Technology

A call campaign in one request: how the AutoCall.kz API works

← All articles

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

POST
/api/v1/autocalls
POST /api/v1/autocalls
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 }}."
}
The usual way
  1. Create a list
  2. Upload numbers to it
  3. Create an audio recording
  4. Wait for processing
  5. Start the call campaign
Here
  • 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.

422
Unprocessable Entity
← 422 Unprocessable Entity

{
 "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=
POST /api/v1/autocalls // { ..., "client_id": "campaign-2026-07-31" }

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.

One request and your campaign is live

Get a token and launch your first campaign from code.

Try it free →