Skip to main content
POST
/
api
/
v1
/
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"
}
'
{
  "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

FieldTypeRequiredDescription
auth_idstringYesYour unique Vobiz account identifier (e.g., MA_BN2MZ1VV). Must match your X-Auth-ID header.
PHONE_NUMBERstringYesPhone number to assign, URL-encoded. Use %2B instead of + (e.g., %2B912271264217).

​
Request Body

FieldTypeRequiredDescription
trunk_group_idstring (UUID)YesUUID 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}"
  }'

​
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