curl --request POST \
--url https://app.thinnest.ai/api/v1/phone-numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "918041234567"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({number: '918041234567'})
};
fetch('https://app.thinnest.ai/api/v1/phone-numbers', 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"
payload = { "number": "918041234567" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"number": "918041234567",
"label": null,
"source": "rented",
"agent": null,
"since": "2026-10-06T10:30:05.442Z",
"provider": null,
"callingAgent": null
}{
"error": "`number` is required — one from GET /phone-numbers/available."
}{
"error": "Unauthorized",
"code": "unauthorized"
}{
"error": "Top up first — a number is charged for its first month as soon as you take it."
}{
"error": "Phone numbers need a paid plan. Switch to pay-as-you-go — there is no monthly fee — and top up, because a number is charged every month."
}{
"error": "Workspace not found.",
"code": "workspace_not_found"
}{
"error": "Your business details are still being checked. This usually takes a few minutes."
}{
"error": "This workspace was deleted on 2026-10-06 and is erased on 2026-11-05. POST /v1/customers/{id}/restore brings it back until then.",
"code": "workspace_deleted"
}{
"error": "Over 240 requests a minute. Slow down and retry.",
"code": "rate_limit_resources",
"limit": {
"name": "resources",
"perMinute": 240
}
}{
"error": "We could not finish setting that number up, so it was handed back. Try again, or pick another."
}Rent Phone Number
Rents a number from Search Available Phone Numbers. This costs money: the first month’s rent (the monthlyPrice the search showed) is charged from your balance at once, and again every month on the same day until you release the number. Every refusal happens before anything is bought or charged. An Indian number also needs your business details sent and approved first (Send Business Details, or the console’s Phone Numbers page). The number arrives answered by nobody — Update Phone Number points it at an agent. Send an Idempotency-Key so a retry cannot rent twice: a repeat returns the first answer with Idempotent-Replayed: true, and a request that failed lets the same key try again. Needs a full key.
curl --request POST \
--url https://app.thinnest.ai/api/v1/phone-numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "918041234567"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({number: '918041234567'})
};
fetch('https://app.thinnest.ai/api/v1/phone-numbers', 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"
payload = { "number": "918041234567" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"number": "918041234567",
"label": null,
"source": "rented",
"agent": null,
"since": "2026-10-06T10:30:05.442Z",
"provider": null,
"callingAgent": null
}{
"error": "`number` is required — one from GET /phone-numbers/available."
}{
"error": "Unauthorized",
"code": "unauthorized"
}{
"error": "Top up first — a number is charged for its first month as soon as you take it."
}{
"error": "Phone numbers need a paid plan. Switch to pay-as-you-go — there is no monthly fee — and top up, because a number is charged every month."
}{
"error": "Workspace not found.",
"code": "workspace_not_found"
}{
"error": "Your business details are still being checked. This usually takes a few minutes."
}{
"error": "This workspace was deleted on 2026-10-06 and is erased on 2026-11-05. POST /v1/customers/{id}/restore brings it back until then.",
"code": "workspace_deleted"
}{
"error": "Over 240 requests a minute. Slow down and retry.",
"code": "rate_limit_resources",
"limit": {
"name": "resources",
"perMinute": 240
}
}{
"error": "We could not finish setting that number up, so it was handed back. Try again, or pick another."
}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
Any unique string. A retry with the same key within 24 hours returns the first request's answer instead of acting twice.
255Developers 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.
"org_3fKq9TzQ1mN8vB2xR7cLpA"
Body
A number from Search Available Phone Numbers, in any spelling.
"918041234567"
Response
The number is yours, as Get Phone Number shows it.
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"
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.
null