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

# Phone Numbers

> Search for, purchase, and register phone numbers with your telephony provider. To make calls, see [Calls](/guides/call-outcomes).

## Overview

Phone calls go through a telephony provider. You have **three ways** to get a number:

| Path                                             | When to use it                                                         | Integration required? |
| ------------------------------------------------ | ---------------------------------------------------------------------- | --------------------- |
| **A — Search & pick a number**                   | You want to choose a specific number from available inventory          | No                    |
| **B — Auto-assign a number**                     | Fastest setup — just pass your agent ID and OneInbox wires a number    | No                    |
| **C — Bring your own number (Twilio or Telnyx)** | You already own a number in Twilio or Telnyx and want to keep using it | Yes                   |

Pick one path below to register your number, then head to [Calls](/guides/call-outcomes) to make your first call.

***

## Path A — Search and pick a number

Search available numbers, then purchase the one you want. OneInbox buys and wires it to your agent in one step.

**1. Search available numbers**

```bash theme={null}
curl "https://api.oneinbox.ai/v1/phone-numbers/search?country=US&area_code=415&limit=10" \
  -H "Authorization: Bearer <api_key>"
```

**2. Purchase a specific number**

Copy a `phone_number` from the search results and pass it to the purchase endpoint:

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Sales Line",
    "agent_id": "<agent_id>",
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": { "agent_id": "<fallback_agent_id>" },
      "voicemail_message": "Sorry we missed you, please leave a message."
    }
  }'
```

Include `inbound_routing` if you want this number to receive inbound calls. Omit it if you only need to make outbound calls from this number.

The number is now assigned to your agent. Head to [Calls](/guides/call-outcomes) to make your first call.

***

## Path B — Auto-assign a number (fastest)

Don't want to search? Omit `phone_number` entirely. OneInbox auto-picks an available number and wires it to your agent in one call:

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "area_code": "415",
    "friendly_name": "Sales Line",
    "agent_id": "<agent_id>",
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": { "agent_id": "<fallback_agent_id>" },
      "voicemail_message": "Sorry we missed you, please leave a message."
    }
  }'
```

Include `inbound_routing` if you want this number to receive inbound calls. Omit it if you only need outbound. The response includes the assigned `phone_number`. Head to [Calls](/guides/call-outcomes) to make your first call.

***

## Path C — Bring your own number (Twilio or Telnyx)

Use a number you already own in Twilio or Telnyx. Both work the same way: set up a SIP trunk, create the integration in OneInbox, then register the number.

