Campaigns API: call a contact list

A campaign is a contact list plus the rules for dialling it: which agent runs, what hours it may ring people, how many lines it may use at once, how often to retry, and how much it is allowed to spend. You upload the list once and start it. After that the platform handles the dialling. It paces itself, waits through the night, retries calls that did not connect, skips numbers on your do-not-call list, pauses itself when the money runs out or when it has connected as many calls as you asked for, and gives you a per-contact report at the end. A campaign can also stay open. With always_on it keeps running after its list is done, and you add numbers whenever your system has them. Base URL https://sandbox.voice.miraiminds.co.

A campaign is a dialler on top of the call API, so its calls are ordinary calls. They appear in GET /v2/calls, they emit the same call.* webhooks, and they debit the same wallet at the same per-minute rate.

The campaign object

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "name": "Order confirmations — Mumbai batch",
  "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
  "tier": "t3",
  "status": "play",
  "pause_reason": null,
  "timezone": "Asia/Kolkata",
  "start_date": "2026-08-11",
  "end_date": "2026-08-18",
  "slots": [{ "start": "10:00", "end": "19:00" }],
  "max_concurrent": 2,
  "retry_count": 1,
  "re_attempt_period_secs": 900,
  "max_duration_secs": 300,
  "budget_paise": 50000,
  "spent_paise": 12900,
  "webhook_url": "https://example.com/mirai/webhook",
  "always_on": false,
  "pause_after_connected": 200,
  "pause_after_connected_count": 174,
  "pause_after_connected_since": "2026-08-11T04:30:00Z",
  "keyterms": ["Diwali Bonanza", "Gold Plus"],
  "created_at": "2026-08-10T09:21:44Z",
  "updated_at": "2026-08-10T11:04:02Z",
  "counters": { "pending": 812, "dialing": 2, "completed": 174, "no_answer": 9, "suppressed": 3 }
}

Field	Type	Description
`id`	string	`cmp_<ulid>`. Opaque.
`name`	string	Your name for the campaign. 1–120 characters.
`agent_id`	string	The agent every contact is dialled with. Must exist in your workspace at create time.
`tier`	string	The rate card every call in this campaign bills at. Defaults to your key’s tier, which is your company’s plan. See tiers.
`status`	enum	`draft` \| `play` \| `paused` \| `stopped` \| `completed`. See lifecycle.
`pause_reason`	string \| null	Why we paused it. `null` when a human paused it, and `null` whenever it is not paused. See pause reasons.
`timezone`	string	IANA name, e.g. `Asia/Kolkata`. Slots and dates are local to this timezone.
`start_date` / `end_date`	string	`YYYY-MM-DD`, inclusive, local dates.
`slots`	array	1–4 `{start, end}` windows in `HH:MM`, local time. See calling window.
`max_concurrent`	integer	1–50. How many of this campaign’s calls may be live at once.
`retry_count`	integer	0–5. Retries after the first attempt. `0` means one attempt per contact.
`re_attempt_period_secs`	integer	60–86400. How long a contact waits before it is eligible again.
`max_duration_secs`	integer	30–1800. Per-call cap. Defaults to the agent’s.
`budget_paise`	integer \| null	Spend cap in paise. `null` means no cap.
`spent_paise`	integer	Billed so far, in paise.
`webhook_url`	string	Receives both this campaign’s `campaign.` events and every child call’s `call.` events.
`always_on`	boolean	`true` keeps the campaign running after everyone on its list has been called, so contacts added later are called too. Always present. See always-on campaigns.
`pause_after_connected`	integer \| null	The campaign pauses itself once this many calls have connected. `null` means no limit. Always present. See pause after connected calls.
`pause_after_connected_count`	integer	Read-only. Connected calls counted toward `pause_after_connected` so far. Present only while a limit is set, and only when you read one campaign (omitted from list pages).
`pause_after_connected_since`	string	Read-only. RFC 3339 time the current count began. Present with `pause_after_connected_count`.
`keyterms`	array of strings	Words speech recognition listens for on this campaign’s calls, before its agent’s own: brand, product, place and people names. Up to 100. Always present, `[]` when there are none. See words to catch.
`keyterm_spellings`	object	Read-only. The keyterms written in the scripts of the calls’ languages, which the calls also listen for, by term and then language. Only when you read one campaign, and absent while there are none. See spellings.
`counters`	object	Contacts by status. Present on `GET /v2/campaigns/{id}`, omitted from list pages.

Campaign money is in paise, call money is in rupees.budget_paise and spent_paise are integer paise (100 paise = ₹1), so a ₹500 cap is "budget_paise": 50000. The call object and the wallet use rupee fields (amount_inr, balance_inr). No object mixes the two units.

Lifecycle

Status	Dials?	Meaning
`draft`	❌	Created. Accepts contacts and edits. Nothing rings until you start it.
`play`	✅	Running, though it may be asleep. Outside the calling window the status is still `play` while the dialler waits for the window to open.
`paused`	❌	Reversible. New calls stop; calls already in progress are not hung up.
`stopped`	❌	Terminal, set by you. Live calls are aborted and pending contacts are marked `aborted`.
`completed`	❌	Terminal, set by us when every contact has reached a final state or the date range has run out. An always-on campaign completes only when its date range runs out.

Only draft and paused campaigns can be edited or started. stopped and completed campaigns never dial again, and they refuse new contacts with 409 because those rows would never ring.

Pause reasons

pause_reason tells you whether the operator paused the campaign or we paused it for them. A pause you asked for has no reason (null), or the reason you sent with it. The money gate sets insufficient_balance and budget_exhausted, your connected-call limit sets connected_limit_reached, and a number or pool that cannot call sets calls_from_unavailable.

`pause_reason`	Set when	What to do
`null`	You called `POST /pause` with no body.	Resume when you are ready.
`<by>: <reason>`	You called `POST /pause` with a `reason` or `by`.	Resume when you are ready.
`insufficient_balance`	The wallet cannot cover another minute at this campaign’s tier.	Add credit, then `POST /start` or `/resume`.
`budget_exhausted`	`spent_paise` has reached `budget_paise`.	Raise `budget_paise` with `PATCH`, then resume.
`connected_limit_reached`	`pause_after_connected` calls have connected since the count began.	Resume when you want the next batch; the count starts again from zero. See pause after connected calls.
`calls_from_unavailable: …`	The pool or number the campaign calls from can no longer place calls. The reason names it.	Add a ready number to the pool, or choose another, then resume.

Every pause, and every start, resume, stop and change to the connected-call limit, is recorded in the campaign’s history, with who did it.

Being outside the calling window is not a pause. The campaign stays play and sleeps until the window next opens. The sleep is durable, so a campaign scheduled for 10:00 tomorrow costs nothing overnight and survives our restarts. An offline fleet is not a pause either. It is a 503 fleet_offline refusal at start time.

Contact statuses

