curl --request GET \
--url https://app.thinnest.ai/api/v1/phone-numbers/{number} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.thinnest.ai/api/v1/phone-numbers/{number}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.thinnest.ai/api/v1/phone-numbers/{number}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"number": "918041234567",
"label": "Front desk",
"source": "rented",
"agent": "ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34",
"since": "2026-09-02T07:15:40.118Z",
"provider": null,
"callingAgent": "ag_9b0e4d17-5a2c-4e6f-b381-7c4d2a0f9e15"
}{
"error": "Send a valid API key as `Authorization: Bearer <key>`."
}{
"error": "That number was not found."
}{
"error": "Over 240 requests a minute. Slow down and retry."
}Get Phone Number
One number this workspace holds: who answers it, who calls out on it, and its name. A number held by another workspace is 404, the same as one that does not exist.
curl --request GET \
--url https://app.thinnest.ai/api/v1/phone-numbers/{number} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.thinnest.ai/api/v1/phone-numbers/{number}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.thinnest.ai/api/v1/phone-numbers/{number}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"number": "918041234567",
"label": "Front desk",
"source": "rented",
"agent": "ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34",
"since": "2026-09-02T07:15:40.118Z",
"provider": null,
"callingAgent": "ag_9b0e4d17-5a2c-4e6f-b381-7c4d2a0f9e15"
}{
"error": "Send a valid API key as `Authorization: Bearer <key>`."
}{
"error": "That number was not found."
}{
"error": "Over 240 requests a minute. Slow down and retry."
}Authorizations
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
Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace.
"org_3fKq9TzQ1mN8vB2xR7cLpA"
Path Parameters
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.
The number. A rented number reads as digits with its country code (918041234567); a brought one as you brought it, usually E.164.
"918041234567"
Its name, or null. Always null for a brought number in List Phone Numbers.
60"Front desk"
rented here and charged monthly, or brought from your own carrier account and never billed by us.
rented, brought "rented"
The agent that answers it (ag_…), or null for nobody.
"ag_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34"
When a rented number was rented; null for a brought one.
"2026-09-02T07:15:40.118Z"
Your own carrier account a brought number is on (plivo, vobiz, twilio or telnyx); null for a number rented here.
"twilio"
The agent lent this number to call out on (ag_…), or null. May differ from agent.
"ag_9b0e4d17-5a2c-4e6f-b381-7c4d2a0f9e15"