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
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. 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
Response
The number is yours, as Get Phone Number shows it.
A number, with the agent it is lent to for calling out.