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

# Handoff API

> Retrieve conversation context and metadata when PolyAI agents hand off to live agents or external systems.

The Handoff API allows downstream platforms to retrieve structured context and metadata when conversations are handed off from PolyAI agents. Use it to enable routing decisions, screen-pops for live agents, and CRM integration.

This endpoint is typically used to support:

* routing decisions
* screen-pops for live agents
* attaching metadata to tickets or workflow systems
* passing through identifiers collected earlier in the call

## What the API returns

A successful response provides:

* `id` – the PolyAI conversation ID
* `shared_id` – an integrator-defined identifier, if one was stored
* `data` – a free-form JSON object containing the handoff metadata written by the agent

The data field may contain:

* customer identifiers
* reasons for handoff
* queue or routing hints
* arbitrary key–value pairs describing caller state

This API is one of three ways the agent passes context to a human at handoff. For SIP headers and Conversations API alternatives, see [Handoff context handover](/call-handoff/introduction#handoff-context-handover).

## Regional base URLs

| Region | Base URL                                                                       |
| -----: | ------------------------------------------------------------------------------ |
|     US | [https://api.us-1.platform.polyai.app](https://api.us-1.platform.polyai.app)   |
|     UK | [https://api.uk-1.platform.polyai.app](https://api.uk-1.platform.polyai.app)   |
|    EUW | [https://api.euw-1.platform.polyai.app](https://api.euw-1.platform.polyai.app) |

Full endpoint structure:

`https://api.{region}.platform.polyai.app/v1/{account_id}/{project_id}/handoff_state`

You must supply either:

* `id` (PolyAI conversation ID), or
* `shared_id` (a custom ID you passed into the system)

If both are supplied, shared\_id takes precedence.

## Authentication

The Handoff API uses API key authentication with the x-api-key header.
API keys are scoped to account, project, and region. Your PolyAI representative will confirm which key is configured for handoff retrieval.

## Typical flow

A downstream platform receives an inbound call that has just transitioned from the PolyAI agent. It queries the handoff state, then uses the data to populate the agent desktop, route the interaction, or enrich CRM entries.

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET \
    "https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/handoff_state?id=CONV-1234567890" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/handoff_state",
      headers={"x-api-key": "YOUR_API_KEY"},
      params={"id": "CONV-1234567890"},
  )
  handoff = response.json()
  print(handoff["data"])  # Free-form handoff metadata
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({ id: "CONV-1234567890" });

  const res = await fetch(
    `https://api.us-1.platform.polyai.app/v1/ACCOUNT-xxx/PROJECT-xxx/handoff_state?${params}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  const handoff = await res.json();
  console.log(handoff.data); // Free-form handoff metadata
  ```
</CodeGroup>

The endpoint is read-only and returns exactly the state stored by the PolyAI agent at the moment of handoff.