POST /flows/{flowId}/calls

Call a number and run a Flow when it answers

This places a real, billable outbound call from the account. The call is placed as soon as the request succeeds — there is no draft, schedule or confirmation step, and no way to cancel it through the API.

Scope	flows:call (API keys only — no OAuth client can hold it)
Resource grant	flow — if the key has flow grants, flowId must be one of them
Role permission	None — the key's run-as user's role is not consulted on this endpoint
Cost	One outbound call, charged like any other call the account places

The flow runs only if the call is answered — by a person or by voicemail. There is no answering-machine detection: a call that reaches voicemail plays the flow's first step into the mailbox.

params fill {placeholders} in the flow's spoken (text-to-speech) text, in a step's request URL and request body, and in a spreadsheet lookup key. A value is substituted as plain text, exactly as you sent it.

The response does not identify the call. call.id is the id of the stored parameters, not a call id, and call.status is always queued. There is no endpoint to look up a placed call's status. To learn the outcome, have the flow report it — see the guide.

Unknown body fields are ignored. The Location header is not set.

Path parameters

Name	Type	Required	Example	Description
flowId	integer	yes	742	The flow's numeric id. It must belong to the key's account, and — if the key has flow grants — be one of them.

Request body

Field	Type	Required	Description
to	string	yes	The number to call. Required; blank is 422. Send the 11-digit form for US numbers (12125550188). It is passed to the phone system as given — not reformatted — and a number the switch refuses is 400.
from	string	no	The caller ID the called person sees. Optional. When set it must be, character for character, a number or Virtual Caller ID on the account in the form the admin center lists it (12125550100 — no +, no spaces or punctuation), or the request is 403 and no call is placed. When omitted, the account's normal outbound caller ID applies.
params	object	no	Per-call values, as a flat object of string values. Each key fills the matching {key} placeholder in the flow. A non-string value (number, boolean, object, array) fails the whole request with 400; null is accepted as an empty string. In a step URL, values are inserted as sent, not URL-encoded. Optional.
ttlSec	integer	no	How long, in seconds from this request, the flow can still read params. Default 900 (15 minutes) when omitted, 0 or negative. The flow reads params on every step, so this must cover ringing time plus the whole call — a step that runs after it lapses no longer sees the values.

An appointment reminder:

{
  "to": "12125550188",
  "from": "12125550100",
  "params": {
    "name": "Dana",
    "doctor": "Dr. Patel",
    "date": "Tuesday, November 4",
    "time": "10:30 AM",
    "appointment_id": "A-20931"
  },
  "ttlSec": 1800
}

Only the required field:

{
  "to": "12125550188"
}

Responses

200

The parameters were stored and the call was handed to the switch. The call is being placed; whether it is answered is not known yet and is never reported back by this endpoint.

Field	Type	Description
call	object
call.id	string	The id of the stored params for this call. Not a call id — it does not appear in Call History or in webhooks. A step URL or request body in the flow can receive it as the {params_id} placeholder.
call.status	queued	Always queued. It is never updated.
call.flowId	integer	The flow from the path.

Call queued:

{
  "code": 200,
  "message": "success",
  "data": {
    "call": {
      "id": "48113",
      "status": "queued",
      "flowId": 742
    }
  }
}

Errors

Status	Meaning
400	The body is not valid JSON (2.4054) — including a params value that is a number, boolean, object or array; or the switch refused the to number (3.96, "invalid flow call destination").
401	No key was sent, or the key is not a valid key. Plain-text body (Unauthorized; unauthorized when no key was sent at all), not JSON.
403	Plain-text Forbidden: the key is revoked or expired, lacks flows:call, the request IP is outside its allowed IPs, the flow is not among its flow grants (including a flow id that does not exist, for a key with flow grants), or the flow is on another account (the body does not say which). JSON 2.4051: from is not a number or Virtual Caller ID on the account.
404	No flow has this id, for a key without flow grants (a key with flow grants gets 403). Plain-text body (Not Found).
409	The flow exists but has not been registered with the phone system yet (2.4048). Open the flow in the admin center and save it again.
422	to is missing or blank (2.4055).
500	The call could not be placed (3.961, "failed to originate flow call"), or an internal error. On 3.961 the parameters were stored and the phone system did not confirm the call — usually none was placed, but a timeout reaching the phone system is reported the same way. A retry that succeeds always places a new call.

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

Example

curl -X POST 'https://api.account.telebroad.com/api/v1/flows/742/calls' \
  -H "Authorization: Bearer $TB_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"12125550188","from":"12125550100","params":{"name":"Dana","doctor":"Dr. Patel","date":"Tuesday, November 4","time":"10:30 AM","appointment_id":"A-20931"},"ttlSec":1800}'