> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Claim a customer or a task > An ownership claim (`owner`, `case`) on the customer or a task lock on an object, for a lease; refused with 409 while another holder has a claim at least as restrictive. An observation from your worker is never refused. ## OpenAPI ````yaml openapi/en/cell.json POST /v1/coordination/claims openapi: 3.1.0 info: title: Niadra data API version: '1' description: >- Writing, context, history, objects, identity, privacy and governance of one space. Every space has a stable address, with the space and the region in its name. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: The space, which comes in the source key. region: default: us-east-2 description: The region of the space, which also comes in the key. security: [] paths: /v1/coordination/claims: post: tags: - coordination summary: Claim a customer or a task description: >- Declares a claim on the customer (`owner` or `case`, at a level of the space, for a lease) or a task lock on a business object. The most restrictive valid claim holds the target; a declaration is refused while another holder's claim is at least as restrictive (409 `lease_held`), and the same holder renews its own. With `source`, it is an observation the company's worker read from one of the space's ownership sources: never refused, it replaces what that source said before, capped by the source's validity. **Authentication.** Source key: `Authorization: Bearer nia_sk_...`. Required scope: `coordinate`. It answers only in a space with the `coordination` feature on (the `features` document); in a space without it, 404. operationId: claim_v1_coordination_claims_post parameters: - in: header name: Idempotency-Key required: true schema: maxLength: 256 minLength: 1 title: Idempotency-Key type: string description: >- Required. Kept 24 hours with the hash of the body: a retry with the same key returns the first answer, and the same key with a different body returns 409 `conflict`. requestBody: content: application/json: schema: $ref: '#/components/schemas/ClaimRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/OwnershipClaim' description: The claim, with the epoch a release must name. '409': description: '`lease_held`, with the holder and until when.' '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The request does not match the contract. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: >- # Hold the customer while this agent works the case; another holder's stricter claim wins claimed = conversation.claim(kind="case", lease_s=600, intents=["proposal_followup"]) if not claimed.held: print(claimed.error) # lease_held, task_locked, or Niadra did not answer - lang: typescript label: TypeScript source: >- // Hold the customer while this agent works the case; another holder's stricter claim wins const claimed = await convo.claim({ kind: "case", leaseS: 600, intents: ["proposal_followup"] }); if (!claimed.held) console.log(claimed.error); // lease_held, task_locked, or Niadra did not answer components: schemas: ClaimRequest: additionalProperties: false description: >- A declared claim, held by `holder`. `level` defaults to the space's least restrictive level; a declaration is refused (409 `lease_held`) while another holder's claim is at least as restrictive, and the same holder renews its own. `lease_s` is capped by the space's longest declared lease. A task lock names an object and its `task`, and is refused (409 `task_locked`) while another holder has that task. properties: holder: maxLength: 256 minLength: 1 title: Holder type: string intents: items: pattern: ^[a-z][a-z0-9_]{0,39}$ type: string maxItems: 20 title: Intents type: array kind: $ref: '#/components/schemas/ClaimKind' lease_s: maximum: 86400 minimum: 1 title: Lease S type: integer level: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' title: Level object: anyOf: - $ref: '#/components/schemas/ObjectRef' - type: 'null' observed_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the source saw it; an observation older than the source's last is ignored. title: Observed At source: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' description: >- An observation of this ownership source, read and sent by the company's worker: never refused, replacing what the source said before, and capped by the source's validity. title: Source subject: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' task: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' title: Task required: - kind - holder - lease_s title: ClaimRequest type: object OwnershipClaim: additionalProperties: false properties: claim_id: maxLength: 512 minLength: 1 title: Claim Id type: string epoch: title: Epoch type: integer holder: title: Holder type: string kind: $ref: '#/components/schemas/ClaimKind' level: pattern: ^[a-z][a-z0-9_]{0,39}$ title: Level type: string valid_until: format: date-time title: Valid Until type: string required: - claim_id - kind - holder - level - valid_until - epoch title: OwnershipClaim type: object Problem: additionalProperties: false description: RFC 9457 problem details; `code` comes from the versioned error catalog. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object ClaimKind: enum: - owner - case - task_lock title: ClaimKind type: string ObjectRef: additionalProperties: false description: >- A business object in a system of record, e.g. `invoice` / `erp` / `0823`. properties: id: maxLength: 512 minLength: 1 title: Id type: string description: The id in that system. namespace: maxLength: 256 minLength: 1 title: Namespace type: string description: The system it lives in, such as `erp`. type: maxLength: 256 minLength: 1 title: Type type: string description: Object type, such as `invoice`, `order` or `ticket`. required: - type - namespace - id title: ObjectRef type: object Handle: additionalProperties: false description: >- An identifier of a subject in some channel or system: a phone, an e-mail, a CRM id. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Namespace for scoped identifiers: the WhatsApp Business account for `wa_bsuid`, the system for `system_id`, the country for `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: Defaults to `person`, except for organization-only handle types. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- The identifier. Normalized on the server: E.164 for phones, lowercase for e-mail. required: - type - value title: Handle type: object SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- A person, a customer organization (`account`) or an organization that takes part without being a customer (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- The kind of identifier. The value is classified by its format, never by the field it came from. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````