POST

Authorizations

​
Authorization
string
header
required

Authorization: Bearer vg_live_<32 hex characters>. Keys are issued by Mergen admins and shown once. Missing or invalid key: 401 unauthorized. Suspended account: 403 tenant_suspended.

Headers

​
Idempotency-Key
string

Optional, 1 to 64 characters, one per campaign you mean to create. Same key and body again: 200 with the campaign the first request created. Same key, different body: 409 idempotency_conflict.

Required string length: 1 - 64

Body

application/json

type: "ai_voice" (the default) needs agent_id. type: "prerecorded" needs message instead (no agent): every record hears the message with its own values in place of the {variable} placeholders, spoken in the voice assigned to the language and gender. Records with the same values share one recording (made at the first call, then reused). A pre-recorded call's outcome is played, partial (hung up during the message), voicemail or invalid; the default goal is played, invalid counts as a wrong number and voicemail is retried like no answer.

​
name
string
required
Required string length: 1 - 200
​
input_type
enum<string>
required

csv: records come from a file uploaded before the first call. api: records are posted as JSON at any time until the campaign ends.

Available options:
csv,
api
​
description
string | null
Maximum string length: 2000
​
type
enum<string>
default:ai_voice

Who speaks to each record. Cannot change after create.

Available options:
ai_voice,
prerecorded
​
agent_id
string

The agent that makes the calls (see GET /v1/campaign-agents). Required for ai_voice, not allowed for prerecorded.

Pattern: ^[A-Za-z0-9_-]{1,128}$
​
message
object

A pre-recorded campaign's message. template is the text, with a record's values written as {name} (for example {due_date}); every placeholder is a required variable of each record. Write it in the script of language (a few Latin words such as "EMI" are fine) and write values the way they should be spoken ("5th November", not "05/11"). The text with its values must stay within the platform's limit (500 characters by default); a record whose text is too long, or a language or gender without a voice, pauses the campaign.

​
goal
object

The agent outcomes that count as success. Each must be one of the agent's outcomes.

​
variables
object
​
csv
object

How a CSV file is read.

​
schedule
object

When calls are allowed. start_date and end_date are calendar dates in timezone (end_date included; null means no end). With time_window_enabled, calls are placed only between daily_start_time and daily_end_time on active_days; without it, all day on active days. The agent's own calling window and your account's limits still apply.

​
execution
object

