Web API: how your system launches campaigns on its own
This section explains what the Web API does, how to get an access key, how to launch a calling campaign through it, and how to read the responses. This section has two parts, written for different people:- How it works requires no programming knowledge: what happens, who is responsible for what, and what has to be decided before the first request.
- Technical reference is for a developer: request paths, fields, response formats, error codes, and examples.
How to read the contract. Everything named in a table is stable unless the table says otherwise. Two things are explicitly not part of the contract:
error.message (English diagnostic prose) and the message field that may appear inside blockers / warnings items on 2xx campaign responses. New fields and new codes are added over time — treat unknown fields as opaque, and an unknown code by falling back to error.type + error.status.What this is and why
Normally a person creates a calling campaign: they log in to the dashboard, create a campaign, upload a file with phone numbers, and click Launch. That works well while campaigns are occasional. The Web API is for when a campaign has to launch by itself — from your system, at the moment an event happens there. A contract goes past due, a ticket closes, a reminder date arrives — your system sends the platform a single request and the campaign starts. No person is involved at that moment.The key property: under the hood this is the same product. A campaign created by a request is no different from one created in the dashboard. The same pre-launch checks, the same number parsing, the same do-not-call registry, the same scheduler, the same per-number frequency caps, the same call recordings and reports. It appears in the dashboard in the common list and can be paused by hand. This is not “a second product for developers” — it is a second door into the same one.
Two working models — pick one
There is no need to mix them in one task: if you hand over a list as a campaign, the platform decides itself whom to call and when, and interfering “from above” with individual calls breaks its pacing calculation.
The rest of this page is mostly about campaigns — the reason the Web API is usually connected in the first place; individual calls are covered in Individual calls.
How it works
The access key and getting ready
Issuing a key, what must be ready before the first request, and the pre-launch checklist.
How a campaign runs
What happens after the request, how to read the response, and why the idempotency key is mandatory.
Consent and responsibility
Consent attestation, the do-not-call registry, and what the platform does itself.
When something goes wrong
The common refusals, what they mean and what to do about them.
Technical reference
Calling the API
Base address, authentication, formats and the map of every request.
Creating a campaign
POST /v1/campaigns: headers, request body, the order of refusals.The campaign object
What comes back, and how to read launch blockers and warnings.
Campaign fields
Retries, numbers, dial binding, consent, registry screening, idempotency.
Managing a campaign
Launch, pause, cancel, progress, statistics and adding batches of numbers.
The upload report
What came back for each row of the file, and the row-level issue codes.
Individual calls
POST /v1/calls/phone, the call object, reading, ending and listing.Call outcomes
The outcome axis:
call_status, status_reason and how they fold into a verdict.Webhooks
The
call_ended and call_analyzed events, signing, retries and delivery order.Error codes and an example
The full list of codes and a working scenario in one piece.