Skip to main content
Attach or assign phone numbers to voice agents to enable inbound and outbound calling capabilities. This endpoint allows you to connect phone numbers from various telephony providers to your voice agents.

​
API Endpoint

Endpoint: POST /api/agent/attach-phone-number Content-Type: application/json Authentication: Required (Token header: token or api_access_token)

​
Request Body

{
  "agent_id": "agent_abc123xyz",
  "provider": "san",
  "numbers": ["+918062810341"]
}

​
Request Parameters

ParameterTypeRequiredDescription
agent_idstringYesUnique identifier of the voice agent
providerstringYesTelephony provider name (see supported providers below)
numbersarrayYesPhone numbers in E.164 format (e.g., ["+918062810341"]). Provide one or more numbers.

​
Supported Providers

ProviderValueDescription
San SoftwaresanSan Software telephony platform
OzonetellozonetellOzonetell cloud communication platform
TwiliotwilioGlobal cloud communications platform
ExotelexotelLeading cloud telephony provider in India
TelnyxtelnyxGlobal carrier network provider
VonagevonageCloud communications platform
PlivoplivoCloud communications platform
BandwidthbandwidthEnterprise communications platform

​
Request Examples

​
cURL

# Attach San Software number to agent
curl -X POST "https://www.tryunleashx.com/api/agent/attach-phone-number" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_AUTH_TOKEN" \
  -d '{
    "agent_id": "agent_abc123xyz",
    "provider": "san",
    "numbers": ["+918062810341"]
  }'

# Attach Twilio number to agent
curl -X POST "https://www.tryunleashx.com/api/agent/attach-phone-number" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_AUTH_TOKEN" \
  -d '{
    "agent_id": "agent_abc123xyz",
    "provider": "twilio",
    "numbers": ["+12025551234"]
  }'

# Attach Exotel number to agent
curl -X POST "https://www.tryunleashx.com/api/agent/attach-phone-number" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_AUTH_TOKEN" \
  -d '{
    "agent_id": "agent_abc123xyz",
    "provider": "exotel",
    "numbers": ["+919876543210"]
  }'

​
PHP

<?php
$url = "https://www.tryunleashx.com/api/agent/attach-phone-number";

$data = [
    "agent_id" => "agent_abc123xyz",
    "provider" => "san",
    "numbers" => ["+918062810341"]
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n" .
                     "token: YOUR_AUTH_TOKEN\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result);

print_r($response);
?>

​
Response

​
Success Response

Status Code: 200 OK 
{
  "error": false,
  "code": 200,
  "message": "Phone number attached successfully",
  "timestamp": 1769244619292,
  "data": {
    "agent_id": "agent_abc123xyz",
    "phone_numbers": ["+918062810341"],
    "provider": "san",
    "attached_at": "2026-01-24T10:30:19Z",
    "status": "active"
  }
}

​
Response Fields

FieldTypeDescription
errorbooleanIndicates if there was an error (false for success)
codeintegerHTTP status code
messagestringSuccess or error message
timestampintegerUnix timestamp in milliseconds
dataobjectResponse data object
data.agent_idstringID of the agent
data.phone_numbersarrayAttached phone numbers in E.164 format
data.providerstringTelephony provider
data.attached_atstringISO 8601 timestamp of attachment
data.statusstringStatus of the phone number (active, pending, inactive)

​
Error Responses

​
400 - Bad Request

Status Code: 400 Bad Request 
{
  "error": true,
  "code": 400,
  "message": "Invalid phone number format. Use E.164 format (e.g., +918062810341)",
  "data": {}
}
Common error messages:
  • "Agent ID is required"
  • "Provider is required"
  • "Phone number(s) are required"
  • "Invalid phone number format. Use E.164 format"
  • "Phone number is already attached to another agent"
  • "Provider not configured for your account"

​
401 - Authentication Error

Status Code: 401 Unauthorized 
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}

