curl --request POST \
--url https://{host}/api/v1/calls/ivr \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"to": "+61412345678",
"callback_url": "<string>",
"caller_id": "+61298765432",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"variables": {
"appointment": "Tuesday 3pm",
"name": "Sam"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
flow_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
to: '+61412345678',
callback_url: '<string>',
caller_id: '+61298765432',
organisation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
variables: {appointment: 'Tuesday 3pm', name: 'Sam'}
})
};
fetch('https://{host}/api/v1/calls/ivr', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/api/v1/calls/ivr"
payload = {
"flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"to": "+61412345678",
"callback_url": "<string>",
"caller_id": "+61298765432",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"variables": {
"appointment": "Tuesday 3pm",
"name": "Sam"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"dry_run": true,
"plan": {
"caller_id": "<string>",
"flow": "<string>",
"max_seconds": 123,
"revision": 123,
"to_e164": "<string>",
"trunk": "<string>"
}
}{
"plan": {
"caller_id": "<string>",
"flow": "<string>",
"max_seconds": 123,
"revision": 123,
"to_e164": "<string>",
"trunk": "<string>"
},
"reference": "<string>",
"request_id": "<string>",
"status": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Ring a number into an IVR
FireTone rings to from caller_id (one of your numbers; optional when you have exactly one), and whoever answers hears the IVR’s published revision — the same walk a number pointed at the IVR gives its callers. For a reminder with “press 1 to confirm”, a survey, a notice.
variables are available to the IVR’s steps as {{name}}.
Answers 202 at once: the dial happens in the background, and how it went is posted to callback_url (call.started, call.ended; call.failed with the reason if nobody answered) and kept on the request (GET /call-requests/{id}).
Refused 422 with the reason: the IVR has never been published, the number is one of your own, no route reaches it, or billing refuses it. 404 when the IVR is not yours. 503 node_busy with Retry-After when the node has no room right now. Rate limited with click-to-call (60 a minute per key). Requires calls:originate.
curl --request POST \
--url https://{host}/api/v1/calls/ivr \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"to": "+61412345678",
"callback_url": "<string>",
"caller_id": "+61298765432",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"variables": {
"appointment": "Tuesday 3pm",
"name": "Sam"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
flow_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
to: '+61412345678',
callback_url: '<string>',
caller_id: '+61298765432',
organisation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
reference: '<string>',
variables: {appointment: 'Tuesday 3pm', name: 'Sam'}
})
};
fetch('https://{host}/api/v1/calls/ivr', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/api/v1/calls/ivr"
payload = {
"flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"to": "+61412345678",
"callback_url": "<string>",
"caller_id": "+61298765432",
"organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"reference": "<string>",
"variables": {
"appointment": "Tuesday 3pm",
"name": "Sam"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"dry_run": true,
"plan": {
"caller_id": "<string>",
"flow": "<string>",
"max_seconds": 123,
"revision": 123,
"to_e164": "<string>",
"trunk": "<string>"
}
}{
"plan": {
"caller_id": "<string>",
"flow": "<string>",
"max_seconds": 123,
"revision": 123,
"to_e164": "<string>",
"trunk": "<string>"
},
"reference": "<string>",
"request_id": "<string>",
"status": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}{
"error": {
"code": "invalid_request",
"message": "<string>"
}
}Authorizations
Every request sends Authorization: Bearer <token>. The token is either a panel session (a JWT from /auth/login, 12 hours) or an API key ft_<id>_<secret>. An API key is accepted only from an address on its IP allowlist (403 ip_not_allowed otherwise; 403 ip_allowlist_required for an old key that has none), is limited to its rate per minute (429 rate_limited with Retry-After; X-RateLimit-Limit/Remaining/Reset on every response), and at most 60 call placements a minute.
Headers
Any string up to 255 characters. A retry with the same key and the same body gets the first answer again (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is 409 idempotency_mismatch; while the first is still running, 409 idempotency_in_progress. Kept 24 hours.
255Query Parameters
true: check everything, place nothing, and return the plan.
Body
The IVR to run for whoever answers. It must be published.
The number to ring. An outside number, not one of your own.
"+61412345678"
Where this call's events are posted, signed with your callback secret.
The number of yours the person sees. Optional when you have exactly one.
"+61298765432"
Not needed: the IVR settles the organisation. If given, it must be the IVR's.
Your own id for this call. It comes back on the request, the callbacks and the call record.
128Values for this call, available to the IVR's steps as {{name}}.
Show child attributes
Show child attributes
{
"appointment": "Tuesday 3pm",
"name": "Sam"
}