---
title: "SIP Addresses"
description: "Register one-time SIP URIs for calls, and manage permanent SIP endpoints that route to an agent."
---

Reach an agent over SIP without a phone number. For how and when to use each
kind, see [Connect over SIP](/guides/sip-addresses).

## 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.

## List and get SIP endpoints

`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.