​
404 - Agent Not Found

Status Code: 404 Not Found 
{
  "error": true,
  "code": 404,
  "message": "Agent not found",
  "data": {}
}

​
409 - Conflict

Status Code: 409 Conflict 
{
  "error": true,
  "code": 409,
  "message": "Phone number already attached to agent: agent_xyz789abc",
  "data": {
    "existing_agent_id": "agent_xyz789abc",
    "phone_number": "+918062810341"
  }
}

​
422 - Validation Error

Status Code: 422 Unprocessable Entity 
{
  "error": true,
  "code": 422,
  "message": "Invalid provider. Supported providers: san, ozonetell, twilio, exotel, telnyx, vonage",
  "data": {}
}

​
500 - Server Error

Status Code: 500 Internal Server Error 
{
  "error": true,
  "code": 500,
  "message": "Internal server error",
  "data": {}
}

​
Phone Number Format

Phone numbers must be in E.164 format:
FormatExampleDescription
E.164+918062810341International format with + prefix, country code, and number
❌ Invalid918062810341Missing + prefix
❌ Invalid(918) 062-810341Contains special characters
❌ Invalid+91 8062 810341Contains spaces

​
E.164 Format Examples by Country

CountryCountry CodeExample
India+91+918062810341
United States+1+12025551234
United Kingdom+44+442012345678
Australia+61+61212345678
Canada+1+14165551234
Singapore+65+6512345678
UAE+971+971501234567

​
Usage Examples

Examples are provided above for cURL and PHP. Client library code examples (JavaScript/Python) have been removed — use the cURL examples as the canonical requests (send numbers as an array of E.164 strings).

​
Important Notes

  1. Phone Number Format: Always use E.164 format with the + prefix, country code, and number without spaces or special characters.
  2. Provider Configuration: Ensure the telephony provider is properly configured in your account before attaching numbers.
  3. Number Availability: Use the List Phone Numbers API to check available numbers before attaching.
  4. One Number, One Agent: A phone number can only be attached to one agent at a time. Attempting to attach an already-used number will result in a 409 Conflict error.
  5. Multiple Numbers: You can attach multiple phone numbers to a single agent for load balancing or regional coverage.
  6. Number Purpose: Numbers with specific purposes (TEST, PRODUCTION) should be used accordingly to avoid mixing test and production traffic.
  7. Detaching Numbers: To detach a number and attach it to a different agent, first detach it from the current agent or use the update agent endpoint.
  8. Inbound Calls: Once attached, the phone number will route inbound calls to the specified agent automatically.
  9. Webhooks: Ensure your agent has proper webhook configurations to handle call events.
  10. Provider Limits: Some providers may have limits on the number of concurrent calls per number. Check your provider’s documentation.

​
Workflow Integration

​
Complete Agent Setup with Phone Number

// 1. Create Agent
const createAgent = async () => {
  const response = await fetch('https://www.tryunleashx.com/api/agents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      agent_name: 'Support Agent',
      prompt: 'You are a helpful support agent.',
      voice: {
        provider: 'elevenlabs',
        voice_id: 'RXe6OFmxoC0nlSWpuCDy'
      }
    })
  });
  return await response.json();
};

// 2. Attach Phone Number
const attachPhone = async (agentId) => {
  const response = await fetch('https://www.tryunleashx.com/api/agent/attach-phone-number', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'token': 'YOUR_AUTH_TOKEN'
    },
    body: JSON.stringify({
      agent_id: agentId,
      provider: 'san',
      phone_number: '+918062810341'
    })
  });
  return await response.json();
};

// 3. Complete setup
const setupAgent = async () => {
  const agent = await createAgent();
  console.log('Agent created:', agent.id);
  
  const attachment = await attachPhone(agent.id);
  console.log('Phone attached:', attachment.data.phone_number);
  
  console.log('Agent is ready to receive calls!');
};

setupAgent();