Skip to main content
GET
Get 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.

Response

The number.

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