> ## 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.

# Create a handoff

> Hands the customer to another holder with a package compiled at the receiving side's verification level and policy; the customer is held until the outcome.



## OpenAPI

````yaml openapi/en/cell.json POST /v1/handoffs
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/handoffs:
    post:
      tags:
        - coordination
      summary: Create a handoff
      description: >-
        Moves the customer to another holder with a package: the compiled view
        for the receiver at its verification level and policy, who held the
        customer, the open objects, the commitments and promises that hold, the
        effects done or in flight, the suppressions, and how to report the
        outcome. While the outcome is due, the customer is held at the space's
        handoff level, so other agents' outbound contacts wait.


        **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: create_handoff_v1_handoffs_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/HandoffCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handoff'
          description: The handoff, with its package.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request does not match the contract.
      security:
        - sourceKey: []
components:
  schemas:
    HandoffCreate:
      additionalProperties: false
      description: >-
        Hands the subject to `target`. The package is compiled at `level`, the
        verification the receiving

        side has of the subject, so it never carries what that side could not
        read.
      properties:
        agent:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: The agent handing off; the calling key's name when absent.
          title: Agent
        conversation_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Conversation Id
        expected_by:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the outcome is due; the space's default wait when absent.
          title: Expected By
        level:
          $ref: '#/components/schemas/Verification'
          default: V0
        reason:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Reason
        subject:
          $ref: '#/components/schemas/Handle'
        target:
          maxLength: 256
          minLength: 1
          title: Target
          type: string
      required:
        - subject
        - target
      title: HandoffCreate
      type: object
    Handoff:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        expected_by:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Expected By
        handoff_id:
          maxLength: 512
          minLength: 1
          title: Handoff Id
          type: string
        outcome:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Outcome
        package:
          anyOf:
            - $ref: '#/components/schemas/HandoffPackage'
            - type: 'null'
        status:
          enum:
            - created
            - accepted
            - closed
            - expired
          title: Status
          type: string
      required:
        - handoff_id
        - status
        - created_at
      title: Handoff
      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
    Verification:
      description: Session verification levels. `no_customer` sits outside the V0-V4 scale.
      enum:
        - V0
        - V1
        - V2
        - V3
        - V4
        - no_customer
      title: Verification
      type: string
    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
    HandoffPackage:
      additionalProperties: false
      description: >-
        What a handoff carries to whoever receives it (the coordination spec,
        7).
      properties:
        commitments_active:
          items:
            $ref: '#/components/schemas/CommitmentRef'
          title: Commitments Active
          type: array
        context:
          $ref: '#/components/schemas/HandoffContext'
        created_at:
          format: date-time
          title: Created At
          type: string
        effects:
          items:
            $ref: '#/components/schemas/EffectSeen'
          title: Effects
          type: array
        from_agent:
          maxLength: 256
          minLength: 1
          title: From Agent
          type: string
        handoff_id:
          maxLength: 512
          minLength: 1
          title: Handoff Id
          type: string
        level:
          $ref: '#/components/schemas/Verification'
        open_objects:
          items:
            $ref: '#/components/schemas/OpenObject'
          maxItems: 50
          title: Open Objects
          type: array
        outcome:
          $ref: '#/components/schemas/OutcomeRequest'
        owner:
          anyOf:
            - $ref: '#/components/schemas/Owner'
            - type: 'null'
        promises_open:
          items:
            $ref: '#/components/schemas/PromiseRef'
          title: Promises Open
          type: array
        reason:
          anyOf:
            - maxLength: 500
              minLength: 1
              type: string
            - type: 'null'
          title: Reason
        spec:
          const: handoff-package.v0
          default: handoff-package.v0
          title: Spec
          type: string
        subject:
          anyOf:
            - $ref: '#/components/schemas/Handle'
            - type: 'null'
          description: Whom the handoff is about.
        suppressions:
          items:
            pattern: ^[a-z][a-z0-9_]{0,39}$
            type: string
          title: Suppressions
          type: array
        target:
          maxLength: 256
          minLength: 1
          title: Target
          type: string
      required:
        - handoff_id
        - created_at
        - from_agent
        - target
        - level
        - context
      title: HandoffPackage
      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.
    CommitmentRef:
      additionalProperties: false
      properties:
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        type:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Type
          type: string
        valid_until:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Valid Until
      required:
        - id
        - type
      title: CommitmentRef
      type: object
    HandoffContext:
      additionalProperties: false
      description: >-
        The compiled `handoff` view, at the receiving side's policy and
        verification level. `etag` is the

        pack's it was compiled from, absent for a subject the memory knows
        nothing of yet.
      properties:
        etag:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Etag
        policy_version:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Policy Version
        text:
          title: Text
          type: string
      required:
        - text
      title: HandoffContext
      type: object
    EffectSeen:
      additionalProperties: false
      properties:
        effect_id:
          pattern: ^[A-Za-z0-9_-]{43}$
          title: Effect Id
          type: string
        kind:
          $ref: '#/components/schemas/EffectKind'
        state:
          enum:
            - reserved
            - done
            - failed
            - unknown_outcome
          title: State
          type: string
      required:
        - effect_id
        - kind
        - state
      title: EffectSeen
      type: object
    OpenObject:
      additionalProperties: false
      properties:
        ref:
          $ref: '#/components/schemas/ObjectRef'
        since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Since
        state:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: State
      required:
        - ref
      title: OpenObject
      type: object
    OutcomeRequest:
      additionalProperties: false
      description: >-
        How the receiving side reports back: one of `vocabulary`, by
        `expected_by`.
      properties:
        expected_by:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Expected By
        vocabulary:
          items:
            pattern: ^[a-z][a-z0-9_]{0,39}$
            type: string
          maxItems: 50
          title: Vocabulary
          type: array
      title: OutcomeRequest
      type: object
    Owner:
      additionalProperties: false
      description: >-
        Who holds the subject or the object now: the most restrictive valid
        claim, where it came from and

        until when. `epoch` fences a release.
      properties:
        epoch:
          title: Epoch
          type: integer
        holder:
          maxLength: 256
          minLength: 1
          title: Holder
          type: string
        kind:
          $ref: '#/components/schemas/ClaimKind'
        level:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Level
          type: string
        since:
          format: date-time
          title: Since
          type: string
        source:
          maxLength: 256
          minLength: 1
          title: Source
          type: string
        valid_until:
          format: date-time
          title: Valid Until
          type: string
        via:
          $ref: '#/components/schemas/ClaimVia'
      required:
        - holder
        - kind
        - level
        - source
        - via
        - since
        - valid_until
        - epoch
      title: Owner
      type: object
    PromiseRef:
      additionalProperties: false
      properties:
        due:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Due
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        owner:
          maxLength: 256
          minLength: 1
          title: Owner
          type: string
      required:
        - id
        - owner
      title: PromiseRef
      type: object
    EffectKind:
      enum:
        - delivery
        - document
        - notice
        - filing
        - paid_call
        - external_action
      title: EffectKind
      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
    ClaimKind:
      enum:
        - owner
        - case
        - task_lock
      title: ClaimKind
      type: string
    ClaimVia:
      description: >-
        The three ways in: a declaration through the API, an observation mapped
        from a webhook, an observation

        the company's worker read and sent.
      enum:
        - declaration
        - mapping
        - worker
      title: ClaimVia
      type: string
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````