Every row you upload has its own status. The first block mirrors the call status vocabulary, so a campaign report reads the same way the call list does. The rest exist only inside campaigns.

Status	Terminal	Meaning
`pending`		Waiting to be dialled: either never attempted, or waiting out `re_attempt_period_secs`.
`claimed`		Picked up by the dialler this tick.
`dialing`		A call has been placed for this contact.
`completed`	✅	Connected and finished. Billed.
`voicemail`	✅	An answering machine answered. Billed. Never retried.
`timeout`	✅	Hit `max_duration_secs`. Billed. Never retried.
`no_answer`	✅	Rang out. Free. Retried while attempts remain.
`busy`	✅	Line busy. Free. Retried while attempts remain.
`failed`	✅	Did not connect, or our pipeline errored. Free. Retried while attempts remain.
`exhausted`	✅	Retried up to `retry_count + 1` attempts and never connected.
`suppressed`	✅	The number is on your do-not-call list. Never dialled or billed.
`aborted`	✅	The campaign was stopped while this contact was pending or in flight.
`skipped`	✅	A pre-call `skip_call` condition held, so we did not dial. Free. Never retried.
`cancelled`	✅	You cancelled the contact while it was waiting. Never dialled again unless you call it again.

Watch exhausted. It counts the people we tried with every attempt you paid for and never reached. A contact that ends no_answer still had attempts left; one that ends exhausted did not. A contact waiting for its next retry is pending again, with attempts above zero and eligible_at set to when the retry may ring. To stop that retry, for example because the customer already did what the call was for, cancel the contact.

Calling window

Two checks decide whether the dialler may ring right now, both in the campaign’s own timezone:

today’s local date is between start_date and end_date, inclusive; and
the local HH:MM falls inside at least one slots entry.

{
  "timezone": "Asia/Kolkata",
  "start_date": "2026-08-11",
  "end_date": "2026-08-18",
  "slots": [
    { "start": "10:00", "end": "13:00" },
    { "start": "16:00", "end": "19:00" }
  ]
}

1 to 4 slots. Fewer is a 400; five is a 400.
A slot may cross midnight. 21:00 to 06:00 is open on both sides of it. The API accepts this, but it is almost never what you want in India. See calling rules.
A zero-length slot is a 400. We reject {"start":"10:00","end":"10:00"} instead of reading it as “all day”, because guessing wrong there means ringing somebody at 03:00.
Times are local. We store and evaluate them in timezone, not UTC, so Asia/Kolkata’s half-hour offset and every daylight-saving boundary are handled for you.

When the date range runs out entirely, the campaign finishes as completed, even if some contacts are still pending, because no window remains to dial them in.

A campaign whose window has already closed for good cannot be started. POST /start and POST /resume refuse it with 409 window_closed, instead of accepting it and finishing it as completed a second later with no calls.The usual cause is start_date and end_date both set to today, with a slot that has already ended. Extend end_date, or add a slot that is still ahead, with PATCH. Then start it again.A campaign started outside its window that opens again later is still accepted. It stays play and sleeps until the window opens.

Retries

Knob	Range	Effect
`retry_count`	0–5	Retries after the first attempt. `1` means up to 2 attempts total.
`re_attempt_period_secs`	60–86400	Minimum wait before a contact becomes eligible again.

Only outcomes that never reached a human are retried: no_answer, busy and failed. completed, voicemail and timeout all produced live media, which means the call happened. Re-dialling somebody who already spoke to us is worse than not calling at all. A retry that comes due outside the calling window waits for the window to open. The retry wait is a minimum, and the actual retry can come later.

Budget and pacing

max_concurrent (1 to 50) is this campaign’s own ceiling on live calls. It is separate from your workspace concurrency and queue-depth limits, which also apply. Two campaigns at max_concurrent: 20 on a workspace provisioned for 5 concurrent calls will share those 5. budget_paise caps the spend of this campaign alone. When spent_paise reaches it, the campaign pauses with budget_exhausted. Contacts keep their place, so if you raise the budget and resume, the campaign continues where it stopped. The wallet is checked before every dialling tick. If it cannot cover another minute at the campaign’s tier, the campaign pauses with insufficient_balance. POST /start also does a wallet estimate up front and tells you how far your balance goes, in funded_calls.

Set budget_paise on every campaign, even when you trust the list. It is the one control that limits the cost of a mistake in the list itself, such as a duplicated CSV or a column shifted by one.

Pause after connected calls

Set pause_after_connected and the campaign pauses itself once that many calls have connected. Resume it when you want the next batch. Use it to keep a long campaign in step with the people who act on its calls: run a list for a month, pause after every 50 conversations, and resume when your team has followed up. What counts as connected. A contact whose call ended completed or timeout, which means a person answered and talked. voicemail, no_answer, busy, failed and skipped don’t count. This is narrower than the report’s connected, which also counts voicemail. When the count starts. Counting begins when you turn the limit on, from null to a number. It starts again from zero each time you resume or start the campaign after the limit paused it. Other pauses (yours, the wallet, the budget) keep the count where it was. Changing the number keeps the count, so with 30 counted, moving the limit from 50 to 80 means 50 more calls. Setting it back to null removes the limit and its count. How it lands on the number. Near the limit, the campaign rings only as many people as it still needs, so it stops on the number you set. Calls already in progress always finish, because a pause never hangs up on anyone. If you lower the limit below the current count, the campaign pauses at its next check. When it pauses, status is paused, pause_reason is connected_limit_reached, and you get the usual campaign.paused webhook. The pause is in the campaign’s history, with the limit and the count.

Rule	Value
Range	1–100000, or `null` for no limit.
Set it	On create, on a copy, or with `PATCH`.
While running	Yes. `PATCH` takes it on a `play` campaign and it applies from the next call.
Finished campaigns	Can’t be edited, like every other setting.

Example: pause a running campaign every 50 conversations

cURL
Python
Node.js

# Turn the limit on. The count starts now.
curl -X PATCH https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Mirai-Actor: Priya (sales ops)" \
  -d '{ "pause_after_connected": 50 }'

# Later, when the team is ready for the next 50:
curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/resume \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Mirai-Actor: Priya (sales ops)"

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}",
        "Mirai-Actor": "Priya (sales ops)"}
CAMPAIGN = "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB"


def pause_every(n):
    r = httpx.patch(f"{API}/v2/campaigns/{CAMPAIGN}", headers=auth,
                    json={"pause_after_connected": n}, timeout=30)
    return r.raise_for_status().json()


def next_batch():
    """Resume after the limit paused the campaign. The count starts again."""
    c = httpx.get(f"{API}/v2/campaigns/{CAMPAIGN}", headers=auth, timeout=30).raise_for_status().json()
    if c["status"] != "paused" or c["pause_reason"] != "connected_limit_reached":
        return c["status"]
    httpx.post(f"{API}/v2/campaigns/{CAMPAIGN}/resume", headers=auth, timeout=30).raise_for_status()
    return "resumed"

