SIP Trunking API

The SIP Trunking API lets you connect your own telephony platform to PolyAI. It has two parts:

A management REST API to create and configure SIP Trunks and their Extensions, and to place outbound calls over a trunk.
A SIP/RTP interface your telephony system connects to.

A SIP Trunk is an account-level virtual connection that carries voice calls between your telephony platform and PolyAI. It authenticates callers, accepts inbound calls, and holds a list of Extensions that map a dialed number to a specific PolyAI agent.

Resource model

The API is organized around two nested, account-scoped resources:

account
 └── sip-trunk              # virtual connection: CIDRs, transport, inbound auth
      └── extension         # maps a dialed number to a PolyAI agent

Base URL

The API is served from a regional gateway. Use the region your PolyAI account is hosted in:

Region	Base URL
US	`https://api.us.poly.ai`
EU	`https://api.eu.poly.ai`
UK	`https://api.uk.poly.ai`

Every resource is scoped to an account, so all management endpoints are prefixed with /v1/accounts/{account_id}/telephony/….

Do not use https://api.poly.ai without a region prefix — it returns an error. Always include the region.

Authentication

All endpoints authenticate with an API key sent in the X-API-Key header — either an Agent Studio personal access token or an account-level API key.

curl https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks \
  -H "X-API-Key: YOUR_API_KEY"

The key must belong to a user who is an admin on the account named in the request path.

Create a key from the API Keys tab in Agent Studio — see API keys.

Quick start

Create a trunk, map a number to an agent, then point your telephony platform at PolyAI.

1. Create a SIP Trunk

Create an encrypted trunk that authenticates inbound calls with a SIP token:

curl -X POST https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example SIP Trunk",
    "encrypted": true,
    "sip_cidr": ["203.0.113.0/24"],
    "rtp_cidr": ["203.0.113.0/24"],
    "inbound": { "sip_token_auth": { "token": "a-long-random-shared-secret" } }
  }'

{
  "id": "tr-0123456789abcdefghijklmn",
  "account_id": "acct-123",
  "name": "Example SIP Trunk",
  "sip_cidr": ["203.0.113.0/24"],
  "rtp_cidr": ["203.0.113.0/24"],
  "encrypted": true,
  "inbound": {
    "hostname": "tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai",
    "sip_auth": { "enabled": false },
    "sip_token_auth": { "enabled": true }
  },
  "created_at": "2026-07-28T12:00:00Z",
  "updated_at": "2026-07-28T12:00:00Z"
}

The response includes the trunk id and its inbound.hostname — the host your telephony platform connects to.

2. Create an extension

Map a dialed number on the trunk to a PolyAI agent. The extension is the number or extension sent in the Request URI of the SIP INVITE to PolyAI:

curl -X POST https://api.us.poly.ai/v1/accounts/ACCOUNT_ID/telephony/sip-trunks/TRUNK_ID/extensions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "extension": "1000",
    "agent": { "agent_id": "my-agent", "client_env": "live" }
  }'

{
  "extension": "1000",
  "agent": { "agent_id": "my-agent", "client_env": "live", "variant_id": "" },
  "created_at": "2026-07-28T12:00:00Z",
  "updated_at": "2026-07-28T12:00:00Z"
}

Calls dialed to 1000 on this trunk now route to the my-agent agent.

3. Connect your telephony platform

Update your SIP server to route calls to your trunk’s inbound.hostname and to the correct port — for TLS that’s port 5061, e.g. tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai:5061. If using SIP token-based auth, you’ll also need to send a X-PolyAI-SIP-Trunk-Token SIP header on your first SIP INVITE.

INVITE sip:1000@tr-0123456789abcdefghijklmn.sbc.sip.us.poly.ai SIP/2.0
…
X-PolyAI-SIP-Trunk-Token: a-long-random-shared-secret
…

See Connecting to PolyAI Telephony for transport, DNS, and authentication details.

Placing outbound calls

A trunk can also place outbound calls: PolyAI dials a number and connects the answered call to one of your agents. First configure the trunk’s outbound settings — a default_caller_id and the sip_addresses your calls route to — with Update a SIP Trunk. Then call the outbound-call endpoint:

curl -X POST https://api.us.poly.ai/v1/telephony/sip-trunks/TRUNK_ID/outbound-call \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": { "agent_id": "my-agent", "client_env": "live" },
    "to_number": "+447700900123"
  }'

{
  "call_sid": "OUT-3f2a7c9e-1b4d-4e6a-9c8b-2d5f7a1e0c34"
}

Use the returned call_sid to poll the call with Get outbound call status until it reaches success or failure.

Error responses

Status	Description
400	Validation error — check the request body
401	Missing or invalid API key
403	Key is not an admin on the account
404	Resource not found
409	Conflict with the current state of the resource

Example error response

{
  "success": false,
  "error": "short_error_code",
  "message": "Human-readable explanation."
}

Connecting to PolyAI Telephony

Route inbound phone calls into PolyAI over SIP/RTP.

Place an outbound call

Dial a number and connect the call to one of your agents over a trunk.

Outbound calls over PolyAI telephony

Place outbound calls over PolyAI-managed telephony with the Agents API.

Agents API

Build and deploy the agents your extensions route calls to.

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Resource model

Base URL

Authentication

Quick start

1. Create a SIP Trunk

2. Create an extension

3. Connect your telephony platform

Placing outbound calls

Error responses

Example error response

Connecting to PolyAI Telephony

Place an outbound call

Outbound calls over PolyAI telephony

Agents API

​Resource model

​Base URL

​Authentication

​Quick start

​1. Create a SIP Trunk

​2. Create an extension

​3. Connect your telephony platform

​Placing outbound calls

​Error responses

​Example error response

​Related

Connecting to PolyAI Telephony

Place an outbound call

Outbound calls over PolyAI telephony

Agents API

Resource model

Base URL

Authentication

Quick start

1. Create a SIP Trunk

2. Create an extension

3. Connect your telephony platform

Placing outbound calls

Error responses

Example error response

Related