Phone numbers

​

Getting a number from us

​

What it costs

​

India needs your business verified first

​

What it asks for

​

Following it up

• Being checked — sent, usually decided within minutes.
• Approved — you can take an Indian number.
• Not accepted — the reason is shown with it. Correct and resend puts the form back up.
• Suspended or Expired — send your documents again.

​

Doing it from the API

curl -X PUT https://app.thinnest.ai/api/v1/phone-numbers/business-details \
  -H "Authorization: Bearer $API_KEY" \
  -H "Thinnest-Workspace: org_3f6a9c21-7d4e-4b58-9a1f-0c2e8b7d5a34" \
  -F businessName="Acme Traders Private Limited" \
  -F gstRegistered=true \
  -F document=@gst-certificate.pdf

{
  "status": "submitted",
  "businessName": "Acme Traders Private Limited",
  "gstRegistered": true,
  "documentKind": "gst",
  "submittedAt": "2026-10-08T09:41:12.380Z",
  "canRent": false
}

​

Marketing calls need a different number

​

Using a number you already own

​

Numbers from Twilio

​

Numbers from Telnyx

​

Recording calls on a number you brought

​

A transferred call on a number you brought

​

Calling out from a number you brought

​

What you can do to a number

• Edit credentials — for a number you brought, the API credentials of the carrier account its outgoing calls go through. Saving applies to every number you brought from that account.
• Rename — a name for your own eyes, so a list of numbers reads as “Bengaluru showroom” rather than six strings ending in different digits. Callers never see it.
• Forward calls — send every call to this number to another phone, with the agent not answering at all. See Forwarding a whole line.
• Move to another workspace… — only for developers building on the customers API: hand the number to one of your customers, or back to your own workspace, keeping its digits. See Moving a number to another workspace.
• Release — only on a number you rent from us. See below; it is permanent.
• Remove — only on a number you brought. We forget it; you keep it. For a Twilio number we also clear the address we set on it, and a Telnyx number is taken off our application, so it stops ringing at us — but only if it still points at us, so anything you have since pointed it at yourself is left alone.

​

Forwarding a whole line

• It rings for 30 seconds. If nobody picks up, the caller of a number from us, Plivo or Twilio hears that nobody could take the call, and the line ends. On a number brought from Telnyx the caller gets no spoken message: the line rings out or returns busy, then ends.
• A forwarded call has a time limit. On a number you took from us it ends when your balance can no longer pay for it, and never later than 20 minutes, the longest any call can run. On a number you brought it ends after 30 minutes.
• Who the phone shows as calling. On a number from Twilio or Telnyx, the original caller’s number. On a number from us or from Plivo, your own number — those lines may only present a number on the account.
• It works whether or not an agent answers the number. If an agent does, the forward replaces it. If none does — no agent attached, the agent deleted, or its Answer calls switched off — the forward answers the call itself. Your plan, your call lines and your balance are checked first, as for any call, so a workspace that cannot pay for a call, or has every call line busy, does not forward it: the caller hears that the number is not answering.
• What it costs is what a call put through to a person costs: on a number you took from us, every minute the caller is connected, at the voice plan of the agent attached to the number — or the standard voice rate when no agent is. If your own keys apply to that agent (or to the workspace, when no agent is attached), it is the flat price of that set of keys instead, even though a forward uses none of them. On a number you brought, nothing from us — the minutes are on your carrier’s bill. It is not the carrier-only charge of a call that ends before the agent speaks.
• It is not recorded. The agent never takes a forwarded call, so there is no recording and no transcript: Get Call shows recording as null and Get Recording answers 404.
• Not to one of these numbers. A forward cannot point at the number itself or at another number on the platform, which would send calls round in a loop.
• Not to premium or special numbers. Premium-rate, shared-cost and toll-free numbers, satellite and international-network numbers, and a short list of high-cost international destinations are refused (forward_destination_not_allowed): a forward runs with nobody watching, and those numbers charge by the minute to whoever dials them. An ordinary landline or mobile is always fine. If you have a real need for one of them, tell us.
• Nothing is said or sent after a forwarded call. The agent never took it, so there is no summary, no extracted details and no follow-up message — you still get the call.completed webhook, with forwardedTo set, when an agent answers the number. When no agent does there is no agent to send it for, so the call shows in Usage, Get Call and the call list (with no agent) and not as a webhook or an inbox conversation. Get Call and the call list carry forwardedTo too, and seconds is how long the caller was connected, even on a number you brought where nothing is billed. A forward nobody picked up is reported as missed, with a hangup of no_answer, busy, rejected or unreachable, and seconds 0. On a Telnyx number a caller who hangs up while the phone is still ringing may be reported as a completed call instead.
• Not on Vobiz. A Vobiz number cannot forward calls, so the setting is refused (number_cannot_forward).

