Skip to main content

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.

The DNI API reserves dynamic phone numbers that route directly to your PolyAI agent while supplying contextual attributes at call start. Use it for marketing campaigns, CRM integrations, and web-to-call flows to personalize conversations and attribute conversions. DNI is typically used in marketing, CRM, and web-to-call integrations where a temporary number encodes context about the user journey. The virtual agent is linked to the API key used in the request. When the caller dials the reserved DNI, they are routed to the agent, which can consume the provided attributes. In most cases, the API key for this endpoint is different from the key used for other API endpoints.

​
What the DNI API does

When your system makes a reservation, PolyAI returns a temporary phone number (the DNI). Any caller who dials that number during the active reservation window is automatically routed to the correct agent, with the attached attributes available at the start of the conversation. Common use cases include:
  • Passing shared IDs, customer identifiers, or session tokens
  • Injecting CRM or cart details
  • Associating prior call history
  • Enabling attribution for marketing conversions
  • Supplying metadata for routing or state initialisation
Only one endpoint is exposed: a POST request that reserves the DNI and associates attributes.

​
Regional base URLs

Choose the base URL that matches your PolyAI deployment region:
RegionBase URL
UShttps://api.us-1.platform.polyai.app
UKhttps://api.uk-1.platform.polyai.app
EUWhttps://api.euw-1.platform.polyai.app
The DNI endpoint is: https://api.{region}.platform.polyai.app/v1/conversations/dni-reservation

​
Authentication

The DNI API uses API-key authentication, supplied with the x-api-key header. Each DNI key is tied to a specific virtual agent. Calling the reserved phone number routes directly to that agent and provides the attributes you supplied. DNI API keys are separate from Conversations API keys. In most deployments, the DNI key is unique and used only for this endpoint.

​
Example: Reserve a DNI

POST https://api.{region}.platform.polyai.app/v1/conversations/dni-reservation Send a JSON payload containing any attributes you want associated with the reservation. The response returns a dni value (the temporary phone number). Your attributes become available to the agent as soon as the call begins.
Last modified on April 16, 2026