Phone numbers and SIP trunks

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.

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

Create the inbound trunk

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

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"]
  }'

Bind a number to it

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

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
  }'

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.

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.

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 or a campaign.

Reference

Resource	Endpoints
Phone numbers	List, create, get, update, delete
Inbound SIP trunks	List, create, get, update, delete, activate
Outbound SIP trunks	List, create, get, update, delete

Get started

Voice AI

Support and chat

SDKs

Take calls from your SIP trunk

Call out through your SIP provider

Reference