{ "forwardTo": "+919812345678" }

​

Moving a number to another workspace

curl -X POST https://app.thinnest.ai/api/v1/phone-numbers/918041234567/move \
  -H "Authorization: Bearer $KEY" \
  -H "Thinnest-Workspace: org_…the customer that has it now…" \
  -H "Content-Type: application/json" \
  -d '{ "toWorkspace": "org_…the workspace it goes to…" }'

• The number stops being any agent’s line, and leaves every agent’s spare numbers, in the workspace it leaves.
• It arrives in the other workspace answered by nobody. Point it at an agent there, as with a number you have just rented.
• Rent carries on from the next month in the new workspace. The month already paid is not charged again — and since your customers are billed to you, no money moves either way.
• An Indian number is held in the name of the business using it, so the workspace it moves to must have its own business details approved first (see India needs your business verified first). The move registers the number to that business.
• A number you brought moves only when both workspaces have the same carrier account’s keys saved. A Telnyx number set up for one workspace cannot move this way: remove it and add it again in the other workspace.
• It is refused while the number is on a call, or while the same number is already being moved.
• Any call forwarding set on the number is cleared: it was the old workspace’s choice.
• If the phone network cannot take the move, the number stays where it was, answered by nobody, and you can try again shortly (number_move_unavailable).
• Repeating a move that already succeeded, to the same workspace, gives the same result, so a lost response is safe to retry.
• A few long-held numbers were set up before workspace-level phone accounts existed and cannot be moved this way; write to us for those.

​

Inbound and outbound are separate

• A receptionist and a caller on one number. One agent answers; a different one makes the outbound calls, and the people it rings see your usual number.
• A number that only calls out. Leave Inbound empty and choose an agent under Outbound. Nobody answers when it is rung, but the agent can place calls from it.
• An agent that only calls out. It does not need a number of its own at all. Give it a number under Outbound and it can run campaigns and test calls straight away — we switch its phone on for you when you do.

​

Numbers from different phone companies on one agent

• In the Playground, Call from lists every number the agent can call from, each with its company’s logo. A number that cannot call yet (one you imported without saving its credentials) is shown but greyed out.
• Campaigns spread their calls across all of them.
• Some features depend on the company. Transferring a call to a person and leaving a voicemail work on ThinnestAI numbers and numbers from Plivo or Telnyx, but not on Vobiz or Twilio numbers. Recording works on every number. A call from a number that can’t do one of these still goes out — that feature is simply off for it, and the Playground and the campaign builder tell you before you call.

​

Spare numbers for calling out

​

Disconnecting, giving up, and removing

​

What callers hear when nothing is set up

• Answer calls off — the agent does not answer. A caller on a Plivo, Vobiz or Twilio number hears a short spoken message and the call ends; a Telnyx caller hears a busy tone. You can write the message yourself (When Answer calls is off).
• Answer calls on, Phone number switched off — the same: the agent does not answer. You have switched voice on without telling it to pick up the phone.
• Everything on, no greeting — the agent waits for the caller to speak first. That is a real choice, and some lines are better that way, but it surprises people who expected a greeting.

​

Things worth knowing