POST /calls

Place a call (click to call)

This spends money. Every call placed is charged to the account.

Rings a phone on the account first. When someone answers it, the call goes on to to, so the person at that phone is connected to the number. This is the API version of clicking a number to call it.

Scope	calls:make
Key grants	Phones — required. phone must be one of the key's phones. Phone numbers limit callerId.
Role permission	Phone numbers — a callerId number must be one of the role's numbers
Cost	Charged per call, on the account's plan

An API key must list the phones it may ring. Pick them on the key under Phones. A key with no phones selected cannot place calls: every request is refused with 403. An OAuth token may ring only the authorizing user's own phones.

201 means the phone is ringing, not that anyone answered. Nothing reports whether the call connected. When it ends, it is in call history (GET /calls/{callid} with reports:read) and in the call webhooks.

callerId is what the person you call sees:

Value	Shows
omitted or ""	The phone's own outbound caller ID
default	The account's main caller ID
original, original_own_number	The phone's own number
a number	That number. It must be on the user's TeleConsole caller ID list, among the role's Phone numbers, and within the key's number grants if it has any.

The caller ID must be one the user could pick in TeleConsole. A number is on the user's list when: it is a number or verified caller ID of the account in a group that allows caller ID; the user's phone-system role may see the company's numbers, or it is the caller ID of one of the user's own phones; it is not a fax number; it is not limited to other users in the admin center; and, when the account restricts numbers, it is set up in the admin center. An account that restricts numbers also refuses "" and default.

Two things can override what you ask for:

• Users whose phone-system role may not change caller ID always call with the phone's own caller ID, whatever callerId says.
• A key with number grants must end on 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 show is not known in advance.

One destination per request. to is a number or an extension: 10 digits get a leading 1; + and international numbers get the 011 prefix; spaces, dashes, dots and parentheses are ignored. Letters are refused.

Unknown fields are rejected.

Request body

Field	Type	Required	Description
phone	string	yes	The phone (line) that rings first, digits only. For an API key it must be one of the key's phones; for an OAuth token, one of the user's own phones.
to	string	yes	The number or extension to connect the phone to. 10 digits get a leading 1; a + or international number gets the 011 prefix. Spaces, dashes, dots and parentheses are ignored; letters are refused.
callerId	string	no	What the called person sees. Omit (or "") for the phone's own caller ID; default for the account's main caller ID; original or original_own_number for the phone's own number; or one of the numbers on the user's TeleConsole caller ID list, among the role's numbers and the key's number grants. See the operation for the rules.

Ring a phone, show its own caller ID:

{
  "phone": "6589455",
  "to": "13475550123"
}

Show one of the account's numbers:

{
  "phone": "6589455",
  "to": "(347) 555-0123",
  "callerId": "12125550188"
}

Responses

201

Handed to the phone system: the phone is ringing. callId is the call's id, the one call history and webhooks use. It is missing when the phone system did not name the call within a couple of seconds; the call is placed either way. Do not retry a 201: that places a second call.

Field	Type	Description
callId	string	The call's id, as call history and webhooks show it. Missing when the phone system did not name the call within a couple of seconds; the call was placed either way.
phone	string	The phone that is ringing.
to	string	to as dialled, after normalization.
callerId	string	The caller ID sent to the phone system. Missing means the phone's own. default is shown as the number it stands for.

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

Errors

Status	Meaning
400	invalid_request — a missing or malformed field, an unknown field, or the phone system refused the destination. No call was placed.
401	unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403	insufficient_scope (the credential lacks calls:make) or permission_denied (the credential may not ring that phone or use that caller ID). No call was placed.
500	internal_error — something failed on our side. For a send, nothing was charged, guaranteed, which is what makes a retry safe.

See Errors for the full catalog and what to do about each.

Example

curl -X POST 'https://api.account.telebroad.com/api/public/v1/calls' \
  -H "Authorization: Bearer $TB_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"6589455","to":"13475550123"}'

Try it in the playground →