Campaigns API
Create, fill, launch and run outbound campaigns from your own servers over the REST API, authenticated with a personal access token.
The campaign routes of the REST API run outbound campaigns from your own servers. They do what the campaign pages do, under the same rules.
curl https://app.verticalai.com.au/api/v1/workspaces/acme/campaigns \
-H "Authorization: Bearer vai_pat_…"| Method and path | Does |
|---|---|
GET /campaigns | List campaigns |
POST /campaigns | Create a draft |
GET /campaigns/{campaign} | Read one, with its results |
PATCH /campaigns/{campaign} | Change its settings |
DELETE /campaigns/{campaign} | Delete it |
POST /campaigns/{campaign}/duplicate | Copy it to a new draft |
PUT /campaigns/{campaign}/sequence | Replace its sequence |
GET /campaigns/{campaign}/audience | Who its audience matches |
POST /campaigns/{campaign}/recipients | Add recipients |
GET /campaigns/{campaign}/recipients | List recipients |
GET /campaigns/{campaign}/recipients/{recipient} | One recipient's calls |
POST /campaigns/{campaign}/recipients/{recipient}/stop | Stop calling them |
DELETE /campaigns/{campaign}/recipients/{recipient} | Take them off a draft |
PUT /campaigns/{campaign}/recipients/{recipient}/callback | Book, move or cancel their callback |
POST /campaigns/{campaign}/launch | Launch or schedule |
POST /campaigns/{campaign}/pause, /resume, /cancel | Pause, resume or cancel |
Paths are relative to https://app.verticalai.com.au/api/v1/workspaces/{workspace},
where {workspace} is the workspace's slug and {campaign} a campaign's id
from the list. Bodies and answers are JSON.
Authenticate
Create a personal access token under Settings, API tokens, and send it as a bearer token. It acts as you, so it reaches what you can reach.
| Token setting | Effect here |
|---|---|
| View only | Reads only. A change is refused as insufficient_scope |
| Edit | Reads and changes, within your role, except deleting |
| Also allow Delete | Deleting a campaign or a recipient (agent:delete). Without it a delete is refused as insufficient_scope |
| This workspace | Only that workspace's paths; any other answers workspace_out_of_scope |
Owners, admins, editors and members can change campaigns; a viewer, a client or a member limited to some agents can only read them, as in the app.
Errors
Every refusal is a problem details object
with a stable code and a sentence to show a person.
{
"type": "https://docs.verticalai.com.au/docs/platform/rest-api-errors#campaign_not_found",
"title": "Not found",
"status": 404,
"detail": "No campaign '9d4b2e70-…' in workspace 'acme'.",
"code": "campaign_not_found"
}A launch that is not ready answers not_ready with the full checklist in readiness, the same one the launch dialog shows. Each blocker has an id: consent_required, agent_unpublished, from_number_required, from_number_not_owned, no_recipients, missing_variables, auto_enroll_needs_spend_cap or sms_sender_required (the sequence has an SMS step and no caller number is an Australian mobile).
{ "status": 400, "code": "not_ready", "detail": "Calling consent not confirmed.", "readiness": { "ready": false, "blockers": [{ "id": "consent_required", "title": "Calling consent not confirmed", "detail": "Confirm this workspace holds the consents required to call these recipients and has checked the list against the Do Not Call Register." }], "warnings": [] } }| Status | Codes |
|---|---|
| 400 | invalid_input, not_ready, invalid_schedule, nothing_to_change, auto_enroll_needs_audience, invalid_sequence, sequence_conflict (a sequence with the shorthand fields, or with template), invalid_template, unknown_outcome, invalid_audience, invalid_number, invalid_number_pool, from_number_not_owned, invalid_time, operation_failed (a setting the server refused, with the reason in detail) |
| 401 | unauthorized, invalid_token: no token, or one that is invalid, expired or revoked |
| 403 | insufficient_scope, workspace_read_only, workspace_out_of_scope, workspace_scope_required, not_available (campaigns are off for the workspace), staff_token_not_accepted |
| 404 | workspace_not_found, campaign_not_found, recipient_not_found, operation_failed (no agent with that slug or id in the workspace) |
| 409 | confirmation_required (a launch or delete without confirm), invalid_transition, not_draft, draft_only, not_editable, not_deletable, not_live, already_stopped, already_settled, spend_cap_reached, auto_enroll_needs_spend_cap, sequence_locked, number_pool_empty, recipient_stopped, no_callback |
| 422 | too_many (more than 5,000 recipients in one request), time_passed, too_far_ahead, outside_calling_hours |
| 429 | rate_limited |
| 500 | tool_threw, launch_failed: check, then try again |
| 503 | disabled: outbound dialling is switched off in this environment |
A workspace you are not in answers 404, the same as one that does not exist.
List and read
GET /campaigns answers { "data": [...], "has_more": false, "next_cursor": null },
newest first, each with its agent's name and recipient counts by status.
GET /campaigns/{campaign} answers the campaign with its counts, results and spend:
{
"campaign": { "id": "9d4b2e70-…", "name": "November outreach", "status": "running", "agentId": "0c9e1d2f-…" },
"counts": { "total": 120, "pending": 64, "calling": 3, "analysing": 0, "completed": 31, "noAnswer": 18, "failed": 2, "cancelled": 2 },
"analytics": { "…": "the figures on the campaign page" },
"spend": { "spentCents": 3842, "inflightCents": 372, "totalCents": 4214, "callCents": 124, "callCentsObserved": true, "chargedCalls": 31, "inflightCalls": 3, "perConnectedCents": 124, "perConversionCents": 427 }
}spend is in AUD cents. spentCents is what the campaign's calls have been
charged; inflightCents estimates the calls still in progress at callCents
each; totalCents, the two together, is what the spend cap is measured
against. See Costs and spend caps.
A draft or scheduled campaign also carries readiness, the launch checklist
below. It always lists consent_required, because consent is given only at
launch.
Create and change
POST /campaigns creates a draft and answers 201 with
{ "campaign": {...} }. name and agent (the agent's slug or id) are
required; every other field is a
dialling rule with its default.
{
"name": "November outreach",
"agent": "front-desk",
"brief": "Follow up last month's quote requests.",
"callingWindow": {
"timezone": "Australia/Perth",
"hours": [{ "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00" }]
},
"template": "multi_stage",
"spendCapCents": 5000
}The fields are name, agent, brief, speakFirst, greetingOverride,
fromNumber, numberPool, callerIdStrategy, routeReturnCalls,
callingWindow, smsWindow, maxConcurrency, ringTimeoutSecs,
spendCapCents, maxCallsPerHour, template, sequence, audience,
autoEnroll, and the sequence shorthand voicemail, doubleDial,
maxAttempts, retryDelayMinutes and convertedOutcomes.
The sequence
Every campaign carries sequence: its call and SMS steps and the outcomes a
call step can end in, as described in
Sequence and outcomes.
template picks a starting point when you create one: single_call (the
default: one step of two attempts 30 minutes apart), call_sms_follow_up (a
call on day 0, a text straight after when nobody answers, and a call on day 3)
or multi_stage (calls on day 0, day 3 and day 10, moving on when nobody
answers). Or send a whole sequence, but not both.
smsWindow sets the hours SMS steps send in, in the callingWindow shape;
null (the default) is Monday to Friday 9:00 to 20:00 and Saturday 9:00 to
17:00 in each person's local time, never on a Sunday or a public holiday. It
changes only on a draft.
voicemail, doubleDial, maxAttempts and retryDelayMinutes are shorthand
for the sequence's first call step: they set every attempt's voicemail, its
double dial, its number of attempts and the gap between them. convertedOutcomes
sets which of the sequence's outcomes count as converted. Send them to change
those parts of the sequence, or send the whole sequence, but not both in one
request. A campaign returns its sequence, and convertedOutcomes as the ids
of its converted outcomes; the four call fields are read from the sequence's
steps. convertedOutcomes names outcomes the sequence has; any other id is
refused as unknown_outcome.
{
"sequence": {
"steps": [
{
"id": "call-1",
"kind": "call",
"delay": { "amount": 0, "unit": "minutes" },
"attempts": [
{ "after": { "amount": 0, "unit": "minutes" }, "voicemail": { "action": "hang_up" } },
{ "after": { "amount": 30, "unit": "minutes" }, "voicemail": null }
],
"doubleDial": true,
"brief": "First contact. Offer to book their annual service.",
"routes": {}
},
{
"id": "sms-1",
"kind": "sms",
"delay": { "amount": 0, "unit": "minutes" },
"body": "Hi {{first_name|there}}, we just tried to call about your annual service. Reply here and we'll find a time.",
"routes": {}
},
{
"id": "call-2",
"kind": "call",
"delay": { "amount": 3, "unit": "days" },
"attempts": [
{ "after": { "amount": 0, "unit": "minutes" }, "voicemail": { "action": "leave_message", "message": "Hi {{first_name|there}}, it's Mia from Bluegum Plumbing. Give us a call back." } }
],
"doubleDial": false,
"brief": "A follow-up. Mention the first call.",
"routes": {}
}
],
"outcomes": [
{ "id": "do_not_call", "label": "Do not call", "builtIn": true },
{
"id": "booked",
"label": "Booked",
"converted": true,
"when": { "match": "any", "rules": [{ "kind": "ai", "prompt": "They agreed a date for their service." }] }
},
{
"id": "completed",
"label": "Completed",
"when": { "match": "any", "rules": [{ "kind": "result", "results": ["completed"] }] }
},
{ "id": "no_response", "label": "No response", "builtIn": true },
{ "id": "other", "label": "Other", "builtIn": true }
]
}
}- Steps.
kindiscallorsms. Steps come in any order, an SMS first included, and at least one is a call.delayis how long after the step before it ends this one starts, counted from launch for the first, up to 90 days;unitisminutes,hoursordays. A call step'sattemptsholds 1 to 5, the first with anafterof 0 and each retry 5 minutes to 24 hours after the one before, each with its ownvoicemail(nulluses the agent's setting).briefis added to the campaign brief for that call. - SMS steps carry
body, the text, with{{variables}}filled for each person. Every send adds a line with the business name and "Reply STOP to opt out", and the whole text must fit in two SMS segments, or the sequence is refused with the step'sbodyin the path. It goes from a mobile among the caller numbers. An SMS step'sroutestakesentandno_response(not delivered), and both go to the next step when left out. A STOP reply ends the sequence asdo_not_call, and any other reply asreplied. - Routes map an outcome id to
next,endor the id of a later step, and only go forward. An outcome left out takes the default:no_response, and an SMS step'ssent, go to the next step and every other outcome ends the sequence.do_not_callalways ends. - Outcomes are checked in order after a connected call; the first that
fits wins.
do_not_callcomes first andotherlast, andno_responseis in the list; those three carrybuiltIn: trueand nowhen. Every other outcome has awhenofmatch(anyorall) andrules: aresultrule lists call results (completed,transferred,abandoned,failed) and anairule holds a statement the call's analysis answers. An outcome takes 1 to 5 rules, at most one of themai. - Limits. 8 steps, 10 outcomes and 10 call attempts across the steps.
GET /campaigns/{campaign} includes the campaign's sequence, and
PUT /campaigns/{campaign}/sequence with { "sequence": {...} } replaces it and
answers { "campaign": {...} }. A sequence that breaks a
rule is refused with 400 and the path of each problem, such as
sequence.steps.1.routes.no_response: on PUT .../sequence the code is
invalid_input and each problem is in errors, and on POST or PATCH the
code is invalid_sequence and the problems are in detail.
On a draft the whole sequence can change. Once the campaign is scheduled,
running or paused, its steps, their attempt counts and routes, and its outcomes
and their rules are fixed; a change to them is refused with
409 sequence_locked. Wording (SMS body included), voicemails, delays, retry
gaps, double dial and converted can still change. A completed or cancelled campaign can change only
converted.
PATCH /campaigns/{campaign} takes any of them and answers { "campaign": {...} }.
After launch only some can change, as in
Changing a campaign after launch;
any other is refused as draft_only, and on a completed or cancelled campaign
as not_editable. null clears an optional field.
DELETE /campaigns/{campaign}?confirm=true deletes a draft, completed or
cancelled campaign and answers { "deleted": "<id>" }.
POST /campaigns/{campaign}/duplicate with { "recipients": "unreached" }
copies it to a new draft and answers 201 with the copy and what was copied.
recipients is none (the default), all or unreached. The copy keeps the
audience.
Audience
audience picks recipients from the workspace's
contacts by filter, instead of or as well as the
recipients you add. Every rule must hold; { "rules": [] } matches every
contact, and null removes the audience. It can change only on a draft.
{
"audience": {
"rules": [
{ "kind": "tags", "op": "any", "tags": ["renewal due"] },
{ "kind": "tags", "op": "none", "tags": ["opted out"] },
{ "kind": "field", "key": "state", "op": "equals", "value": "WA" },
{ "kind": "field", "key": "visits", "op": "gte", "value": 3 },
{ "kind": "field", "key": "vip", "op": "is", "value": true },
{ "kind": "field", "key": "plan", "op": "any_of", "values": ["Gold", "Silver"] }
]
}
}| Rule | op |
|---|---|
"kind": "tags" with tags | any, none |
A text field, with a text value | equals (ignoring case), contains; or is_set, is_empty with no value |
A number field, with a number value | eq, gt, gte, lt, lte |
A yes or no field, with true or false | is, is_not |
A choice field, with values from its options | any_of |
key is a field's key from GET /contacts/fields. A rule the field's type
doesn't take is refused as invalid_audience, naming the rule. Numbers on the
do-not-call list are always left out. When
the campaign launches, or at its scheduled start, the contacts that match
become recipients and the list is locked.
"autoEnroll": true keeps the campaign open to contacts who start to match
after launch, as in
Keep adding contacts who match:
each joins once, ever, within a few minutes of the change, and one the audience
added who stops matching is stopped before their next call with the outcome
left_audience. The campaign never completes while it is on. It needs an
audience (auto_enroll_needs_audience) and a spend cap: launch is not_ready
without one, and once launched, turning it on, or setting spendCapCents to
null while it is on, is refused as auto_enroll_needs_spend_cap. It can
change while the campaign is scheduled, running or paused, and removing the
audience from a draft turns it off.
POST /campaigns and PATCH /campaigns/{campaign} answer with audiencePreview
when the campaign has an audience:
{ "campaign": {...}, "audiencePreview": { "matched": 312, "doNotCall": 4, "willJoin": 308 } }GET /campaigns/{campaign}/audience answers the audience, a plain line for each rule
and a preview with up to 20 of the contacts that will join. Pass audience, as
URL-encoded JSON, to preview a filter without saving it; saved is then
false:
{
"saved": true,
"status": "draft",
"audience": { "rules": [...] },
"summary": ["Tag has any of renewal due", "State is WA"],
"preview": {
"matched": 312,
"doNotCall": 4,
"willJoin": 308,
"sample": [{ "id": "…", "phoneNumber": "+61412555018", "name": "Mia Thompson", "tags": ["renewal due"], "fields": { "state": "WA" } }]
}
}Setting or reading an audience needs access to the workspace's contacts, so a
token whose user is a client, or is limited to some agents, is refused with
workspace_scope_required.
Recipients
POST /campaigns/{campaign}/recipients adds up to 5,000 recipients to a draft. Each
number is checked, duplicates are dropped, and the
do-not-call list is applied before anyone is
added.
{
"recipients": [
{ "phone": "0412 345 678", "name": "Sam Lee", "variables": { "quote_id": "Q-1042" }, "contextNote": "Asked about decking", "timezone": "WA" }
]
}{ "inserted": 1, "skipped": 0, "suppressed": 0, "invalid": [] }GET /campaigns/{campaign}/recipients lists 50 a page. It takes status,
outcome, converted=true and search (part of a name or number), and
answers { "data": [...], "has_more", "next_cursor" }; pass next_cursor back
as cursor for the next 50.
{recipient} is the recipient's id or their phone number, + written as %2B.
GET .../recipients/{recipient}answers the recipient, every call and text newest first inattempts, andconverted. Each has achannel(callorsms); a text also hassms: itsbodyas sent,fromNumber,status(sending,accepted,deliveredorfailed), the failure'sdetail, and the person'sreplyandrepliedAt.POST .../recipients/{recipient}/stopstops calling them on a scheduled, running or paused campaign and answers{ "recipient": {...} }.DELETE .../recipients/{recipient}takes them off a draft and answers{ "removed": "<id>" }.
Callbacks
PUT .../recipients/{recipient}/callback books, moves or cancels a callback on
a running or paused campaign. The agent books one itself when the person asks
to be called back; this changes it.
{ "date": "2026-11-12", "time": "14:30", "note": "Wants to talk about the Thursday slot." }date and time are in the recipient's own local time, inside the
campaign's calling hours there, from 5 minutes to 30 days ahead; a time
outside them is refused with the next time the campaign may call. The callback
uses no attempt and replaces any pending retry. Send { "cancel": true } to
drop it. It answers { "recipient": {...} }.
Launch
POST /campaigns/{campaign}/launch starts a draft now, or at a later time with
schedule. consentConfirmed must be true: you confirm you hold the calling
consents the launch asks for.
fromNumber is required, and so is confirm: true, because a launch places
real calls.
{
"consentConfirmed": true,
"confirm": true,
"fromNumber": "+61861497310",
"schedule": { "at": "2026-11-10T09:00", "timezone": "Australia/Sydney" }
}It answers { "campaign": {...} } with the status running or scheduled.
Send it again to move a scheduled start, or without schedule to start now.
Pause, resume and cancel
POST /campaigns/{campaign}/pause, /resume and /cancel take no body and answer
{ "campaign": {...} }. Resume is refused as spend_cap_reached while the
spend cap leaves no room for a call: raise it with PATCH first.
Audit and webhooks
Every change is in the workspace's audit log under your email, made through the API. The changes send the same campaign webhook events as the app.