The usual way to start a call campaign through an API looks like this: create a contact list, wait for it to be processed, upload or synthesize the audio, wait for the conversion, and only then start the campaign. Four requests, two waits and state you have to keep somewhere between steps.
In AutoCall.kz it’s one POST. Not because we cut corners, but because the request fields accept more than just IDs. Let’s look at how it works, along with the parts of the API that integrators trip over most often.
One request instead of four
Authorization: Bearer {your_token}
Content-Type: application/json
{
"name": "Напоминание о приёме",
"type": "regular",
"time_from": "10:00:00",
"time_to": "20:00:00",
// audio: synthesized right here, there’s no file yet
"audio_id": [{
"type": "synthesis",
"data": { "text": "Здравствуйте! Напоминаем о приёме завтра." }
}],
// list: also right here, no need to create it in advance
"list_id": [
{ "number": "+77010000001", "variables": { "name": "Иван", "time": "14:30" } },
{ "number": "+77010000002", "variables": { "name": "Пётр", "time": "16:00" } }
],
"sms_unanswered": true,
"text_unanswered": "{{ name }}, не дозвонились. Ждём вас в {{ time }}."
}
- Create a list
- Upload numbers to it
- Create an audio recording
- Wait for processing
- Start the call campaign
- One
POST - The response is a ready call campaign
- No state to keep between steps
- Nothing can fail halfway
The last point matters more than it seems. Multi-step creation is a distributed transaction without rollback: the list got created, the audio failed to upload, and orphans pile up in your account that nobody cleans up. Here either everything is created, or nothing is.
Why the field is an array, and why it can contain objects
This is the first thing that surprises people about our API: audio_id and list_id are arrays, and mixed ones at that. Let’s go through them one by one.
An array, because there can be several recordings
A call campaign plays several audio recordings in a row. This isn’t redundancy, it’s a working technique: the common opening of the campaign in one file, the variable part in another, the legal note in a third. You change the middle without touching the rest.
The same goes for list_id: a campaign can run on several lists at once. Duplicate numbers across lists are merged, so one person gets one call even if they are in both “Almaty customers” and “debtors.”
An object, because the entity may not exist yet
Now this is the interesting part. An array element can be either the ID of an existing record or an object describing what to create.
| Field | What you can pass |
|---|---|
audio_id |
[5, 7] — IDs of existing recordings[{"type":"synthesis","data":{"text":"..."}}] — synthesis from text[{"type":"upload","data":{"file":"base64..."}}] — file upload[5, {"type":"synthesis", ...}] — both, mixed
|
list_id |
[10, 15] — IDs of existing lists[{"number":"+7701..."}] — numbers directly[{"number":"+7701...","variables":{"name":"Иван"}}] — with variables
|
You can mix freely: take some audio from existing recordings and synthesize the rest on the fly. The service parses the array, creates what’s missing and fills in the resulting IDs.
The practical effect: a one-off call campaign needs no entities in your database. You don’t have to store our list_id, keep it up to date or clean up old lists. Send the numbers, get a call campaign.
If you run campaigns on the same database regularly, create the list once with POST /api/v1/lists and then pass its ID. That way contacts won’t be duplicated in your account from campaign to campaign. Both approaches work and the choice is yours; the API doesn’t force either one.
About variables
The variables field in a contact holds substitutions for personalized texts. They work in SMS messages (text, text_unanswered) and in the AI agent’s script.
An important note to avoid surprises: variables are not substituted into the synthesized audio of a regular call campaign. There is one recording for the whole campaign; otherwise we’d have to generate a separate file for every contact. If you need a truly personalized voice, use an interactive scenario or an AI agent.
Why fields are required “sometimes”
The second place where it’s easy to trip: whether a field is required depends on the value of another field. In POST /autocalls it looks like this:
| If you pass | Becomes required | Why |
|---|---|---|
"type": "regular" |
audio_id |
A regular campaign plays a recording; without it there’s nothing to call with |
"type": "interactive" |
scenario_id |
The scenario runs the conversation |
"type": "agent" |
agent_id |
The AI agent leads the conversation |
"sms": true |
text |
You can’t send an SMS without text |
"sms_unanswered": true |
text_unanswered |
Same for unanswered calls |
time_from |
time_to |
And vice versa: the window bounds are set only as a pair |
That’s how it should be. The alternative is three separate endpoints /autocalls/regular, /autocalls/interactive, /autocalls/agent with nearly identical bodies, and your code duplicates everything they share: schedule, attempts, SMS, callback_url. The campaign type is a property of the campaign, not a separate resource.
If a field is missing, the response says exactly which one and why.
{
"message": "The given data was invalid.",
"errors": {
"audio_id": ["Поле audio id обязательно, когда type равно regular."]
}
}
The HTTP status is the status
This deserves a separate mention, because it breaks more integrations than everything else combined.
Our API has no "status": "ok" field in the response body. The result of an operation is the HTTP code. That’s what it was invented for.
| Code | What happened | What to do |
|---|---|---|
| 201 | Campaign created, funds reserved | Save the id from the response body |
| 202 | Accepted for processing. There are so many recipients that the service will split them into sends in the background; waiting for that inside the HTTP request would be wrong | Also a success. Fetch the result later with a GET by id |
| 402 | Not enough balance to reserve the funds | Top up and retry. Retrying “as is” is pointless |
| 422 | Validation failed | Check errors and fix the request. A retry won’t help |
| 429 | More than 300 requests per minute | Wait and retry; this one you can retry |
The difference between “retrying helps” and “retrying is pointless” is the only reason these codes exist. When a service answers every situation with 200 OK and a body of {"status":"error"}, that difference disappears: your HTTP client treats the request as successful, the retry policy doesn’t kick in, monitoring shows green charts, and the campaign never went out.
The most common integration bug looks like this: the client only checks whether there’s an id in the response and silently ignores 402. The campaign is “sent,” the logs are clean, and there are no calls. Check the response code, not the shape of the body.
How to find your campaign without storing our ID
When creating a campaign, you can pass client_id, your own campaign identifier:
GET /api/v1/autocalls?client_id=campaign-2026-07-31
← 200 OK // that same campaign, with all calls and counters
Handy when you have your own campaign numbering and don’t want to add an extra column for someone else’s IDs. Works the same way in /bulks and /scenarios.
This is a lookup key, not duplicate protection. Two POST requests with the same client_id create two campaigns and reserve the funds twice. Retry idempotency is still on your side.
And a little pedantry about REST
Since we’re talking about APIs, let’s go over a couple of decisions that look like nitpicking but save time.
Creation is a POST, not a GET. Not out of theoretical purity. By the spec, GET is safe and repeatable, and everything around relies on that: browsers and proxies cache such responses, search crawlers follow links on their own, and logs and history store the full URL. Creating a campaign with GET means the campaign can go out again from a “Refresh” click, and contact numbers end up in the web server log in plain text.
Resources in the plural. /autocalls, not /autocall. A collection is a set: /autocalls is all campaigns, /autocalls/42 is the forty-second. A boring rule, but you can guess any endpoint without ever opening the docs.
The request body is JSON, not query parameters. URL length is limited, query strings have no nested structures, and contact numbers and message texts in the address bar are a leak in every log along the request’s path.
What’s next
The full specification is in openapi.yaml: you can feed it to Postman, Insomnia or a client generator and get a ready SDK in your language without rewriting anything by hand. The overview page with examples is API and integrations.
Your token is in your dashboard, under settings. A test campaign to one of your own numbers costs next to nothing, so start there: send the request from the beginning of this article with your number in it.