const API = "https://sandbox.voice.miraiminds.co";
const auth = {
  Authorization: `Bearer ${process.env.MIRAI_API_KEY}`,
  "Mirai-Actor": "Priya (sales ops)",
};
const CAMPAIGN = "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB";

async function pauseEvery(n) {
  const res = await fetch(`${API}/v2/campaigns/${CAMPAIGN}`, {
    method: "PATCH",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({ pause_after_connected: n }),
  });
  if (!res.ok) throw new Error(`PATCH failed: ${res.status}`);
  return res.json();
}

// Resume after the limit paused the campaign. The count starts again.
async function nextBatch() {
  const c = await (await fetch(`${API}/v2/campaigns/${CAMPAIGN}`, { headers: auth })).json();
  if (c.status !== "paused" || c.pause_reason !== "connected_limit_reached") return c.status;
  const res = await fetch(`${API}/v2/campaigns/${CAMPAIGN}/resume`, { method: "POST", headers: auth });
  if (!res.ok) throw new Error(`resume failed: ${res.status}`);
  return "resumed";
}

200 OK — the PATCH answer, trimmed

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "status": "play",
  "pause_reason": null,
  "pause_after_connected": 50,
  "pause_after_connected_count": 0,
  "pause_after_connected_since": "2026-11-05T08:30:00Z"
}

GET /v2/campaigns/{id} shows pause_after_connected_count climbing. To act the moment a batch is done, listen for campaign.paused with data.campaign.pause_reason set to connected_limit_reached.

Always-on campaigns

An ordinary campaign completes once every contact has reached a final state, and from then on it refuses new contacts. Set always_on: true and the campaign stays open instead. When it has called everyone on its list it stays play and waits. Contacts you add later are called under the same rules as the first ones: inside the calling window, within max_concurrent, and retried up to retry_count times. Use it to run a queue. Keep one open campaign for an agent and add each number as your system produces it, such as a new order or a new lead, instead of placing single calls. Every number then gets calling hours, pacing and retries, which POST /v2/calls does not do. You can set always_on:

when you create the campaign, or on a copy made with POST /v2/campaigns/{id}/duplicate, which keeps the source’s value unless you send another;
with PATCH while the campaign is draft or paused. On a running campaign the change is refused with 409 conflict, so pause it, patch it and resume it.

It is returned on the campaign object, on list pages, in the add-contacts response and as data.campaign.always_on on every campaign webhook. An always-on campaign ends when you stop it, or when its end_date is behind it. Then it completes and sends campaign.completed as usual. Set end_date as far ahead as you want the campaign to stay open. To move it later, pause the campaign, PATCH the new end_date and resume. Running out of contacts never completes it and sends no event. The money rules are the same as for any campaign. The wallet check pauses it with insufficient_balance, and budget_paise pauses it with budget_exhausted. On an open campaign the budget counts everything it has ever spent, so treat it as a ceiling you raise from time to time, or leave it unset and rely on the wallet. A contact added while the campaign is waiting is called straight away when the calling window is open, and when the window next opens otherwise. If that wake-up is ever lost, the campaign looks at its list again within five minutes.

Give each contact its own id in an always-on campaign. A contact you add with an id, such as an order or cart id, is unique by that id: the same number comes back next week under a new id and is called again, and the same id sent twice counts in contacts_duplicate. A contact sent without an id is unique by phone for the whole life of the campaign, and so is every contact of a campaign that is not always-on. Two contacts on one number are never dialled at the same time. To call a contact again with the details it already has, use POST /v2/campaigns/{id}/contacts/{contact_id}/retry.

Example: one open campaign, numbers added as they come

Create the campaign once and start it:

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmations (open)",
    "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
    "timezone": "Asia/Kolkata",
    "start_date": "2026-10-15",
    "end_date": "2027-03-31",
    "slots": [{ "start": "10:00", "end": "19:00" }],
    "max_concurrent": 5,
    "retry_count": 2,
    "re_attempt_period_secs": 3600,
    "always_on": true,
    "webhook_url": "https://example.com/mirai/webhook"
  }'

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K8QAC5N9P4R7S3T6V8W2X4YB/start \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Then add each new order as it is placed:

cURL
Python
Node.js

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K8QAC5N9P4R7S3T6V8W2X4YB/contacts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "id": "order-8842", "phone": "+919876543210",
        "variables": { "customer_name": "Rahul", "order_id": "8842" },
        "metadata": { "order_id": "8842" } }
    ]
  }'

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}
CAMPAIGN = "cmp_01K8QAC5N9P4R7S3T6V8W2X4YB"


def queue_confirmation_call(order):
    r = httpx.post(
        f"{API}/v2/campaigns/{CAMPAIGN}/contacts",
        headers=auth,
        json={"contacts": [{
            "id": f"order-{order.id}",
            "phone": order.phone,  # E.164, e.g. +919876543210
            "variables": {"customer_name": order.first_name, "order_id": str(order.id)},
            "metadata": {"order_id": str(order.id)},
        }]},
        timeout=30,
    )
    if r.status_code == 409:
        raise RuntimeError("campaign has finished; create a new one")  # stopped or end_date passed
    added = r.raise_for_status().json()
    if added["contacts_rejected"]:
        raise ValueError(added["contacts_rejected"][0]["reason"])
    return added["contacts_accepted"] == 1  # False: this contact is already in the campaign

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };
const CAMPAIGN = "cmp_01K8QAC5N9P4R7S3T6V8W2X4YB";

async function queueConfirmationCall(order) {
  const res = await fetch(`${API}/v2/campaigns/${CAMPAIGN}/contacts`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      contacts: [{
        id: `order-${order.id}`,
        phone: order.phone, // E.164, e.g. +919876543210
        variables: { customer_name: order.firstName, order_id: String(order.id) },
        metadata: { order_id: String(order.id) },
      }],
    }),
  });
  if (res.status === 409) throw new Error("campaign has finished; create a new one");
  const added = await res.json();
  if (!res.ok) throw new Error(`${added.error.code}: ${added.error.message}`);
  if (added.contacts_rejected.length) throw new Error(added.contacts_rejected[0].reason);
  return added.contacts_accepted === 1; // false: this contact is already in the campaign
}

200 OK

{
  "id": "cmp_01K8QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "status": "play",
  "always_on": true,
  "contacts_accepted": 1,
  "contacts_duplicate": 0,
  "contacts_rejected": []
}

contacts_accepted: 1 means the number is in line to be called, unless it is on your do-not-call list when its turn comes. Each call sends the ordinary call.* webhooks to the campaign’s webhook_url with order_id in data.call.metadata, and GET /v2/campaigns/{id}/contacts shows where every number is, attempts included.

Create a campaign

POST /v2/campaigns

Request

