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.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json
number
string
required

The number, ideally in E.164 (+14155550100). Without a country code it is read as Indian.

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"

setup
object
required

Where the number must send its calls.