Connect

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 pathDoes
GET /campaignsList campaigns
POST /campaignsCreate a draft
GET /campaigns/{campaign}Read one, with its results
PATCH /campaigns/{campaign}Change its settings
DELETE /campaigns/{campaign}Delete it
POST /campaigns/{campaign}/duplicateCopy it to a new draft
PUT /campaigns/{campaign}/sequenceReplace its sequence
GET /campaigns/{campaign}/audienceWho its audience matches
POST /campaigns/{campaign}/recipientsAdd recipients
GET /campaigns/{campaign}/recipientsList recipients
GET /campaigns/{campaign}/recipients/{recipient}One recipient's calls
POST /campaigns/{campaign}/recipients/{recipient}/stopStop calling them
DELETE /campaigns/{campaign}/recipients/{recipient}Take them off a draft
PUT /campaigns/{campaign}/recipients/{recipient}/callbackBook, move or cancel their callback
POST /campaigns/{campaign}/launchLaunch or schedule
POST /campaigns/{campaign}/pause, /resume, /cancelPause, 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 settingEffect here
View onlyReads only. A change is refused as insufficient_scope
EditReads and changes, within your role, except deleting
Also allow DeleteDeleting a campaign or a recipient (agent:delete). Without it a delete is refused as insufficient_scope
This workspaceOnly 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": [] } }
StatusCodes
400invalid_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)
401unauthorized, invalid_token: no token, or one that is invalid, expired or revoked
403insufficient_scope, workspace_read_only, workspace_out_of_scope, workspace_scope_required, not_available (campaigns are off for the workspace), staff_token_not_accepted
404workspace_not_found, campaign_not_found, recipient_not_found, operation_failed (no agent with that slug or id in the workspace)
409confirmation_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
422too_many (more than 5,000 recipients in one request), time_passed, too_far_ahead, outside_calling_hours
429rate_limited
500tool_threw, launch_failed: check, then try again
503disabled: 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. kind is call or sms. Steps come in any order, an SMS first included, and at least one is a call. delay is how long after the step before it ends this one starts, counted from launch for the first, up to 90 days; unit is minutes, hours or days. A call step's attempts holds 1 to 5, the first with an after of 0 and each retry 5 minutes to 24 hours after the one before, each with its own voicemail (null uses the agent's setting). brief is 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's body in the path. It goes from a mobile among the caller numbers. An SMS step's routes take sent and no_response (not delivered), and both go to the next step when left out. A STOP reply ends the sequence as do_not_call, and any other reply as replied.
  • Routes map an outcome id to next, end or the id of a later step, and only go forward. An outcome left out takes the default: no_response, and an SMS step's sent, go to the next step and every other outcome ends the sequence. do_not_call always ends.
  • Outcomes are checked in order after a connected call; the first that fits wins. do_not_call comes first and other last, and no_response is in the list; those three carry builtIn: true and no when. Every other outcome has a when of match (any or all) and rules: a result rule lists call results (completed, transferred, abandoned, failed) and an ai rule holds a statement the call's analysis answers. An outcome takes 1 to 5 rules, at most one of them ai.
  • 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"] }
    ]
  }
}
Ruleop
"kind": "tags" with tagsany, none
A text field, with a text valueequals (ignoring case), contains; or is_set, is_empty with no value
A number field, with a number valueeq, gt, gte, lt, lte
A yes or no field, with true or falseis, is_not
A choice field, with values from its optionsany_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 in attempts, and converted. Each has a channel (call or sms); a text also has sms: its body as sent, fromNumber, status (sending, accepted, delivered or failed), the failure's detail, and the person's reply and repliedAt.
  • POST .../recipients/{recipient}/stop stops 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.

On this page