Field	Type	Required	Description
`name`	string	yes	1–120 characters.
`agent_id`	string	yes	Must exist in your workspace.
`agent_revision`	integer	no	A saved, published version of the agent to use. Defaults to its current one.
`tier`	string	no	`t1` \| `t3` \| `t5`. Defaults to your key’s tier, which is your company’s plan, so leave it out. Calls at any other tier are not covered by your plan. Before your company goes live, campaigns run at `t5`, whatever you send.
`timezone`	string	yes	IANA name, e.g. `Asia/Kolkata`.
`start_date` / `end_date`	string	yes	`YYYY-MM-DD`, local, inclusive.
`slots`	array	yes	1–4 × `{start, end}` as `HH:MM`.
`max_concurrent`	integer	no	1–50. Default `1`.
`retry_count`	integer	no	0–5. Default `0`.
`re_attempt_period_secs`	integer	no	60–86400. Default `900`.
`max_duration_secs`	integer	no	30–1800. Defaults to the agent’s.
`budget_paise`	integer	no	Positive paise. Omit for no cap.
`webhook_url`	string	no	HTTPS. Gets `campaign.` and* `call.` events, and the `phone_number.` and `phone_pool.*` events for numbers and pools the campaign calls from.
`phone_number_id`	string \| null	no	One of your own phone numbers to call from. `null` clears it.
`pool_id`	string \| null	no	A phone pool to call from, spreading calls across its numbers at its pace. Exclusive with `phone_number_id` and `caller_ids`. `null` clears it. The campaign object returns `pool_id` and a `calls_from` object that names where its number comes from.
`always_on`	boolean	no	Default `false`. `true` keeps the campaign open after its list is done, so you can keep adding contacts. See always-on campaigns.
`pause_after_connected`	integer \| null	no	1–100000. The campaign pauses itself once this many calls have connected. Omit it, or send `null`, for no limit. See pause after connected calls.
`keyterms`	array of strings	no	Up to 100 words for speech recognition to listen for on this campaign’s calls, before the agent’s own. See words to catch.
`final_results`	boolean	no	Default `true`. Each call ends with one `call.processed` carrying the transcript, the after-call results and the contact’s `metadata`. `false` sends the shorter events only. Change it while the campaign is a draft or paused.
`contacts`	array	no	Up to 1000 rows per request. `{phone, variables?, metadata?, call_settings?, id?}`. Add more later.

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmations — Mumbai batch",
    "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
    "timezone": "Asia/Kolkata",
    "start_date": "2026-08-11",
    "end_date": "2026-08-18",
    "slots": [{ "start": "10:00", "end": "19:00" }],
    "max_concurrent": 2,
    "retry_count": 1,
    "re_attempt_period_secs": 900,
    "max_duration_secs": 300,
    "budget_paise": 50000,
    "webhook_url": "https://example.com/mirai/webhook",
    "contacts": [
      { "id": "cust-1001", "phone": "+919876543210",
        "variables": { "customer_name": "Rohit Sharma", "order_id": "AC-88213" } },
      { "id": "cust-1002", "phone": "+919876543211",
        "variables": { "customer_name": "Anita Desai", "order_id": "AC-88219" } }
    ]
  }'

201 Created

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "name": "Order confirmations — Mumbai batch",
  "agent_id": "agt_01K7Q9F3K7M2N5P9R4T6V8W0XZ",
  "tier": "t3",
  "status": "draft",
  "pause_reason": null,
  "timezone": "Asia/Kolkata",
  "start_date": "2026-08-11",
  "end_date": "2026-08-18",
  "slots": [{ "start": "10:00", "end": "19:00" }],
  "max_concurrent": 2,
  "retry_count": 1,
  "re_attempt_period_secs": 900,
  "max_duration_secs": 300,
  "budget_paise": 50000,
  "spent_paise": 0,
  "webhook_url": "https://example.com/mirai/webhook",
  "created_at": "2026-08-10T09:21:44Z",
  "updated_at": "2026-08-10T09:21:44Z",
  "contacts_accepted": 2,
  "contacts_duplicate": 0,
  "contacts_rejected": []
}

The response is the campaign object itself, with three extra top-level keys. It is not wrapped as {"campaign": …, "contacts": …}. Read the id at .id, and the upload result at .contacts_accepted / .contacts_duplicate / .contacts_rejected.

Contacts are reported row by row, not rejected as a batch

If a 900-row upload has two bad numbers, we store the good rows and return the bad ones by index instead of failing the whole upload with 400:

201 Created — two rows rejected, one duplicate

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "status": "draft",
  "contacts_accepted": 3,
  "contacts_duplicate": 1,
  "contacts_rejected": [
    { "index": 1, "phone": "9876543211", "reason": "phone must be an E.164 number" },
    { "index": 4, "phone": "+91984500112", "reason": "phone must be an E.164 number" }
  ]
}

Counter	Meaning
`contacts_accepted`	Rows stored and dialable.
`contacts_duplicate`	The contact was already in this campaign, or repeated inside this batch: the same `id` in an always-on campaign, otherwise the same phone number. We deduplicate on purpose, so this is not an error.
`contacts_rejected`	Rows we could not store, each with the index in the array you sent and why.

Two things do fail the whole request: more than 1000 rows (400 invalid_request) and a malformed body. Every other problem is reported per row. variables follow the same rules as call variables (a flat string map, 32 keys, 512 characters per value) and fill the same {{placeholders}} in the agent’s prompt. id is your own key for the row. If you omit it, we mint one.

Your own fields: `metadata`

Most lists carry more than the agent needs: a CRM lead id, a branch, where the lead came from. Put those in metadata, not variables:

{ "id": "cust-1001", "phone": "+919876543210",
  "variables": { "customer_name": "Rohit Sharma", "order_id": "AC-88213" },
  "metadata": { "crm_id": "L-17", "branch": "Pune" } }

The agent never sees it. It is not a variable and is not in the prompt.
It stays with the contact: List contacts returns it.
Every call to that contact carries it as the call’s metadata, so data.call.metadata in each call.* webhook tells you which of your records the call was for.
It follows the same rules as call metadata: up to 16 keys, string values of up to 256 characters, 4 KB in total. A row that breaks them is rejected by index like any other bad row.

A value the agent needs and your system matches on, like a loan number, can go in both: variables for the agent and metadata for your webhooks. In the console, a CSV column set to Extra info is sent as metadata, and Both sends it in each. See Campaigns in the console.

If the agent declares its variables (input_schema), a variable it does not declare rejects the row. Send those extra columns as metadata instead.

Voice and language per contact

Give a contact its own call_settings, and its calls use that voice and those languages in place of the agent’s. People on one list can hear a different voice, or be understood in a different language.

{ "id": "cust-1003", "phone": "+919876543212",
  "variables": { "customer_name": "Mehul Patel", "order_id": "AC-88240" },
  "call_settings": { "voice_id": "sameer", "language": "gu", "secondary_languages": ["en"] } }

