If you are integrating rather than clicking, this is the whole path. Four steps, and the last one makes your phone ring.
1 · Get a key
In the dashboard, Settings → Developer → create an API key. It is shown once, at creation — only a hash is stored, so a lost key has to be replaced rather than recovered. It begins with a recognisable prefix and acts with admin rights inside one workspace, so keep it server-side.
Every request carries it as a bearer token in the Authorization header.
2 · Know what a key can reach
A key is scoped to twelve mounts: agents, campaigns, batches, calls, alert, ratings, dashboard, analytics, wallet, balances, numbers and recordings. Anything else answers 403 with a clear message, including endpoints your own user can open in the browser. Billing changes, workspace settings and team management are deliberately outside a key's reach.
This surprises people once and then never again. If you get a 403 on something that clearly exists, check that list before checking your key.
3 · Create an agent, or find one
List your agents and take an id, or create one with a name, a welcome message and a prompt. Everything else has a working default — you do not need to choose a model or a voice to make the first call.
4 · Dial
Post a phone number to the agent's test-call endpoint and your phone rings within a few seconds. Two failures are worth expecting:
- 403 — the monthly minute quota is spent, or the wallet is empty.
- 409 — that number already has a call in flight. The body carries the live call id; wait for it to settle rather than retrying immediately.
Then decide which shape you need
The test-call endpoint is for one number. Past that there are three shapes, and picking the wrong one is the most common early mistake:
- Batches — create, add people, start. Paced by your concurrency limit. This is the right default for a list.
- Campaigns — the same thing built around a CSV upload, for when a human drives it.
- Alert — one request, every number dialled in parallel, returns before they connect. For events, not lists.
The full reference, with request and response for every endpoint in five languages, is at the API docs.