Configure a Number

Configure how inbound calls to your phone number are handled by assigning it to either a SIP trunk or a voice application.

Configuration Options

Assign to Trunk Route inbound calls through a SIP trunk to your own voice infrastructure (PBX, contact center, etc.).

Assign to Application Route inbound calls to a voice application with programmable call control via webhooks (answer URL, hangup URL, etc.).

Assign to Trunk

Route all inbound calls on this number through a specified SIP trunk.

Endpoint

POST /v1/account/{account_id}/numbers/{e164}/assign

Request Body

Field	Type	Required	Description
trunk_id	string	Yes	ID of the trunk to assign (e.g., "trunk_abc123")

Request Example

curl --request POST \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/assign \
  --header 'Authorization: Bearer tvx_sk_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "trunk_id": "trunk_abc123"
  }'

Response

{
  "e164": "+14155551234",
  "trunk_id": "trunk_abc123",
  "application_id": null,
  "status": "active",
  "updated_at": "2026-04-09T11:15:00Z"
}

Assign to Application

Route all inbound calls on this number to a voice application with webhook URLs.

Endpoint

POST /v1/account/{account_id}/numbers/{e164}/application

Request Body

Field	Type	Required	Description
application_id	string	Yes	ID of the voice application (e.g., "app_xyz789")

Request Example

curl --request POST \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/application \
  --header 'Authorization: Bearer tvx_sk_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "application_id": "app_xyz789"
  }'

Response

{
  "e164": "+14155551234",
  "trunk_id": null,
  "application_id": "app_xyz789",
  "status": "active",
  "updated_at": "2026-04-09T11:20:00Z"
}

Unassign from Trunk

Remove the trunk assignment from a phone number. The number will no longer route inbound calls until reassigned.

Endpoint

DELETE /v1/account/{account_id}/numbers/{e164}/assign

Request Example

curl --request DELETE \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/assign \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "e164": "+14155551234",
  "trunk_id": null,
  "application_id": null,
  "status": "active",
  "updated_at": "2026-04-09T11:25:00Z",
  "message": "Trunk unassigned successfully"
}

Unassign from Application

Remove the application assignment from a phone number. The number will no longer route inbound calls until reassigned.

Endpoint

DELETE /v1/account/{account_id}/numbers/{e164}/application

Request Example

curl --request DELETE \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/application \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "e164": "+14155551234",
  "trunk_id": null,
  "application_id": null,
  "status": "active",
  "updated_at": "2026-04-09T11:30:00Z",
  "message": "Application unassigned successfully"
}

Configuration Notes

A phone number can be assigned to either a trunk OR an application, but not both
Assigning to a trunk will automatically unassign any existing application (and vice versa)
Unassigned numbers will reject inbound calls with a busy signal
Configuration changes take effect immediately

Response Fields

Field	Type	Description
e164	string	Phone number in E.164 format
trunk_id	string	null
application_id	string	null
status	string	Number status (always "active" for configured numbers)
updated_at	string	ISO 8601 timestamp of last configuration change

Error Handling

Common errors:

Error Code	Description
404	Number not found in your account
404	Trunk or application not found
400	Invalid trunk_id or application_id format
403	Insufficient permissions to assign this trunk/application

Next Steps

Learn about SIP Trunking for routing calls to your infrastructure
Explore Voice Applications for programmable call control
List Your Numbers to view all configured numbers

On this page