Click to call

POST /calls places a call in two steps. First it rings a phone on the account. When someone answers that phone, the call goes on to the number you asked for, and the two are connected. It is what happens when a user clicks a number in a CRM to call it.

Endpoint	Scope	Does
POST /calls	calls:make	Rings a phone, then connects it to to. Charged.

curl https://api.account.telebroad.com/api/public/v1/calls \
  -H "Authorization: Bearer tbk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"phone": "6589455", "to": "3475550123", "callerId": "12125550188"}'

{
  "data": {
    "callId": "1761755203.884213",
    "phone": "6589455",
    "to": "13475550123",
    "callerId": "12125550188"
  }
}

201 means the phone is ringing. It does not mean anyone answered. When the call ends it is in call history under callId (GET /calls/{callid}, with reports:read) and in the call webhooks. callId is missing in the rare case the phone system did not name the call within a couple of seconds; the call is placed either way.

Do not retry a 201. Each request places a new call.

The phones a key may ring

An API key must list the phones it may ring. When you create or edit the key, pick them under Phones. phone in the request must be one of them; any other phone gets 403 permission_denied.

:::caution A key with no phones cannot place calls If you give a key calls:make but select no phones, every POST /calls is refused with 403:

this API key has no phones it may ring; add phones to the key to place calls

This is on purpose. It is the opposite of the usual rule, where a type with no grants is unrestricted. A key must be told exactly which desks it may ring. :::

Every phone you pick must be a phone of your account; any other is refused when you save the key. A phone does not have to belong to the user the key runs as.

An OAuth token has no phone list. It may ring only the authorizing user's own phones.

Caller ID

callerId is what the person you call sees.

callerId	Shows
omitted or ""	The phone's own outbound caller ID
default	The account's main caller ID
original or original_own_number	The phone's own number
a number, e.g. 12125550188	That number

The caller ID must be one the user could pick in TeleConsole. The user is the one the key runs as (or the authorizing user, for OAuth). A number must be on that user's TeleConsole caller ID list, which follows these rules:

1. It is one of the account's numbers that can be a caller ID: a phone number or a verified caller ID, in a group that allows caller ID.
2. If the user's phone-system role may not see the company's numbers, the list is only the caller IDs set on the user's own phones.
3. A number marked for fax in the admin center is not on the list.
4. A number limited to specific users in the admin center is on the list only for those users. A number limited to no one is on nobody's list.
5. If the account restricts numbers, only numbers set up in the admin center are on the list, and "" and default are refused.

On top of that list, a number must also pass two more checks:

• It is among the Phone numbers of the user's role.
• If the key has number grants, it is one of them. Number grants now limit caller ID too, not only texting and faxing.

Two rules can change what you asked for:

• If the user's phone-system role may not change caller ID, the call always shows the phone's own caller ID, whatever callerId says.
• A key with number grants must show a granted number. Send that number as callerId, or default when the account's main caller ID is granted. Omitted, "" and original are refused for such a key, because the number they would show is not known in advance.

The number to call

to is a phone number or an extension. Spaces, dashes, dots and parentheses are ignored. 10 digits get a leading 1. A number starting with +, or a long number that does not start with 1 or 0, gets the international 011 prefix. Letters are refused, so 1-800-FLOWERS is a 400, not a call to 1800.

One request calls one number.

When a request is refused

Response	Cause	Fixed by
400 invalid_request	A missing or malformed field, an unknown field, or the phone system refused the destination	Your request
403 insufficient_scope	The key does not have calls:make	Edit the key and add the scope
403 permission_denied — no phones	The key has no phones selected	Edit the key and pick its phones
403 permission_denied on phone	phone is not one of the key's phones, or not a phone of the account	Edit the key, or send one of its phones
403 permission_denied on callerId	The number is not on the user's TeleConsole caller ID list, not in the role's numbers, or not in the key's number grants	An admin changes the number's access, the role or the key
403 permission_denied, default or no caller ID	The account restricts numbers, so "" and default are not allowed	Send one of the user's caller ID numbers

In every refused case, no call was placed.