Skip to main content
POST
Import Phone Number

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json
number
string
required

The number in E.164 (+14155550100). Include the country code: a number without one is refused.

Example:

"+14155550100"

provider
enum<string>
required

A carrier a brought number can be on — whose network your own account is with.

Available options:
plivo,
vobiz,
twilio,
telnyx
Example:

"twilio"

Response

The number is recorded.

A brought number, with what is left to set up.

number
string
required

The number. A rented number reads as digits with its country code (918041234567); a brought one as you brought it, usually E.164.

Example:

"918041234567"

label
string | null
required

Its name, or null. Always null for a brought number in List Phone Numbers.

Maximum string length: 60
Example:

"Front desk"

source
enum<string>
required

rented here and charged monthly, or brought from your own carrier account and never billed by us.

Available options:
rented,
brought
Example:

"rented"

agent
string | null
required

The agent that answers it (ag_…), or null for nobody.

Example:

"ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34"

since
string<date-time> | null
required

When a rented number was rented; null for a brought one.

Example:

"2026-09-02T07:15:40.118Z"

provider
string | null
required

Your own carrier account a brought number is on (plivo, vobiz, twilio or telnyx); null for a number rented here.

Example:

"twilio"

callingAgent
string | null
required

The agent lent this number to call out on (ag_…), or null. May differ from agent.

Example:

"ag_9b0e4d17-5a2c-4e6f-b381-7c4d2a0f9e15"

forwardTo
string | null
required

Where every call to this number is forwarded (E.164) instead of the agent answering - and when no agent answers it - or null when the agent answers as usual.

Example:

null

setup
object
required

Where the number must send its calls.