Skip to main content
POST
Rent 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

Idempotency-Key
string

Any unique string. A retry with the same key within 24 hours returns the first request's answer instead of acting twice.

Maximum string length: 255
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

A number from Search Available Phone Numbers, in any spelling.

Example:

"918041234567"

Response

The number is yours, as Get Phone Number shows it.

A number, with the agent it is lent to for calling out.

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