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": "Unauthorized",
"code": "unauthorized"
}{
"error": "Answering a phone number needs a paid plan — the free plan answers calls on your website only."
}{
"error": "Workspace not found.",
"code": "workspace_not_found"
}{
"error": "That number is already registered here. If it is yours, get in touch and we will sort it out."
}{
"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": "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."
}{
"error": "Over 240 requests a minute. Slow down and retry.",
"code": "rate_limit_resources",
"limit": {
"name": "resources",
"perMinute": 240
}
}{
"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": "Unauthorized",
"code": "unauthorized"
}{
"error": "Answering a phone number needs a paid plan — the free plan answers calls on your website only."
}{
"error": "Workspace not found.",
"code": "workspace_not_found"
}{
"error": "That number is already registered here. If it is yours, get in touch and we will sort it out."
}{
"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": "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."
}{
"error": "Over 240 requests a minute. Slow down and retry.",
"code": "rate_limit_resources",
"limit": {
"name": "resources",
"perMinute": 240
}
}{
"error": "We could not check whether that number is already in use. Try again in a moment."
}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 recorded.
A brought number, with what is left to set up.