Assign Number to Trunk

POST

api

Account

{auth_id}

numbers

{phone_number}

assign

Assign Number to Trunk

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "trunk_group_id": "e3e55a78-1234-5678-90ab-cdef12345678"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign"

payload = { "trunk_group_id": "e3e55a78-1234-5678-90ab-cdef12345678" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({trunk_group_id: 'e3e55a78-1234-5678-90ab-cdef12345678'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign

Use this endpoint to assign a phone number to a specific SIP trunk. Once assigned, all inbound calls to that phone number are routed through the designated trunk according to your trunk’s configuration.

Authentication required:

X-Auth-ID - Your account Auth ID
X-Auth-Token - Your account Auth Token
Content-Type: application/json

Important: The phone number must already be in your account inventory. You can purchase numbers using the Purchase Number endpoint before assigning them to a trunk.

URL Encoding Notice: Always encode the phone number in the URL. Use %2B instead of the + symbol. For example: %2B912271264217 (not +912271264217). Failure to encode properly may result in a 404 error.

URL Parameters

Field	Type	Required	Description
`auth_id`	string	Yes	Your unique Vobiz account identifier (e.g., `MA_BN2MZ1VV`). Must match your `X-Auth-ID` header.
`PHONE_NUMBER`	string	Yes	Phone number to assign, URL-encoded. Use `%2B` instead of `+` (e.g., `%2B912271264217`).

Request Body

Field	Type	Required	Description
`trunk_group_id`	string (UUID)	Yes	UUID of the trunk to assign this phone number to (e.g., `e3e55a78-1234-5678-90ab-cdef12345678`).

Request Body Example

{
  "trunk_group_id": "aabbccdd-1234-5678-90ab-cdef12345678"
}

Examples

curl -X POST "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/%2B1234567890/assign" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "trunk_group_id": "{trunk_id}"
  }'

curl -X POST "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "trunk_group_id": "{trunk_id}"
  }'

Response

On successful assignment, the API returns 204 No Content with no response body. Verify the assignment by retrieving the trunk or listing your numbers.

Success Response - 204 No Content

HTTP/1.1 204 No Content

Error Responses

Error Response - 404 Not Found (Number not in inventory)

{
  "error": "Number not found",
  "message": "The phone number could not be found. Ensure it is in your inventory and URL-encoded correctly."
}

Error Response - 400 Bad Request (Number already assigned)

{
  "error": "invalid request",
  "message": "This number is already assigned to a trunk."
}

Reassigning a number. If a number is already assigned to a trunk, the assign call returns 400. Unassign it first with Unassign Number, then assign it to the new trunk.

Quick Tips:

Success Code: Look for 204 No Content (empty body) - the call succeeded.
URL Encoding: Always use %2B instead of + in the phone number.
Body field: The trunk UUID goes in trunk_group_id, not trunk_id.
Number Format: Use E.164 with country code (e.g., +1234567890), URL-encoded.

Next Steps:

Verify the assignment by retrieving your trunk details
Configure your trunk’s inbound routing rules
Test inbound calls to the assigned number
To remove the assignment, use the Unassign Number endpoint

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

phone_number

string

required

The phone number to assign, URL-encoded (use %2B instead of +).

Example:

"%2B912271264217"

Body

application/json

trunk_group_id

string<uuid>

required

The UUID of the trunk to assign this number to.

Example:

"e3e55a78-1234-5678-90ab-cdef12345678"

Response

Number assigned to trunk

Assign Number to Trunk

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "trunk_group_id": "e3e55a78-1234-5678-90ab-cdef12345678"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign"

payload = { "trunk_group_id": "e3e55a78-1234-5678-90ab-cdef12345678" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({trunk_group_id: 'e3e55a78-1234-5678-90ab-cdef12345678'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{phone_number}/assign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

​URL Parameters

​Request Body

​Examples

​Response

​Error Responses

Authorizations

Path Parameters

Body

Response

URL Parameters

Request Body

Examples

Response

Error Responses