<Tabs>
  <Tab title="Twilio">
    **1. Buy the number in Twilio**
    Purchase a phone number from [Twilio Console](https://console.twilio.com) → Phone Numbers → Manage → Buy a number.

    **2. Set up an Elastic SIP Trunk**
    OneInbox connects to Twilio via Elastic SIP Trunking.

    <Accordion title="How to set up an Elastic SIP Trunk in Twilio">
      **Step 1 — Create a trunk**

      In [Twilio Console](https://console.twilio.com), go to **Elastic SIP Trunking** in the left sidebar → click **Create new SIP Trunk** → give it a name (e.g. "OneInbox Trunk") → click **Create**.

      ***

      **Step 2 — Configure Termination (outbound calls)**

      The Termination SIP URI is how OneInbox sends outbound calls through your trunk.

      1. Open your trunk → go to the **Termination** tab
      2. Twilio auto-generates a **Termination SIP URI** — it looks like `yourtrunk.pstn.twilio.com`
      3. Copy this — it's the `sip_trunk` value you'll pass to OneInbox

      ***

      **Step 3 — Configure Origination (inbound calls)**

      The Origination URI tells Twilio where to send inbound calls — in this case, to OneInbox.

      1. Go to the **Origination** tab on your trunk
      2. Click **Add new Origination URI**
      3. Enter `sip:voice.oneinbox.ai:5060`
      4. Set **Priority** to `10` and **Weight** to `10` → click **Add**

      ***

      **Step 4 — Attach your phone number**

      1. Go to the **Numbers** tab on your trunk
      2. Click **Add a number** → select the number you purchased in Step 1
      3. Click **Add Selected**

      The number is now routed through this trunk.

      ***

      **Step 5 — Enable Geographic Permissions (for international calls)**

      If you need to call numbers outside your country (e.g. UAE, India), you must enable those regions:

      1. In Twilio Console, go to **Voice** → **Settings** → **Geo Permissions**
      2. Find the country or region you want to call → toggle it on
      3. Click **Save**

      Without this, outbound calls to international numbers will fail with a `403 Forbidden` error.

      ***

      After completing these steps, copy the **Termination SIP URI** (e.g. `yourtrunk.pstn.twilio.com`) — you'll pass it as `sip_trunk` below.
    </Accordion>

    **3. Store your Twilio credentials in OneInbox**
    Your Account SID and Auth Token are in Twilio Console → Dashboard → Account Info.

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/integrations \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My Twilio Account",
        "provider": "twilio",
        "api_key": "<your_twilio_auth_token>",
        "metadata": {
          "account_sid": "<your_twilio_account_sid>",
          "phone_number": "+15739693824",
          "sip_trunk": "<your_sip_trunk_domain>"
        }
      }'
    ```

    ```json theme={null}
    { "id": "crd_abc123", "provider": "twilio" }
    ```

    **4. Register the number with OneInbox**

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+15739693824",
        "friendly_name": "Sales Line",
        "provider": "twilio",
        "agent_id": "<agent_id>",
        "provider_config": {
          "trunk_address": "yourtrunk.pstn.twilio.com",
          "auth_username": "oneinbox",
          "auth_password": "<your_sip_password>"
        },
        "inbound_routing": {
          "agent_id": "<routing_agent_id>",
          "fallback": { "agent_id": "<fallback_agent_id>" },
          "voicemail_message": "Sorry, we missed you. Please leave a message."
        }
      }'
    ```

    Include `inbound_routing` if you want this number to receive inbound calls. Omit it if you only need outbound.
  </Tab>

  <Tab title="Telnyx">
    **1. Buy the number in Telnyx**
    Purchase a phone number from [Telnyx Portal](https://portal.telnyx.com) → Numbers → Buy Numbers.

    **2. Set up a SIP Connection**
    OneInbox connects to Telnyx via a SIP Connection (FQDN connection).

    <Accordion title="How to set up a SIP Connection in Telnyx">
      **Step 1 — Create a connection**

      In [Telnyx Portal](https://portal.telnyx.com), go to **Voice** → **SIP Connections** → click **Add SIP Connection**.

      * **Connection name**: e.g. "OneInbox"
      * **Auth method**: Credential
      * Set a **username** and **password** — these go into `auth_username` and `auth_password` when you register the number in OneInbox

      ***

      **Step 2 — Get the SIP trunk domain**

      After creating the connection, Telnyx assigns a SIP domain — it looks like `<yourconnection>.sip.telnyx.com`. Copy this — it's the `sip_trunk` value you'll pass to OneInbox.

      ***

      **Step 3 — Configure inbound (origination)**

      1. Open your connection → go to **Inbound**
      2. Under **SIP Trunking Settings**, set the origination destination to `sip:voice.oneinbox.ai:5060`

      ***

      **Step 4 — Attach your phone number**

      1. Go to **Numbers** → select the number you purchased
      2. Under **Connection/App**, select the SIP connection you just created
      3. Click **Save**

      ***

      **Step 5 — Enable international calling (if needed)**

      If you need to call numbers outside your country:

      1. Go to **Voice** → **Call Control** → **Outbound Voice Profile**
      2. Enable the countries you need under **Destinations**
    </Accordion>

    **3. Store your Telnyx credentials in OneInbox**
    Your API key is in Telnyx Portal → Account → API Keys. Your account SID is in Account → Overview.

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/integrations \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My Telnyx Account",
        "provider": "telnyx",
        "api_key": "<your_telnyx_api_key>",
        "metadata": {
          "account_sid": "<your_telnyx_account_id>",
          "phone_number": "+15739693824",
          "sip_trunk": "<yourconnection>.sip.telnyx.com"
        }
      }'
    ```

    ```json theme={null}
    { "id": "crd_abc123", "provider": "telnyx" }
    ```

    **4. Register the number with OneInbox**

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+15739693824",
        "friendly_name": "Sales Line",
        "provider": "telnyx",
        "agent_id": "<agent_id>",
        "provider_config": {
          "trunk_address": "<yourconnection>.sip.telnyx.com",
          "auth_username": "<your_sip_username>",
          "auth_password": "<your_sip_password>"
        },
        "inbound_routing": {
          "agent_id": "<routing_agent_id>",
          "fallback": { "agent_id": "<fallback_agent_id>" },
          "voicemail_message": "Sorry, we missed you. Please leave a message."
        }
      }'
    ```

    Include `inbound_routing` if you want this number to receive inbound calls. Omit it if you only need outbound.
  </Tab>
</Tabs>

```json theme={null}
{
  "id": "phn_abc123",
  "phone_number": "+15739693824",
  "agent_id": "agt_abc123",
  "status": "active"
}
```

To reassign the number to a different agent later, use [PATCH Update phone number](/api-reference/phone-numbers/update-phone-number) with `{ "agent_id": "..." }`.

***

## Inbound calls

To make a number receive inbound calls, set `inbound_routing` when you register or purchase it (see paths A, B, and C above). Without `inbound_routing`, the number is outbound-only — calls to it will not be routed to your agent.

To add or update inbound routing on an existing number, use [PATCH Update phone number](/api-reference/phone-numbers/update-phone-number):

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<new_agent_id>" }'
```

### Inbound routing

Use `inbound_routing` to control which agent handles inbound calls — you can use the same agent as outbound or a different one. Optionally add a fallback agent or a custom voicemail message.

```bash theme={null}
# Set inbound_routing when registering the number
curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "friendly_name": "Sales Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "provider_config": { ... },
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": {
        "agent_id": "<fallback_agent_id>"
      },
      "voicemail_message": "Sorry, we missed you. Please leave a message."
    }
  }'

# Or update routing on an existing number
curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "voicemail_message": "Updated voicemail message."
    }
  }'
```

| Field                               | What it does                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `inbound_routing.agent_id`          | Override which agent handles inbound calls — independent of the number's primary `agent_id` |
| `inbound_routing.fallback.agent_id` | Agent to route to if the primary routing agent is unavailable                               |
| `inbound_routing.voicemail_message` | Custom voicemail message for this number, overrides the agent's default                     |

***

## Manage phone numbers

### Get a phone number

Retrieve a single number's current configuration — agent assignment, inbound routing, and provider details.

```bash theme={null}
curl https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>"
```

### Delete a phone number

Releases the number from your account. For numbers purchased through OneInbox, this also cancels the number with the carrier.

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## API reference

[Register phone number](/api-reference/phone-numbers/register-phone-number) · [Update phone number](/api-reference/phone-numbers/update-phone-number) · [List phone numbers](/api-reference/phone-numbers/list-phone-numbers) · [Get phone number](/api-reference/phone-numbers/get-phone-number) · [Delete phone number](/api-reference/phone-numbers/delete-phone-number)