The keys and rules are the same as on POST /v2/calls. A key you leave out keeps the agent’s value.
A contact with a bad value is rejected on its own row in contacts_rejected, with the reason, and the rest of the list goes in.
We check the values again when the contact is dialled. If a key no longer passes, for example because a voice left the catalogue after you uploaded the list, that call keeps the agent’s value for it.
A pre-call tool on the agent can still change them call by call. Each call’s call_settings.sources says campaign for a value that came from the contact.
List contacts returns them, and a duplicated campaign keeps them.

In a CSV upload, the columns call_settings.voice_id, call_settings.language and call_settings.secondary_languages set the same keys. Separate secondary languages with commas, for example hi,en. An existing language column stays a variable.

Errors

Status	`error.code`	Cause
`400`	`invalid_request`	Missing `name`/`agent_id`/`timezone`/dates/`slots`, a knob out of range, a bad window, or more than 1000 contacts.
`400`	`invalid_flow`	`agent_id` is a node-based agent and your tier’s model cannot run flows. Checked again at start and resume.
`404`	`not_found`	`agent_id` does not exist in your workspace. We check this at create time, so a typo fails now instead of failing every contact tomorrow morning. The same code answers a `pool_id` or `phone_number_id` that is not yours.
`409`	`pool_unavailable`, `number_retired`	The pool has no number that can call, or the number is retired. See phone numbers and pools.
`501`	`tier_unavailable`	`tier` names a tier that is not enabled on this deployment.
`503`	`campaigns_unavailable`	Campaigns are not enabled for your workspace. Your request is fine; ask us to enable them.

List campaigns

GET /v2/campaigns?limit=&cursor=

curl -G https://sandbox.voice.miraiminds.co/v2/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "limit=20"

Returns the standard paginated envelope of campaign objects, newest first. counters is omitted on list pages; fetch one campaign to get them.

Get a campaign

GET /v2/campaigns/{id}

curl https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "name": "Order confirmations — Mumbai batch",
  "tier": "t3",
  "status": "paused",
  "pause_reason": "insufficient_balance",
  "spent_paise": 49800,
  "budget_paise": 50000,
  "counters": {
    "pending": 612,
    "completed": 174,
    "no_answer": 9,
    "exhausted": 2,
    "suppressed": 3
  },
  "created_at": "2026-08-10T09:21:44Z",
  "updated_at": "2026-08-10T11:04:02Z"
}

counters comes from the contact table, not from the running dialler, so a finished campaign answers exactly like a live one and you can safely build a dashboard on this endpoint. 404 not_found for an unknown id and for one in another workspace. The two responses are identical on purpose.

Update a campaign

PATCH /v2/campaigns/{id}

While the campaign is draft or paused you can change: name, slots, start_date, end_date, max_concurrent, retry_count, re_attempt_period_secs, max_duration_secs, budget_paise, webhook_url, skip_called_before, final_results, always_on, pause_after_connected and keyterms. Not patchable: agent_id, tier, timezone. While it is running, only the pacing, the agent’s version, the connected-call limit and the keyterms can change: max_concurrent, slots, agent_revision, pause_after_connected and keyterms. They take effect straight away. Anything else returns 409 conflict, because changing the retry policy or the budget under a live dialler would leave the campaign’s own report describing settings that were never in force for half of its calls. Pause it, patch it, then resume it. A finished campaign can’t be edited.

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "budget_paise": 120000, "max_concurrent": 4 }'

Returns 200 OK with the campaign object. A change to pause_after_connected is recorded in the campaign’s history.

Switch to the agent’s latest version

A campaign keeps the version of its agent it was created with. If you change the agent later (a new voice, a new prompt), the campaign’s calls don’t pick that up on their own. The campaign object shows the version it uses in agent_revision, and GET /v2/agents/{id} shows the agent’s current revision. To move the campaign onto the new version, send that revision. This works while the campaign is running, so you don’t need to pause it:

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_revision": 5 }'

The next calls use the new version. Calls already in progress finish as they started. A contact whose own call_settings name a voice keeps that voice. You can also send an older revision to go back. In the console, the campaign page shows Use the latest version when the agent has changed.

Status	Code	When
`400`	`invalid_request`	`agent_revision` is not a positive number, or that revision is a draft. Publish the agent first.
`404`	`not_found`	The agent has no such revision.
`409`	`agent_archived`	The agent is archived. Restore it first.
`409`	`agent_inputs_changed`	That version needs variables some waiting contacts don’t have. The message names the first one.
`503`	`fleet_offline`	A running campaign only: calling capacity for that version’s voice is offline. Try again in a few minutes.

Words to catch

keyterms are the names your contacts may say that a recogniser tends to mishear, such as a product, an offer or a city. A campaign’s calls listen for its own keyterms first, then its agent’s, at most 200 in all. You can change them while the campaign is running, without pausing it:

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyterms": ["Diwali Bonanza", "Gold Plus", "Koramangala"] }'

The list you send replaces the saved one. [] or null clears it, and a PATCH without keyterms leaves it alone.
The next call uses the new list. Calls already in progress keep theirs.
Up to 100 terms, each 1 to 50 characters and at most 5 words, with no comma. A list that breaks a rule is refused with 400 invalid_request, and the message names the term.
GET /v2/campaigns/{id} also returns keyterm_spellings: the same terms in the script of the agent’s languages, added for you a short while after you save.

The agent’s own keyterms come from the revision the campaign uses. In the console, the list is Words to catch on the campaign form. Words to catch covers what to put on the list.

Add contacts

POST /v2/campaigns/{id}/contacts

Up to 1000 rows per request. For a larger list, call it repeatedly. Each row takes the same fields as on create, metadata and call_settings included. A draft, play or paused campaign accepts new contacts. When a running campaign had nothing left to dial, the add wakes it, so the new contacts are called straight away if the calling window is open.

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/contacts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "id": "cust-2001", "phone": "+919812345678",
        "variables": { "customer_name": "Vikram Rao", "order_id": "AC-88224" },
        "metadata": { "crm_id": "L-2201" } },
      { "id": "cust-2002", "phone": "+919833221100",
        "variables": { "customer_name": "Meera Nair", "order_id": "AC-88231" } }
    ]
  }'

200 OK

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "object": "campaign",
  "status": "play",
  "contacts_accepted": 2,
  "contacts_duplicate": 0,
  "contacts_rejected": []
}

The response has the same shape as the create response, so one parser in your client handles both routes that add contacts. 409 conflict if the campaign is stopped or completed. Nothing would ever dial those rows, so we refuse them instead of accepting them silently. The status check runs in the same database transaction as the insert, under a lock the campaign also takes when it completes. A campaign that completes at the moment you add contacts therefore does one of two things: it counts your new contacts and calls them, or it completes first and your request gets 409 conflict with nothing stored. A 200 never leaves contacts on a campaign that has finished.

