> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach Phone Number

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

```json theme={null}
{
  "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

```bash theme={null}
# 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 theme={null}
<?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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "error": true,
  "code": 401,
  "message": "Invalid Auth Key or Session Expired",
  "data": {}
}
```

### 404 - Agent Not Found

**Status Code:** `404 Not Found`

```json theme={null}
{
  "error": true,
  "code": 404,
  "message": "Agent not found",
  "data": {}
}
```

### 409 - Conflict

**Status Code:** `409 Conflict`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

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](/api-reference/phone-numbers/list-phone-numbers) 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

```javascript theme={null}
// 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();
```

## Related Endpoints

* [List Phone Numbers](/api-reference/phone-numbers/list-phone-numbers) - Get available phone numbers
* [Create Voice Agent](/api-reference/voice-ai/create-voice-agent) - Create a new voice agent
* [Update Voice Agent](/api-reference/voice-ai/update-voice-agent) - Update agent configuration
* [List Voice Agents](/api-reference/voice-ai/list-voice-agents) - View all agents
* [Make Call](/api-reference/voice-ai/make-call) - Make outbound calls with your agent


## OpenAPI

````yaml api-reference/openapi.json POST /attach-phone-numbers
openapi: 3.1.0
info:
  title: >-
    UnleashX - Build human like conversations | Voice Agents | Automations | AI
    Workforce
  version: 1.0.0
  description: UnleashX - Your home for human like conversations
servers:
  - url: https://www.tryunleashx.com/api/v1/global/
security:
  - bearerAuth: []
paths:
  /attach-phone-numbers:
    post:
      tags:
        - Voice AI
      summary: Attach phone numbers to an agent
      parameters:
        - name: token
          in: header
          required: true
          description: API token for authentication
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
                - numbers
              properties:
                agent_id:
                  type: integer
                  description: ID of the agent to attach phone numbers to
                numbers:
                  type: array
                  description: >-
                    Phone numbers to attach to the agent. Must include country
                    code with + prefix (e.g., '+1234567890'). Provide one or
                    more numbers.
                  items:
                    type: string
                    example: '+12025551234'
                  minItems: 1
      responses:
        '200':
          description: Numbers attached successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      agent_id:
                        type: integer
                      phone_numbers:
                        type: array
                        items:
                          type: string
        '400':
          description: Bad Request - Phone Number or Agent ID is required
        '401':
          description: Unauthorized
        '404':
          description: Agent not found or not active
        '422':
          description: Validation error
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````