> ## Documentation Index
> Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone numbers and SIP trunks

> Bring your own numbers and SIP infrastructure to Clarity voice agents with the Voice API.

A **phone number** is where calls reach a project and where agents call out from. A number comes either from a carrier (`provider`) or from your own SIP infrastructure through an **inbound SIP trunk** (`sip_trunk_id`), never both. To place outbound calls through your own SIP provider, assign the number one or more **outbound SIP trunks**.

Every request below uses your organization API key. See [Authentication](https://docs.support.onclarity.com/authentication.md).

> [!NOTE]
>
> Creating, changing, activating and deleting numbers and trunks changes what live calls do, so it needs the publish permission. Organization API keys have it. Which agent answers an inbound number is set in Clarity, under the number's routing.

## Take calls from your SIP trunk

**1. Create the inbound trunk**

List the IP ranges your SIP infrastructure sends calls from. The trunk starts `inactive`.

```bash theme={null}
curl -X POST "https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/telephony/sip-trunks" \
  -H "Authorization: Bearer $CLARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main PBX",
    "whitelist_cidrs": ["203.0.113.0/24"]
  }'
```

**2. Bind a number to it**

`e164` is the number in E.164 form as digits, with no `+`.

```bash theme={null}
curl -X POST "https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/phone-numbers" \
  -H "Authorization: Bearer $CLARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "e164": "14155550123",
    "sip_trunk_id": "'"$TRUNK_ID"'",
    "voice_inbound": true
  }'
```

**3. Activate the trunk**

Activation needs at least one bound number and answers `409` otherwise. It is safe to repeat: on an active trunk it repairs the call routing and changes nothing else.

```bash theme={null}
curl -X POST "https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/telephony/sip-trunks/$TRUNK_ID/activate" \
  -H "Authorization: Bearer $CLARITY_API_KEY"
```

Numbers you add to an active trunk later take calls straight away.

Deleting a trunk keeps its numbers, unassigned, unless you pass `delete_numbers=true`.

## Call out through your SIP provider

Create an outbound trunk, then list it on the number with `outbound_trunk_ids`. The first trunk is the primary and up to four more are fallbacks. The number needs `voice_outbound: true`.

```bash theme={null}
curl -X POST "https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/telephony/outbound-trunks" \
  -H "Authorization: Bearer $CLARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carrier A",
    "address": "sip.example.com",
    "auth": { "type": "basic", "username": "clarity", "password": "'"$SIP_PASSWORD"'" }
  }'
```

The password is write-only: responses show `has_secret` instead. Leave `password` out of an update to keep the stored one.

Outbound calls themselves are placed with [dispatch a call](https://docs.support.onclarity.com/voice/outbound-calls.md) or a [campaign](https://docs.support.onclarity.com/voice/campaigns.md).

## Reference

| Resource | Endpoints |
| - | - |
| Phone numbers | [List](https://docs.support.onclarity.com/api-reference/voice/phone-numbers/list-phone-numbers.md), [create](https://docs.support.onclarity.com/api-reference/voice/phone-numbers/create-a-phone-number.md), [get](https://docs.support.onclarity.com/api-reference/voice/phone-numbers/get-a-phone-number.md), [update](https://docs.support.onclarity.com/api-reference/voice/phone-numbers/update-a-phone-number.md), [delete](https://docs.support.onclarity.com/api-reference/voice/phone-numbers/delete-a-phone-number.md) |
| Inbound SIP trunks | [List](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/list-inbound-sip-trunks.md), [create](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/create-an-inbound-sip-trunk.md), [get](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/get-an-inbound-sip-trunk.md), [update](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/update-an-inbound-sip-trunk.md), [delete](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/delete-an-inbound-sip-trunk.md), [activate](https://docs.support.onclarity.com/api-reference/voice/inbound-sip-trunks/activate-an-inbound-sip-trunk.md) |
| Outbound SIP trunks | [List](https://docs.support.onclarity.com/api-reference/voice/outbound-sip-trunks/list-outbound-sip-trunks.md), [create](https://docs.support.onclarity.com/api-reference/voice/outbound-sip-trunks/create-an-outbound-sip-trunk.md), [get](https://docs.support.onclarity.com/api-reference/voice/outbound-sip-trunks/get-an-outbound-sip-trunk.md), [update](https://docs.support.onclarity.com/api-reference/voice/outbound-sip-trunks/update-an-outbound-sip-trunk.md), [delete](https://docs.support.onclarity.com/api-reference/voice/outbound-sip-trunks/delete-an-outbound-sip-trunk.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.