List contacts

GET /v2/campaigns/{id}/contacts?status=&limit=&cursor=

Query param	Description
`status`	Filter by one contact status, e.g. `exhausted`.
`limit`	1–100, default 20.
`cursor`	From `next_cursor`.

curl -G https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/contacts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "status=exhausted" \
  --data-urlencode "limit=100"

200 OK

{
  "data": [
    {
      "id": "cust-1002",
      "phone": "+919876543211",
      "status": "exhausted",
      "attempts": 2,
      "variables": { "customer_name": "Anita Desai", "order_id": "AC-88219" },
      "metadata": { "crm_id": "L-1002" },
      "last_call_id": "call_01K7QB4M8N3P6R2S5T7V9W1YA",
      "last_status": "no_answer",
      "eligible_at": "2026-08-11T11:19:02Z",
      "updated_at": "2026-08-11T11:34:10Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

last_call_id is an ordinary call_ id: fetch it from GET /v2/calls/{id} for the full outcome. A contact without metadata has no metadata field, and one without call_settings has no call_settings field.

Call a contact again

POST /v2/campaigns/{id}/contacts/{contact_id}/retry

Puts one contact back in line, even one that has used all its retries: completed, voicemail, no_answer, busy, timeout, failed, exhausted or cancelled. It becomes pending, eligible now, and keeps attempts, last_call_id and last_status. attempts goes up by one when the new call is placed. On a running campaign it rings as soon as the calling window and pacing allow, and the call spends credit. Answers 200 with the contact, in the same shape as List contacts. Allowed while the campaign is draft, paused or play.

Status	`error.code`	Cause
`409`	`contact_in_progress`	The contact is already waiting or being called. A second retry is refused, so a double click never calls anyone twice.
`409`	`contact_suppressed`	The contact is `suppressed` or `skipped`, its number is on the do-not-call list, or `skip_called_before` applies.
`409`	`campaign_finished`	The campaign is `stopped` or `completed`. Start a new campaign for these contacts.
`409`	`campaign_archived`	Restore the campaign first.
`404`	`not_found`	No such campaign in your workspace, or no such contact in it.

Remove a contact

DELETE /v2/campaigns/{id}/contacts/{contact_id}

Takes a contact off the list before its first call, for example a number added by mistake. Only a contact that has never been dialled can be removed: status pending, attempts 0, not being called. Answers 204 with no body, and the campaign’s counters no longer include it. The number can be added again. Once a contact has a call it is part of the campaign’s record and stays. To stop its next retry, cancel it. To stop every future call to a number, add it to the do-not-call list.

curl -X DELETE https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/contacts/cust-2002 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Status	`error.code`	Cause
`409`	`contact_dialled`	The contact has been called, or is being called right now.
`409`	`campaign_finished`	The campaign is `stopped` or `completed`. Its list is its record.
`404`	`not_found`	No such campaign in your workspace, or no such contact in it, including one already removed.

Cancel a contact

POST /v2/campaigns/{id}/contacts/{contact_id}/cancel

Stops calling one contact that is waiting: one not called yet, or one waiting for its next retry after a call nobody picked up. Use it when the reason for the call goes away between attempts. A shopper completes the order you were going to remind them about, a customer pays the bill, a lead books on your site. The contact becomes cancelled. It is not called again, and the campaign no longer waits for it, so a campaign that is not always-on can complete without it. Its attempts, last_call_id and last_status stay, and it stays in List contacts and the report. Allowed while the campaign is draft, paused or play. A call that is already ringing or in conversation is never cut off. The cancel answers 409 contact_in_call. Send it again once the call ends: if the call reached nobody and a retry is booked, the retry is cancelled. To end a live call, use POST /v2/calls/{id}/abort with that call’s id (data.call.id in its webhooks).

cURL
Python
Node.js

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K8QAC5N9P4R7S3T6V8W2X4YB/contacts/order-8842/cancel \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

import os, time
from urllib.parse import quote

import httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}
CAMPAIGN = "cmp_01K8QAC5N9P4R7S3T6V8W2X4YB"


def cancel_order_call(order_id, tries=5):
    """Stop calling about an order once it has been placed."""
    url = f"{API}/v2/campaigns/{CAMPAIGN}/contacts/{quote(f'order-{order_id}', safe='')}/cancel"
    for _ in range(tries):
        r = httpx.post(url, headers=auth, timeout=30)
        if r.status_code == 200:
            return "cancelled"
        code = r.json()["error"]["code"] if r.status_code in (404, 409) else None
        if code == "contact_in_call":
            time.sleep(60)  # a call is in progress; it is never cut off
            continue
        if code in ("contact_finished", "campaign_finished", "not_found"):
            return code  # nothing is waiting to be cancelled
        r.raise_for_status()
    return "still_in_call"

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };
const CAMPAIGN = "cmp_01K8QAC5N9P4R7S3T6V8W2X4YB";

// Stop calling about an order once it has been placed.
async function cancelOrderCall(orderId, tries = 5) {
  const contact = encodeURIComponent(`order-${orderId}`);
  const url = `${API}/v2/campaigns/${CAMPAIGN}/contacts/${contact}/cancel`;
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, { method: "POST", headers: auth });
    if (res.ok) return "cancelled";
    const { error } = await res.json();
    if (error.code === "contact_in_call") {
      await new Promise((r) => setTimeout(r, 60_000)); // never cut off; try after it ends
      continue;
    }
    if (["contact_finished", "campaign_finished", "not_found"].includes(error.code)) {
      return error.code; // nothing is waiting to be cancelled
    }
    throw new Error(`${error.code}: ${error.message}`);
  }
  return "still_in_call";
}

200 OK

{
  "id": "order-8842",
  "phone": "+919876543210",
  "status": "cancelled",
  "attempts": 1,
  "variables": { "customer_name": "Rahul", "order_id": "8842" },
  "metadata": { "order_id": "8842" },
  "last_call_id": "call_01K8QB4M8N3P6R2S5T7V9W1YA",
  "last_status": "no_answer",
  "eligible_at": "2026-10-15T11:19:02Z",
  "updated_at": "2026-10-15T11:16:40Z"
}

The answer is the contact, in the same shape as List contacts. Cancelling a contact that is already cancelled answers 200 with it again, so a repeated request (a webhook delivered twice, a retried job) is safe. To call a cancelled contact after all, call it again.

Status	`error.code`	Cause
`409`	`contact_in_call`	The contact is being called right now. The call is not cut off; try again after it ends.
`409`	`contact_finished`	The contact already has an outcome (`completed`, `voicemail`, `timeout`, `exhausted`, `skipped`, `suppressed`, `aborted` and the like) and is not waiting for any call. The message names its status.
`409`	`campaign_finished`	The campaign is `stopped` or `completed`. A stop already marked every waiting contact `aborted`.
`404`	`not_found`	No such campaign in your workspace, or no such contact in it.

