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.

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

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"

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