Skip to main content
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

​
Regional base URLs

RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-1.platform.polyai.app
EUWhttps://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. 
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"
The endpoint is read-only and returns exactly the state stored by the PolyAI agent at the moment of handoff.
Last modified on April 20, 2026