Skip to main content
The DNI API allows your systems to reserve a Dynamic Number Insertion (DNI) number that routes callers directly to a PolyAI virtual agent while supplying additional contextual data. These attributes are consumed at call start and can be used to personalise call flows, pre-populate state, or identify the caller before dialogue begins. DNI is typically used in marketing, CRM, and web-to-call integrations where a temporary number encodes context about the user journey.

​
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/dni-reservation

​
Authentication

The DNI API uses API-key authentication, supplied via 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/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.