Phone Numbers - OneInbox

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 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

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:

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 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:

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 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.

Twilio
Telnyx

1. Buy the number in Twilio Purchase a phone number from Twilio Console → Phone Numbers → Manage → Buy a number.2. Set up an Elastic SIP Trunk OneInbox connects to Twilio via Elastic SIP Trunking.

How to set up an Elastic SIP Trunk in Twilio

Step 1 — Create a trunkIn Twilio Console, 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.

Open your trunk → go to the Termination tab
Twilio auto-generates a Termination SIP URI — it looks like yourtrunk.pstn.twilio.com
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.

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

Step 4 — Attach your phone number

Go to the Numbers tab on your trunk
Click Add a number → select the number you purchased in Step 1
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:

In Twilio Console, go to Voice → Settings → Geo Permissions
Find the country or region you want to call → toggle it on
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.

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

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>"
    }
  }'

{ "id": "crd_abc123", "provider": "twilio" }

4. Register the number with OneInbox

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.

1. Buy the number in Telnyx Purchase a phone number from Telnyx Portal → Numbers → Buy Numbers.2. Set up a SIP Connection OneInbox connects to Telnyx via a SIP Connection (FQDN connection).

How to set up a SIP Connection in Telnyx

Step 1 — Create a connectionIn Telnyx Portal, 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 domainAfter 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)

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

Step 4 — Attach your phone number

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

Step 5 — Enable international calling (if needed)If you need to call numbers outside your country:

Go to Voice → Call Control → Outbound Voice Profile
Enable the countries you need under Destinations

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

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"
    }
  }'

{ "id": "crd_abc123", "provider": "telnyx" }

4. Register the number with OneInbox

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.

{
  "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 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:

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.

# 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.

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.

curl -X DELETE https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>"

​Overview

​Path A — Search and pick a number

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

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

​Inbound calls

​Inbound routing

​Manage phone numbers

​Get a phone number

​Delete a phone number

​API reference