> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reddy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Call Handoff

> Retrieves call-handoff metadata collected by Reddy during a voice call.

Retrieves the metadata record identified by `handoff_id`. Reddy creates this
record when a voice call starts and writes metadata to it incrementally while
the call is in progress. When the call wraps up, Reddy finalizes the record:
`final` flips to `true`, `finalized_at` is set, and the metadata becomes
immutable.

<Warning>
  **Always check the `final` flag before consuming the metadata.** While
  `final` is `false`, the record is still being written: keys may be missing
  entirely or carry intermediate values that will change. Only treat the
  metadata as complete and authoritative once `final` is `true`. If you fetch
  the record and `final` is still `false`, retry after a short delay (or wait
  for your handoff trigger) instead of consuming the partial data.
</Warning>

The `handoff_id` is a UUID minted by Reddy for a single call handoff. Supply
it from whatever integration path your account is set up with; delivery of
the id alongside the transferred call itself is being rolled out separately,
so confirm with your Reddy contact how your systems will receive it.

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://app.reddy.io/api/v1/call-handoff/6f1b24a0-8c2d-4a4e-9d64-2f6a1f0c3b7e' \
    -H 'Authorization: Bearer your_api_key'
  ```
</RequestExample>

<ResponseExample>
  ```json Finalized (safe to consume) theme={null}
  {
    "handoff_id": "6f1b24a0-8c2d-4a4e-9d64-2f6a1f0c3b7e",
    "final": true,
    "metadata": {
      "customer_intent": "cancel_service",
      "account_number": "A-10293",
      "sentiment": "frustrated",
      "summary": "Customer wants to cancel due to billing issues."
    },
    "created_at": "2026-08-04T14:03:11Z",
    "updated_at": "2026-08-04T14:09:42Z",
    "finalized_at": "2026-08-04T14:09:42Z"
  }
  ```

  ```json Still partial (do NOT consume yet) theme={null}
  {
    "handoff_id": "6f1b24a0-8c2d-4a4e-9d64-2f6a1f0c3b7e",
    "final": false,
    "metadata": {
      "customer_intent": "cancel_service"
    },
    "created_at": "2026-08-04T14:03:11Z",
    "updated_at": "2026-08-04T14:05:20Z",
    "finalized_at": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/call-handoff/{handoff_id}
openapi: 3.1.0
info:
  title: Reddy API
  version: 1.0.0
  description: ''
servers: []
security: []
paths:
  /api/v1/call-handoff/{handoff_id}:
    get:
      tags:
        - Call Handoff
      summary: Get Call Handoff
      description: |-
        Retrieve call-handoff metadata by its handoff id.

        The record is written incrementally during the call, so the metadata
        may be PARTIAL until `final` is true. Always check the `final` flag
        before consuming the data; poll again (or wait for your handoff
        trigger) if it is still false.
      operationId: api_standard_api_call_handoff_get_call_handoff
      parameters:
        - in: path
          name: handoff_id
          schema:
            format: uuid
            title: Handoff Id
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallHandoffSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - AuthBearer: []
components:
  schemas:
    CallHandoffSchema:
      properties:
        handoff_id:
          description: Unique identifier of the handoff record
          title: Handoff Id
          type: string
        final:
          description: >-
            True once the record is finalized and immutable. While false, the
            metadata is still being written and may be partial -- always check
            this flag before consuming the data.
          title: Final
          type: boolean
        metadata:
          additionalProperties: true
          description: >-
            Key/value metadata collected during the call. Only complete and safe
            to consume once 'final' is true.
          title: Metadata
          type: object
        created_at:
          description: When the handoff record was created
          format: date-time
          title: Created At
          type: string
        updated_at:
          description: When the record was last updated
          format: date-time
          title: Updated At
          type: string
        finalized_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the record was finalized, or null while still partial
          title: Finalized At
      required:
        - handoff_id
        - final
        - metadata
        - created_at
        - updated_at
        - finalized_at
      title: CallHandoffSchema
      type: object
    ErrorResponse:
      properties:
        error:
          title: Error
          type: string
      required:
        - error
      title: ErrorResponse
      type: object
  securitySchemes:
    AuthBearer:
      type: http
      scheme: bearer

````