Handoff API

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

Which fields actually appear here depends on your project’s configuration — see Before you start. 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.

Before you start

This endpoint only returns data for conversations where the agent has been configured to expose handoff fields (for example, a call summary, verification status, or routing hint) into the data object. Setting up which fields get exposed is not yet self-serve — contact your PolyAI representative to configure this for your project before integrating against this endpoint.

If the agent isn’t configured to expose any handoff data, this endpoint returns 404 conversation not found — the same response returned when the id or shared_id doesn’t exist at all. If you’re getting a 404 for a conversation you can otherwise see in Conversation Review, confirm with your PolyAI representative that handoff fields are configured before assuming the ID passed to this endpoint is wrong.

Regional base URLs

Region	Base URL
US	https://api.us-1.platform.polyai.app
UK	https://api.uk-1.platform.polyai.app
EUW	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.

Identifiers

account_id above is your account ID — Agent Studio’s UI calls this the Workspace ID and shows it prefixed (ws-xxxxxxxx). project_id is the same value as the Agent ID shown in Agent Studio (prefixed PROJECT-xxxxxxxx); “Project” is the legacy term for the same resource. Both the slug form from the Agent Studio URL and the prefixed form work in API calls.

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.

curl -X GET \
  "https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/PROJECT-xxx/handoff_state?id=CONV-1234567890" \
  -H "x-api-key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/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

const params = new URLSearchParams({ id: "CONV-1234567890" });

const res = await fetch(
  `https://api.<region>.platform.polyai.app/v1/ws-xxxxxxxx/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

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

API reference

Models

Build & deploy

Runtime & data

Monitoring

Legacy

What the API returns

Before you start

Regional base URLs

Authentication

Identifiers

Typical flow

​What the API returns

​Before you start

​Regional base URLs

​Authentication

​Identifiers

​Typical flow

What the API returns

Before you start

Regional base URLs

Authentication

Identifiers

Typical flow