Skip to main content
PATCH
Update 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"

Path Parameters

number
string
required

The number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading + as %2B, or leave it out.

Body

application/json

Send any of the four; at least one.

label
string | null

A name for the number. null or "" removes it.

Maximum string length: 60
Example:

"Front desk"

agent
string | null

The agent that answers the number (ag_…): it becomes that agent's line and stops being any other's. The agent must have voice switched on. null makes nothing answer it.

Example:

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

callingAgent
string | null

The agent that calls out on the number without answering it (ag_…) — campaigns spread their calls over an agent's numbers. null takes it back. Where the number answers is unchanged.

Example:

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

forwardTo
string | null

Forward every call to this number to this phone (E.164, like +919812345678) without the agent answering — a fallback for when the agent is not working. It rings for 30 seconds. If nobody picks up, a caller on a number from us, Plivo or Twilio hears that nobody could take the call; a caller on a number brought from Telnyx gets no spoken message — the line rings out or returns busy, then ends. A call that is picked up is cut off at its limit: on a number rented here, when the balance can no longer pay for it and never later than 20 minutes (the platform's maximum call length); on a number you brought, after 30 minutes. Premium-rate, shared-cost, toll-free, satellite and some high-cost international destinations are refused (forward_destination_not_allowed, 422). It works whether or not an agent answers the number: with an agent, the forward replaces it; with none (never attached, deleted, or its voice switched off) the forward answers the call itself, so the number never goes quiet. A workspace that cannot pay for a call, or has no free call line, does not forward - the caller hears that the number is not answering. Billed like a call put through to a person: every connected minute on a number rented here (at the voice plan of the agent attached to the number, or the Premium plan when no agent is; under your own keys, the flat own-key price of that set), nothing on a number you brought. A forwarded call is not recorded. Cannot be this number or another number on the platform. null stops forwarding.

Example:

"+919812345678"

Response

The number as it now is.

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