Attach Phone Number

Attach phone numbers to an agent

curl --request POST \
  --url https://www.tryunleashx.com/api/v1/global/attach-phone-numbers \
  --header 'Content-Type: application/json' \
  --header 'token: <token>' \
  --data '
{
  "agent_id": 123,
  "numbers": [
    "+12025551234"
  ]
}
'

import requests

url = "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers"

payload = {
    "agent_id": 123,
    "numbers": ["+12025551234"]
}
headers = {
    "token": "<token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agent_id: 123, numbers: ['+12025551234']})
};

fetch('https://www.tryunleashx.com/api/v1/global/attach-phone-numbers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => 123,
    'numbers' => [
        '+12025551234'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "token: <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers"

	payload := strings.NewReader("{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("token", "<token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.tryunleashx.com/api/v1/global/attach-phone-numbers")
  .header("token", "<token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.tryunleashx.com/api/v1/global/attach-phone-numbers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["token"] = '<token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "data": {
    "agent_id": 123,
    "phone_numbers": [
      "<string>"
    ]
  }
}

POST

attach-phone-numbers

Attach phone numbers to an agent

curl --request POST \
  --url https://www.tryunleashx.com/api/v1/global/attach-phone-numbers \
  --header 'Content-Type: application/json' \
  --header 'token: <token>' \
  --data '
{
  "agent_id": 123,
  "numbers": [
    "+12025551234"
  ]
}
'

import requests

url = "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers"

payload = {
    "agent_id": 123,
    "numbers": ["+12025551234"]
}
headers = {
    "token": "<token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({agent_id: 123, numbers: ['+12025551234']})
};

fetch('https://www.tryunleashx.com/api/v1/global/attach-phone-numbers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => 123,
    'numbers' => [
        '+12025551234'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "token: <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.tryunleashx.com/api/v1/global/attach-phone-numbers"

	payload := strings.NewReader("{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("token", "<token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.tryunleashx.com/api/v1/global/attach-phone-numbers")
  .header("token", "<token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.tryunleashx.com/api/v1/global/attach-phone-numbers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["token"] = '<token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": 123,\n  \"numbers\": [\n    \"+12025551234\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "data": {
    "agent_id": 123,
    "phone_numbers": [
      "<string>"
    ]
  }
}

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

Parameter	Type	Required	Description
`agent_id`	string	Yes	Unique identifier of the voice agent
`provider`	string	Yes	Telephony provider name (see supported providers below)
`numbers`	array	Yes	Phone numbers in E.164 format (e.g., `["+918062810341"]`). Provide one or more numbers.

Supported Providers

Provider	Value	Description
San Software	`san`	San Software telephony platform
Ozonetell	`ozonetell`	Ozonetell cloud communication platform
Twilio	`twilio`	Global cloud communications platform
Exotel	`exotel`	Leading cloud telephony provider in India
Telnyx	`telnyx`	Global carrier network provider
Vonage	`vonage`	Cloud communications platform
Plivo	`plivo`	Cloud communications platform
Bandwidth	`bandwidth`	Enterprise 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

Field	Type	Description
`error`	boolean	Indicates if there was an error (false for success)
`code`	integer	HTTP status code
`message`	string	Success or error message
`timestamp`	integer	Unix timestamp in milliseconds
`data`	object	Response data object
`data.agent_id`	string	ID of the agent
`data.phone_numbers`	array	Attached phone numbers in E.164 format
`data.provider`	string	Telephony provider
`data.attached_at`	string	ISO 8601 timestamp of attachment
`data.status`	string	Status 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:

Format	Example	Description
E.164	`+918062810341`	International format with + prefix, country code, and number
❌ Invalid	`918062810341`	Missing + prefix
❌ Invalid	`(918) 062-810341`	Contains special characters
❌ Invalid	`+91 8062 810341`	Contains spaces

E.164 Format Examples by Country

Country	Country Code	Example
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

Phone Number Format: Always use E.164 format with the + prefix, country code, and number without spaces or special characters.
Provider Configuration: Ensure the telephony provider is properly configured in your account before attaching numbers.
Number Availability: Use the List Phone Numbers API to check available numbers before attaching.
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.
Multiple Numbers: You can attach multiple phone numbers to a single agent for load balancing or regional coverage.
Number Purpose: Numbers with specific purposes (TEST, PRODUCTION) should be used accordingly to avoid mixing test and production traffic.
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.
Inbound Calls: Once attached, the phone number will route inbound calls to the specified agent automatically.
Webhooks: Ensure your agent has proper webhook configurations to handle call events.
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();

List Phone Numbers - Get available phone numbers
Create Voice Agent - Create a new voice agent
Update Voice Agent - Update agent configuration
List Voice Agents - View all agents
Make Call - Make outbound calls with your agent

Headers

token

string

required

API token for authentication

Body

application/json

agent_id

integer

required

ID of the agent to attach phone numbers to

numbers

string[]

required

Phone numbers to attach to the agent. Must include country code with + prefix (e.g., '+1234567890'). Provide one or more numbers.

Minimum array length: 1

Response

Numbers attached successfully

success

boolean

message

string

data

object

Show child attributes

API Documentation

Phone Numbers

Voice AI

Click to Call

Call Logs

Campaigns

Users

Attach Phone Number

API Endpoint

Request Body

Request Parameters

Supported Providers

Request Examples

cURL

PHP

Response

Success Response

Response Fields

Error Responses

400 - Bad Request

401 - Authentication Error

404 - Agent Not Found

409 - Conflict

422 - Validation Error

500 - Server Error

Phone Number Format

E.164 Format Examples by Country

Usage Examples

Important Notes

Workflow Integration

Complete Agent Setup with Phone Number

Headers

Body

Response

​API Endpoint

​Request Body

​Request Parameters

​Supported Providers

​Request Examples

​cURL

​PHP

​Response

​Success Response

​Response Fields

​Error Responses

​400 - Bad Request

​401 - Authentication Error

​404 - Agent Not Found

​409 - Conflict

​422 - Validation Error

​500 - Server Error

​Phone Number Format

​E.164 Format Examples by Country

​Usage Examples

​Important Notes

​Workflow Integration

​Complete Agent Setup with Phone Number

​Related Endpoints

Headers

Body

Response

API Endpoint

Request Body

Request Parameters

Supported Providers

Request Examples

cURL

PHP

Response

Success Response

Response Fields

Error Responses

400 - Bad Request

401 - Authentication Error

404 - Agent Not Found

409 - Conflict

422 - Validation Error

500 - Server Error

Phone Number Format

E.164 Format Examples by Country

Usage Examples

Important Notes

Workflow Integration

Complete Agent Setup with Phone Number

Related Endpoints