Percent-encode contact_id in the path when your ids contain /, spaces or other reserved characters.

Start a campaign

POST /v2/campaigns/{id}/start

Allowed from draft and from paused. Starting a paused campaign is how you resume one whose dialler is no longer running (after a top-up, for example), because start re-runs the fleet and wallet preflight that a bare resume skips. Starting a campaign that the connected-call limit paused starts its count again from zero, as a resume does.

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/start \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

202 Accepted

{ "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB", "status": "play" }

202 means the dialler is running. It does not mean a phone is ringing yet: outside the calling window, the campaign waits in play, which is expected. If the window can never open again, you get 409 window_closed instead.

`funded_calls`: an underfunded campaign still starts

If your wallet cannot cover every remaining contact, the campaign still starts and the response carries a warning:

202 Accepted — partially funded

{
  "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "status": "play",
  "funded_calls": 166
}

The campaign starts, dials what the balance covers, and then pauses itself with pause_reason: "insufficient_balance". Top up and start it again to continue. funded_calls is a one-minute-per-call estimate at this campaign’s tier. Treat it as a floor on how far you get, though not a guaranteed one.

Errors

Status	`error.code`	Cause
`409`	`conflict`	The campaign is already `play`, or is `stopped`/`completed`.
`409`	`pool_unavailable`, `number_retired`	The pool it calls from has no number that can call, or its number is retired. See phone numbers and pools.
`409`	`window_closed`	The campaign’s calling window can never open again: today is past the last slot and `end_date` has no later opening. Extend `end_date` or widen `slots` with `PATCH`, then start again.
`429`	`rate_limited`	Your workspace queue is full (500 calls accepted and not yet ended). Honour `Retry-After`.
`503`	`fleet_offline`	Speech capacity is offline. `Retry-After: 300`. Nothing is charged and the campaign stays where it was.
`503`	`campaigns_unavailable`	Campaigns are not enabled for your workspace.

Here is window_closed for a campaign whose start_date and end_date are both today, started after its only slot ended at 17:00:

409 Conflict

{
  "error": {
    "code": "window_closed",
    "message": "calling window is already closed: no slot opens again on or before end_date 2026-10-10 (Asia/Kolkata, slots 09:00–17:00). Extend end_date or widen slots with PATCH /v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB, then start again."
  }
}

Nothing was dialled, and the campaign keeps its status. Move end_date out and start it again:

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "end_date": "2026-10-11" }'

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/start \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Pause a campaign

POST /v2/campaigns/{id}/pause

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/pause \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

202 Accepted

{ "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB", "status": "paused" }

Takes effect immediately, including while the campaign is asleep waiting for tomorrow’s window. Calls already live are not hung up. Pause stops new calls and lets current conversations finish. If you need a live call to end now, use POST /v2/calls/{id}/abort. Only a play campaign can be paused; anything else is 409 conflict. The body is optional. Send reason and by to say why and who, and the campaign’s pause_reason reads <by>: <reason> (at most 300 characters together):

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/pause \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "agent script under review", "by": "Priya (sales ops)" }'

Resume a campaign

POST /v2/campaigns/{id}/resume

202 Accepted

{ "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB", "status": "play" }

409 conflict if the campaign is not paused, and also if it is paused but has no running dialler. In that case the message tells you to use POST /start instead, because a bare resume would skip the wallet and fleet preflight. 409 window_closed if the calling window can never open again, exactly as on start. The campaign stays paused. Extend end_date or widen slots with PATCH, then resume. Resuming a campaign paused with connected_limit_reached starts the connected-call count again from zero, so it calls the next batch and pauses again. To call more before the next pause, raise pause_after_connected first. To stop pausing, set it to null.

Stop a campaign

POST /v2/campaigns/{id}/stop

202 Accepted

{ "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB", "status": "stopped" }

Stopping is terminal and cannot be undone. Live calls are hung up, pending contacts are marked aborted, and the campaign will never dial again. Allowed from draft, play and paused. If you might want to continue later, pause instead.

Campaign history

GET /v2/campaigns/{id}/history?limit=

The campaign’s log: every start, pause, resume, stop and completion, and every change to its connected-call limit, with when it happened, who did it and why. It is how you tell a pause someone pressed from one the campaign made on its own.

Query param	Description
`limit`	1–200, default 50. Entries come newest first.

curl -G https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/history \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "limit=20"

200 OK

{
  "object": "list",
  "data": [
    { "type": "resumed", "at": "2026-11-06T05:00:12Z", "by": "Priya (sales ops)",
      "reason": null, "count_restarted": true },
    { "type": "paused", "at": "2026-11-05T09:02:11Z", "by": null,
      "reason": "connected_limit_reached", "pause_after_connected": 50, "connected": 50 },
    { "type": "resumed", "at": "2026-11-05T07:55:40Z", "by": "Priya (sales ops)",
      "reason": null },
    { "type": "paused", "at": "2026-11-05T07:40:03Z", "by": null,
      "reason": "insufficient_balance" },
    { "type": "pause_rule_changed", "at": "2026-11-05T04:30:00Z", "by": "Priya (sales ops)",
      "reason": null, "pause_after_connected": 50, "previous_pause_after_connected": null },
    { "type": "started", "at": "2026-11-05T04:29:31Z", "by": "Priya (sales ops)",
      "reason": null }
  ]
}

Field	Type	Description
`type`	enum	`started` \| `paused` \| `resumed` \| `stopped` \| `completed` \| `pause_rule_changed`.
`at`	string	RFC 3339 time it happened.
`by`	string \| null	Who did it: the `Mirai-Actor` they sent. `null` when the campaign did it on its own, such as an automatic pause or a completion. Always present.
`reason`	string \| null	On `paused`, the campaign’s `pause_reason` at that moment. On `completed`, `list_finished` or `end_date`. Otherwise `null`. Always present.
`pause_after_connected`	integer \| null	On `pause_rule_changed`, the new limit (`null` means it was removed). On a pause with `connected_limit_reached`, the limit it reached. Absent otherwise.
`previous_pause_after_connected`	integer \| null	On `pause_rule_changed` only: the limit before the change (`null` means there was none).
`connected`	integer	On a pause with `connected_limit_reached` only: the connected calls it counted.
`count_restarted`	boolean	`true` on `started` or `resumed` when the connected-call count started again. Absent otherwise.

The history starts on the day this endpoint shipped. Older campaigns have no entries from before it. 404 not_found for an unknown id and for one in another workspace.

Who did it: `Mirai-Actor`

Add a Mirai-Actor header to any campaign write (create, PATCH, start, pause, resume, stop) to name the person or system behind it. It is up to 120 characters and appears as by in the history.

curl -X POST https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/resume \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Mirai-Actor: crm-sync (nightly)"

