curl --request POST \
--url https://app.thinnest.ai/api/v1/phone-numbers/import \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "+14155550100",
"provider": "twilio"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({number: '+14155550100', provider: 'twilio'})
};
fetch('https://app.thinnest.ai/api/v1/phone-numbers/import', 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/import"
payload = {
"number": "+14155550100",
"provider": "twilio"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"number": "+14155550100",
"label": null,
"source": "brought",
"agent": null,
"since": null,
"provider": "twilio",
"callingAgent": null,
"setup": {
"answerUrl": "https://app.thinnest.ai/api/voice/twilio/answer",
"statusUrl": "https://app.thinnest.ai/api/voice/twilio/status",
"pointed": true,
"replaced": null
}
}{
"error": "That does not look like a phone number. Check the digits and the country code."
}{
"error": "Send a valid API key as `Authorization: Bearer <key>`."
}{
"error": "Answering a phone number needs a paid plan — the free plan answers calls on your website only."
}{
"error": "That number is already registered here. If it is yours, get in touch and we will sort it out."
}{
"error": "We asked your carrier and that number is not on the account whose credentials you gave us. Check it includes the country code — for example +1 415 555 0100 — because a number without one is read as Indian."
}{
"error": "Over 240 requests a minute. Slow down and retry."
}{
"error": "We could not check whether that number is already in use. Try again in a moment."
}Import Phone Number
Brings a number you own on your own carrier account. It stays on your account and you keep paying your carrier for it; we never bill it. For carriers that sign their calls with your account’s secret, save the account’s keys first (Save Carrier Account) — we also use them to check the number is really on that account. setup says what is left to do: where the number must send its calls, and whether we pointed it there ourselves. Bringing the same number again is not an error; it corrects provider. The number arrives answered by nobody — Update Phone Number points it at an agent. Needs a paid plan and a full key.
curl --request POST \
--url https://app.thinnest.ai/api/v1/phone-numbers/import \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "+14155550100",
"provider": "twilio"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({number: '+14155550100', provider: 'twilio'})
};
fetch('https://app.thinnest.ai/api/v1/phone-numbers/import', 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/import"
payload = {
"number": "+14155550100",
"provider": "twilio"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"number": "+14155550100",
"label": null,
"source": "brought",
"agent": null,
"since": null,
"provider": "twilio",
"callingAgent": null,
"setup": {
"answerUrl": "https://app.thinnest.ai/api/voice/twilio/answer",
"statusUrl": "https://app.thinnest.ai/api/voice/twilio/status",
"pointed": true,
"replaced": null
}
}{
"error": "That does not look like a phone number. Check the digits and the country code."
}{
"error": "Send a valid API key as `Authorization: Bearer <key>`."
}{
"error": "Answering a phone number needs a paid plan — the free plan answers calls on your website only."
}{
"error": "That number is already registered here. If it is yours, get in touch and we will sort it out."
}{
"error": "We asked your carrier and that number is not on the account whose credentials you gave us. Check it includes the country code — for example +1 415 555 0100 — because a number without one is read as Indian."
}{
"error": "Over 240 requests a minute. Slow down and retry."
}{
"error": "We could not check whether that number is already in use. Try again in a moment."
}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"
Body
The number, ideally in E.164 (+14155550100). Without a country code it is read as Indian.
"+14155550100"
A carrier a brought number can be on — whose network your own account is with.
plivo, vobiz, twilio, telnyx "twilio"
Response
The number is recorded.
A brought number, with what is left to set up.
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 the number must send its calls.
Show child attributes
Show child attributes