# Create a phone number (/en/api-reference/api-ref/conversational-ai/platform/create-number)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Registers a phone number, its SIP trunk, and its inbound routing in your project.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: create-number
- Method: POST
- Path: /v1/projects/{appid}/numbers
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/numbers

## Servers

- https://preview.ai.agora.io/conversational-ai

Use this endpoint to import a number that your carrier assigned to you. Importing a number doesn't purchase one. Outbound sessions and campaigns can use the number as their caller ID, and `inbound` chooses the agent that answers calls to it.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.

## Request body

- `number` (string, required) - The phone number in E.164 format, for example `+14155550100`.
  - Min length: `1`
  - Max length: `128`
- `description` (string) - A description of the number's purpose. It's separate from `sip_trunk.name`, which names the carrier connection.
- `sip_trunk` (object, required) - The carrier connection for this number.
  - `sip_trunk.name` (string) - A name for the carrier connection that helps you identify it.
  - `sip_trunk.hostname` (string, required) - The carrier's SIP hostname, without a scheme or port. For example, `acme.pstn.example.com`.
    - Pattern: `^[^:/\s]+$`
  - `sip_trunk.port` (integer) - The SIP signaling port. Defaults to `5061` when `transport` is `tls`, and `5060` when it's `udp` or `tcp`.
    - Range: `[1, 65535]`
  - `sip_trunk.transport` (string) - The transport protocol for the carrier connection.
    - Allowed: `udp` | `tcp` | `tls`
    - Default: `tls`
  - `sip_trunk.auth` (object) - The credentials for your SIP trunk. They are write-only and are never returned.
    - `sip_trunk.auth.username` (string, required) - The SIP username.
    - `sip_trunk.auth.password` (string, required) - The SIP password. Referring to a secret set, such as `$secrets.support_prod.sip_password`, isn't supported in the Preview.
  - `sip_trunk.allowed_ips` (array) - The addresses allowed to send inbound SIP traffic to this number. Each entry is an IPv4 address, such as `54.172.60.1`, or an IPv4 CIDR range, such as `54.172.60.0/23`. IPv6 addresses and hostnames aren't accepted. If you omit it, inbound SIP traffic is accepted from any address, so set it to your carrier's signaling addresses.
    - `sip_trunk.allowed_ips.items` (string)
- `inbound` (object) - What happens when someone calls this number. If you omit it, inbound calls are rejected. `call_policy` is required when `agent` isn't `null`.
  - `inbound.agent` (string | null | null, required) - The ID of the agent that answers inbound calls. Set to `null` to reject inbound calls.
  - `inbound.call_policy` (object) - Limits and behavior for inbound calls to this number. Each limit you omit adds no limit.
    - `inbound.call_policy.max_call_duration_seconds` (integer) - The maximum length of a call in seconds, measured from when it's answered.
      - Minimum: `1`
    - `inbound.call_policy.max_silence_duration_ms` (integer) - Hang up when nobody on the call has spoken for this many milliseconds.
      - Minimum: `1`
    - `inbound.call_policy.end_call` (object) - Conditions under which the agent can end the call itself. Every condition is off unless you set it to `true`.
      - `inbound.call_policy.end_call.on_user_request` (boolean) - End the call when the caller clearly says goodbye or asks to hang up.
        - Default: `false`
      - `inbound.call_policy.end_call.on_voicemail` (boolean) - End the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
        - Default: `false`
      - `inbound.call_policy.end_call.on_ai_assistant` (boolean) - End the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
        - Default: `false`

### Request body example

```json
{
  "number": "+14155550100",
  "description": "Primary customer support line for North America.",
  "sip_trunk": {
    "name": "support-line",
    "hostname": "acme.pstn.example.com",
    "transport": "tls",
    "auth": {
      "username": "acme",
      "password": "<your_sip_password>"
    }
  },
  "inbound": {
    "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
    "call_policy": {
      "max_call_duration_seconds": 1800,
      "max_silence_duration_ms": 60000,
      "end_call": {
        "on_user_request": true
      }
    }
  }
}
```

## Responses

### 201

The number was created. The response body contains the saved number.

- `number_id` (string) - The ID of the phone number, a UUID.
  - Format: `uuid`
- `number` (string) - The phone number in E.164 format.
- `description` (string) - A description of the number's purpose. It's separate from `sip_trunk.name`, which names the carrier connection.
- `sip_trunk` (object)
  - `sip_trunk.name` (string) - The name of the carrier connection.
  - `sip_trunk.hostname` (string) - The carrier's SIP hostname.
  - `sip_trunk.port` (integer) - The SIP signaling port.
  - `sip_trunk.transport` (string) - The transport protocol for the carrier connection.
    - Allowed: `udp` | `tcp` | `tls`
  - `sip_trunk.allowed_ips` (array) - The addresses allowed to send inbound SIP traffic.
    - `sip_trunk.allowed_ips.items` (string)
- `inbound` (object) - What happens when someone calls this number. If you omit it, inbound calls are rejected. `call_policy` is required when `agent` isn't `null`.
  - `inbound.agent` (string | null | null, required) - The ID of the agent that answers inbound calls. Set to `null` to reject inbound calls.
  - `inbound.call_policy` (object) - Limits and behavior for inbound calls to this number. Each limit you omit adds no limit.
    - `inbound.call_policy.max_call_duration_seconds` (integer) - The maximum length of a call in seconds, measured from when it's answered.
      - Minimum: `1`
    - `inbound.call_policy.max_silence_duration_ms` (integer) - Hang up when nobody on the call has spoken for this many milliseconds.
      - Minimum: `1`
    - `inbound.call_policy.end_call` (object) - Conditions under which the agent can end the call itself. Every condition is off unless you set it to `true`.
      - `inbound.call_policy.end_call.on_user_request` (boolean) - End the call when the caller clearly says goodbye or asks to hang up.
        - Default: `false`
      - `inbound.call_policy.end_call.on_voicemail` (boolean) - End the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
        - Default: `false`
      - `inbound.call_policy.end_call.on_ai_assistant` (boolean) - End the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
        - Default: `false`
- `create_ts` (integer) - The time the number was added, as a Unix timestamp in seconds.
### 400

The request is invalid. Check `reason` and `detail` in the response body.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 404

The resource in the path doesn't exist. The reason is `ResourceNotFound`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 409

`NumberAlreadyExists`: The number is already registered in the project. `ResourceConflict`: The number is registered to another account, or another project in your account already routes its inbound calls to an agent.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 201

```json
{
  "number_id": "92e68758-3d3a-4f27-8b93-3fd8d834467c",
  "number": "+14155550100",
  "description": "Primary customer support line for North America.",
  "sip_trunk": {
    "name": "support-line",
    "hostname": "acme.pstn.example.com",
    "port": 5061,
    "transport": "tls"
  },
  "inbound": {
    "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
    "call_policy": {
      "max_call_duration_seconds": 1800,
      "max_silence_duration_ms": 60000,
      "end_call": {
        "on_user_request": true
      }
    }
  },
  "create_ts": 1787223852
}
```