Open in

SIP Addresses

Reach an agent over SIP without a phone number. For how and when to use each kind, see Connect over SIP.

Endpoints

Method	Path	Description
`POST`	`/v1/calls/register-sip`	Register a call and get a one-time SIP URI
`GET`	`/v1/sip-endpoints`	List SIP endpoints
`POST`	`/v1/sip-endpoints`	Create a SIP endpoint (returns its password once)
`GET`	`/v1/sip-endpoints/{id}`	Get a SIP endpoint
`PATCH`	`/v1/sip-endpoints/{id}`	Update name, agent, source-IP allowlist or status
`DELETE`	`/v1/sip-endpoints/{id}`	Delete a SIP endpoint
`POST`	`/v1/sip-endpoints/{id}/rotate-password`	Issue a new password (returned once)

Creating, updating and deleting require an organization API key, or a dashboard session with the admin role or higher.

Register a call

POST /v1/calls/register-sip

Request fields

Field	Type	Required	Description
`agent_id`	integer	yes	Agent in your organization that answers the call
`to_number`	string	no	E.164 number the caller dialed on your side; stored as the call's destination
`variables`	object	no	Values for the agent prompt's `{{placeholders}}`

Response (`201`)

Field	Type	Description
`call_id`	integer	Id the call will have in call history
`sip_uri`	string	One-time SIP URI to dial: `sip:c-<token>@sip.thunderphone.com`. Treat it as a secret until used
`expires_at`	string	When the URI stops working (5 minutes after registration)
`agent_id`	integer	The answering agent
`to_number`	string \| null	The registered destination, if any

The URI works for one call. After that call, or after expires_at, calls to it are refused.

Errors

Status	When
`400`	Unknown agent, `to_number` not in E.164 format, or invalid `variables`
`403`	Dashboard session below the admin role
`503`	SIP addresses are not available in this environment

SIP endpoint object

Field	Type	Description
`id`	integer	Endpoint id
`name`	string	Your label
`agent_id`	integer \| null	Agent that answers calls to the endpoint
`sip_uri`	string	Permanent address: `sip:agent-<id>-<letters>@sip.thunderphone.com`
`username`	string	SIP digest username
`password`	string	Only on create and `rotate-password` responses
`allowed_source_cidrs`	string[]	Source IP ranges allowed to call; empty means any source with valid credentials. Checked for TCP/TLS calls only: an endpoint with an allowlist refuses UDP calls
`status`	string	`active`, `disabled` (calls refused) or `provisioning` (setup in progress or failed; cannot receive calls)
`created_at`	string	Creation time

Create a SIP endpoint

POST /v1/sip-endpoints

Field	Type	Required	Description
`agent_id`	integer	yes	Agent in your organization
`name`	string	no	Label, up to 120 characters
`allowed_source_cidrs`	string[]	no	Up to 50 IPv4/IPv6 addresses or CIDR ranges

Returns 201 with the endpoint object, including password.

allowed_source_cidrs entries are normalized and deduplicated. 0.0.0.0/0 and ::/0 are refused (they are not an allowlist); use [] to allow any source with valid credentials.

Status	When
`400`	Unknown agent, invalid field, or invalid CIDR
`403`	Dashboard session below the admin role
`502`	The address could not be set up. Retry the request
`503`	SIP addresses are not available in this environment

After a 502, create the endpoint again. A leftover endpoint in provisioning never received a password, cannot receive calls and is removed automatically; don't wait for it to become active.

GET /v1/sip-endpoints returns 200 with {"results": [...]}, newest first. GET /v1/sip-endpoints/{id} returns one endpoint; an unknown id, or one in another organization, returns 404. Read responses never include password.

Update a SIP endpoint

PATCH /v1/sip-endpoints/{id} accepts any of name, agent_id, allowed_source_cidrs and status (active or disabled). Returns the endpoint object. Changing the agent or the allowlist takes effect for the next call. Changing status returns 409 while the endpoint is still provisioning.

Rotate the password

POST /v1/sip-endpoints/{id}/rotate-password returns the endpoint object with a new password. The old password stops working immediately.

Delete a SIP endpoint

DELETE /v1/sip-endpoints/{id} returns 204. Calls to the address are refused from then on. Call history is kept. It returns 409 while the endpoint is still provisioning; an endpoint whose setup failed is removed automatically, usually within an hour.