Limits of the campaign. max_concurrency: calls it keeps open at once (1 to 200, and never more than your account allows). max_attempts: the length of the attempt ladder (1 to 10). dnc_enabled: skip numbers on your do-not-call list, and add a number to it when a call ends with a do-not-call outcome. reschedule_enabled: honour callback requests. dial_first_attempt_immediately: place attempt 1 as soon as the campaign may call, ignoring its day and time. skip_duplicates and skip_invalid_phones: skip such records instead of refusing the upload. budget_micros: your cost at which the campaign pauses (needs your account's pricing). The gateway never retries a campaign call by itself; every new try is an attempt of the ladder.

​
attempts
object[]
Required array length: 1 - 10 elements
​
retry
object

Which unsuccessful attempts are tried again (with the next attempt of the ladder, while attempts are left). no_answer (also voicemail) with retry_on_no_answer, busy with retry_on_busy, an answered call shorter than short_call_threshold_seconds with retry_on_short_call, any of insight_based_retry_conditions that holds, and always an attempt that failed on our side. retry_delay_minutes is the least time between the end of one attempt and the next (except an instant redial).

​
outcome_rules
object

What some outcomes mean. After an answered call: an outcome in do_not_call (with execution.dnc_enabled) closes the record and adds the number to your do-not-call list; an outcome in callback (with execution.reschedule_enabled) schedules the next attempt at the time in the post-call variable callback_variable (a callback may use one attempt beyond the ladder, at most 2 per record); an outcome in goal.outcomes completes the record as a success; an outcome in wrong_number completes it as a wrong number. Defaults come from the agent's outcome_roles.

​
metadata
object

Your own data (at most 4 KB of JSON), returned as it is.

​
records
object[]

Records of an api campaign, taken in like POST .../records.

Maximum array length: 5000

Response

Replay of an earlier request with the same Idempotency-Key and body. Returns the campaign's current state.

A campaign. agent_contract is what the campaign read from its agent. counts and results count its records by status and by result. success_rate is the share of callable records that ended as a success, in percent (null until a call was answered). window says whether the schedule allows a call now. test_report is the latest dry run (null before the first). locked is true once the first call was placed (see PATCH). actions lists what the status allows now. canceling is true while a canceled campaign waits for its last calls to finish. intake is present only in the create answer, when the request carried records.

​
id
string
required

cmp_ + 32 hex characters.

​
tenant_id
string
required

Your account id.

​
name
string
required
​
description
string | null
required
​
status
enum<string>
required

draft (being set up; everything can change), created (launched; the configuration passed its blocking checks), testing (the dry run is working), tested (the dry run finished; see test_report), running, paused, completed (no record is left to call, or the end date passed) and canceled. A campaign moves from draft to created with launch, may be tested any number of times, then goes to running with start.

Available options:
draft,
created,
testing,
tested,
running,
paused,
completed,
canceled
​
input_type
enum<string>
required

csv: records come from a file uploaded before the first call. api: records are posted as JSON at any time until the campaign ends.

Available options:
csv,
api
​
agent
object
required
​
agent_contract
object
required

What the campaign read from its agent (on create, and again on launch, test and start).

​
goal
object
required
​
variables
object
required
​
csv
object
required
​
schedule
object
required

When calls are allowed. start_date and end_date are calendar dates in timezone (end_date included; null means no end). With time_window_enabled, calls are placed only between daily_start_time and daily_end_time on active_days; without it, all day on active days. The agent's own calling window and your account's limits still apply.

​
execution
object
required

The campaign's execution limits, plus why it is paused.

​
attempts
object[]
required
​
retry
object
required

Which unsuccessful attempts are tried again (with the next attempt of the ladder, while attempts are left). no_answer (also voicemail) with retry_on_no_answer, busy with retry_on_busy, an answered call shorter than short_call_threshold_seconds with retry_on_short_call, any of insight_based_retry_conditions that holds, and always an attempt that failed on our side. retry_delay_minutes is the least time between the end of one attempt and the next (except an instant redial).

​
outcome_rules
object
required

What some outcomes mean. After an answered call: an outcome in do_not_call (with execution.dnc_enabled) closes the record and adds the number to your do-not-call list; an outcome in callback (with execution.reschedule_enabled) schedules the next attempt at the time in the post-call variable callback_variable (a callback may use one attempt beyond the ladder, at most 2 per record); an outcome in goal.outcomes completes the record as a success; an outcome in wrong_number completes it as a wrong number. Defaults come from the agent's outcome_roles.

​
metadata
object
required
​
counts
object
required

Records by status.

​
results
object
required

Records by result (records still open have none).

​
success_rate
number | null
required
​
spend
object
required

Your cost of the campaign's calls. status is pending while any cost is still pending, final once every cost is known, and no_rule (with amount_micros: null) while your account has no pricing.

​
collected
object
required

What was paid, from your customer events (POST /v1/customer-events).

​
window
object
required

Whether the schedule allows a call right now, when the current window closes, or when the next one opens.

​
pause_reason
enum<string> | null
required

Same as execution.pause_reason.

Available options:
manual,
credits,
unroutable,
budget,
failures,
disabled
​
pause_details
object | null
required

Same as execution.pause_details.

​
test_report
object | null
required

The result of the dry run. status is failed when any check is an error, passed_with_warnings when any is a warning, else passed. timeline shows when each attempt of a sample record would be placed if no call were answered (at is null for an attempt that falls after the end date). samples shows the resolved variables of up to 5 records. estimate compares the expected attempts with the calling hours of the schedule.

​
locked
boolean
required
​
actions
enum<string>[]
required

An action the campaign's status allows right now.

Available options:
edit,
add_records,
launch,
delete,
test,
start,
pause,
resume,
cancel,
duplicate
​
duplicated_from
string | null
required

The campaign this one was copied from.

​
launched_at
string<date-time> | null
required
​
tested_at
string<date-time> | null
required
​
locked_at
string<date-time> | null
required
​
started_at
string<date-time> | null
required
​
paused_at
string<date-time> | null
required
​
completed_at
string<date-time> | null
required
​
canceled_at
string<date-time> | null
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
type
enum<string>

prerecorded campaigns have no agent (agent is { id: "prerecorded", name: "Pre-recorded message" }) and a message.

Available options:
ai_voice,
prerecorded
​
message
object | null

A pre-recorded campaign's message. template is the text, with a record's values written as {name} (for example {due_date}); every placeholder is a required variable of each record. Write it in the script of language (a few Latin words such as "EMI" are fine) and write values the way they should be spoken ("5th November", not "05/11"). The text with its values must stay within the platform's limit (500 characters by default); a record whose text is too long, or a language or gender without a voice, pauses the campaign.

​
canceling
boolean
​
intake
object

What an upload did. received records were read; added are now pending. skipped counts the records not called and why (do_not_call ones are closed). invalid and missing list up to 100 rows each (the CSV row or the position in the request).