Without the header, by is the by you sent in a pause body, then your API key’s label, then API. Changes made in the console carry your workspace’s name.

Campaign report

GET /v2/campaigns/{id}/report
GET /v2/campaigns/{id}/report?format=csv

JSON — the aggregate

curl https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/report \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "campaign_id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
  "status": "completed",
  "counters": {
    "completed": 174,
    "voicemail": 12,
    "no_answer": 9,
    "exhausted": 21,
    "suppressed": 3
  },
  "contacts": 219,
  "dialed": 216,
  "attempts": 251,
  "connected": 186,
  "spent_paise": 60300,
  "spent_inr": 603,
  "budget_paise": 120000
}

Field	Meaning
`counters`	Contacts by final status.
`contacts`	Rows uploaded.
`dialed`	Contacts with at least one attempt.
`attempts`	Total dial attempts, retries included. `attempts − dialed` is what retrying cost you.
`connected`	`completed` + `voicemail` + `timeout`: the calls that produced live media, which are the ones you paid for.
`spent_paise` / `spent_inr`	The same number in both units, for convenience.

connected / dialed is your answer rate. attempts / dialed tells you whether retry_count is paying off.

CSV — per contact

curl -G https://sandbox.voice.miraiminds.co/v2/campaigns/cmp_01K7QAC5N9P4R7S3T6V8W2X4YB/report \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "format=csv" \
  -o campaign.csv

id,phone,status,attempts,last_call_id
cust-1001,+919876543210,completed,1,call_01K7QB4M8N3P6R2S5T7V9W1YA
cust-1002,+919876543211,exhausted,2,call_01K7QB4M8N3P6R2S5T7V9W1YB
cust-1003,+919812345678,suppressed,0,

The CSV is streamed rather than buffered, so it is safe on a six-figure campaign. Join last_call_id against GET /v2/calls for durations and costs.

Webhooks

If you set webhook_url on the campaign, you receive both its lifecycle events and every child call’s call.* events. Both are signed with the same workspace secret and verified by the same code path.

Type	Fires when
`campaign.started`	The first `POST /start` takes effect. Once per campaign, never on an internal restart.
`campaign.paused`	You paused it, or the campaign paused itself: the money gate, the connected-call limit or its number. Read `data.campaign.pause_reason`.
`campaign.resumed`	Dialling resumed.
`campaign.completed`	Every contact reached a final state, or the date range ran out. An always-on campaign sends it only when the date range runs out.
`campaign.stopped`	You stopped it.

POST https://example.com/mirai/webhook

{
  "id": "evt_01K7QC5N9P4R7S3T6V8W2X4YB",
  "type": "campaign.paused",
  "created_at": "2026-08-11T13:04:02Z",
  "data": {
    "campaign": {
      "id": "cmp_01K7QAC5N9P4R7S3T6V8W2X4YB",
      "object": "campaign",
      "name": "Order confirmations — Mumbai batch",
      "status": "paused",
      "pause_reason": "insufficient_balance",
      "counters": { "pending": 612, "completed": 174, "no_answer": 9 },
      "dialed": 216,
      "always_on": false
    }
  }
}

Campaign events use the same envelope as call events ({id, type, created_at, data}), with data.campaign where data.call would be. data.campaign.always_on is on every campaign event. Every call.* event of a campaign call names the campaign and the contact in data.call.campaign_id and data.call.contact_id, and carries the contact’s metadata in data.call.metadata. With final_results on (the default), each call also ends with one call.processed that has the transcript and the after-call results, so you don’t need to fetch anything. An agent with emit_processed_webhook: false sends no call.processed, whatever the campaign says. Verification, retries and replay protection are identical; see Webhooks.

Alert on campaign.paused with a pause_reason. That event means a campaign has stopped spending money for a reason you can fix in one API call.

Follow a campaign call live

Each campaign call has a live event stream, like any other call: the agent’s state and each turn while the call runs. A campaign call has no create response, so it has no events_url. Open its stream from your backend with your API key. Take the call id from data.call.id on its call.started webhook, or from GET /v2/calls.

curl -N https://sandbox.voice.miraiminds.co/v2/calls/call_01K7QB4M8N3P6R2S5T7V9W1YA/events \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

A campaign that behaves

Scrub first. Push known opt-outs to POST /v2/dnc before you upload the list. Suppression is checked at dial time, so late additions still work, but a number dialled at 10:00 cannot be un-dialled at 10:05.
Keep the window legal. 09:00 to 21:00 IST is the outer bound for commercial calls in India, and most enterprise programmes run 10:00 to 19:00. See calling rules.
Budget every campaign. budget_paise is the cheapest insurance there is against a bad CSV.
Retry once, wait fifteen minutes. retry_count: 1 with re_attempt_period_secs: 900 works for most Indian mobile lists. Retrying five times in five minutes annoys people and does not connect.
Start small. Begin with ten contacts, one slot and max_concurrent: 1, and read the transcripts. Then upload the rest into the same campaign.
Watch exhausted and suppressed in the report. They are the two numbers that tell you about your list rather than your agent.

​The campaign object

​Lifecycle

​Pause reasons

​Contact statuses

​Calling window

​Retries

​Budget and pacing

​Pause after connected calls

​Example: pause a running campaign every 50 conversations

​Always-on campaigns

​Example: one open campaign, numbers added as they come

​Create a campaign

​Request

​Contacts are reported row by row, not rejected as a batch

​Your own fields: metadata

​Voice and language per contact

​Errors

​List campaigns

​Get a campaign

​Update a campaign

​Switch to the agent’s latest version

​Words to catch

​Add contacts

​List contacts

​Call a contact again

​Remove a contact

​Cancel a contact

​Start a campaign

​funded_calls: an underfunded campaign still starts

​Errors

​Pause a campaign

​Resume a campaign

​Stop a campaign

​Campaign history

​Who did it: Mirai-Actor

​Campaign report

​JSON — the aggregate

​CSV — per contact

​Webhooks

​Follow a campaign call live

​A campaign that behaves

The campaign object

Lifecycle

Pause reasons

Contact statuses

Calling window

Retries

Budget and pacing

Pause after connected calls

Example: pause a running campaign every 50 conversations

Always-on campaigns

Example: one open campaign, numbers added as they come

Create a campaign

Request

Contacts are reported row by row, not rejected as a batch

Your own fields: `metadata`

Voice and language per contact

Errors

List campaigns

Get a campaign

Update a campaign

Switch to the agent’s latest version

Words to catch

Add contacts

List contacts

Call a contact again

Remove a contact

Cancel a contact

Start a campaign

`funded_calls`: an underfunded campaign still starts

Errors

Pause a campaign

Resume a campaign

Stop a campaign

Campaign history

Who did it: `Mirai-Actor`

Campaign report

JSON — the aggregate

CSV — per contact

Webhooks

Follow a campaign call live

A campaign that behaves