Campaigns

API reference descriptions are provided in English to preserve the exact published contract.

List resumable campaign builder drafts

GET /v1/accounts/{AC}/campaign-builder-drafts

getV1AccountsByAcCampaignBuilderDraftsPaginated200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a resumable campaign builder draft

POST /v1/accounts/{AC}/campaign-builder-drafts

postV1AccountsByAcCampaignBuilderDraftsIdempotency-Key required201

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (4 fields)

Request body
Name	Type	Required
`currentStep`	integer (1–9)	yes
`data`	object	yes
`name`	string (max 256 chars)	yes
`version`	integer (1–)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch a campaign builder draft

GET /v1/accounts/{AC}/campaign-builder-drafts/{CD}

getV1AccountsByAcCampaignBuilderDraftsByCd200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CD`	path · string (CD… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Save campaign builder progress

PATCH /v1/accounts/{AC}/campaign-builder-drafts/{CD}

patchV1AccountsByAcCampaignBuilderDraftsByCdIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CD`	path · string (CD… SID)	yes

Request body (4 fields)

Request body
Name	Type	Required
`currentStep`	integer (1–9)	yes
`data`	object	yes
`name`	string (max 256 chars)	yes
`version`	integer (1–)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Delete a campaign builder draft

DELETE /v1/accounts/{AC}/campaign-builder-drafts/{CD}

deleteV1AccountsByAcCampaignBuilderDraftsByCd204

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CD`	path · string (CD… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List campaigns and authoritative planning state

GET /v1/accounts/{AC}/campaigns

getV1AccountsByAcCampaignsPaginated200

List campaigns with their state and planning progress. Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`state`	query · "DRAFT" \| "PENDING_APPROVAL" \| "SCHEDULED" \| "PLANNING" \| "RUNNING" \| "PAUSED" \| "COMPLETING" \| "COMPLETED" \| "CANCELED" \| "FAILED"
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a campaign draft

POST /v1/accounts/{AC}/campaigns

postV1AccountsByAcCampaignsIdempotency-Key required201

Create a campaign draft: who receives which template, when, and how fast. Nothing is sent until the campaign is started. Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (21 fields)

Request body
Name	Type	Required	Description
`audience`	object	yes
`budgetCap`	string (pattern ^[0-9][0-9,]*(\.[0-9]+)?$, max 24 chars)		Budget cap in the campaign currency's own units, for example "500" for JPY or "12.50" for GBP.
`budgetCapMinor`	integer (0–)
`contentSid`	string (HX… SID)	yes
`currency`	string (pattern ^[A-Z]{3}$)
`frequencyPolicy`	object \| null
`headerMediaSid`	string (ME… SID)		Media sent as the header of an IMAGE, VIDEO or DOCUMENT template. Meta needs the header asset on every send; without this the asset the template was submitted with is used, and a campaign with neither cannot be submitted.
`name`	string (max 256 chars)	yes
`pacing`	object	yes
`pacing.perAccountPerMinute`	integer (1–1000000)
`pacing.perSenderPerMinute`	integer (1–1000000)	yes
`requiresApproval`	boolean
`schedule`	object	yes
`schedule.endAt`	string (date-time)	yes
`schedule.quietHours`	object
`schedule.startAt`	string (date-time)	yes
`schedule.timezoneMode`	"sender" \| "recipient"
`senderPoolSid`	string (SP… SID)
`senderSids`	string (WA… SID)[]
`transport`	"cloud_api" \| "marketing_messages"
`variablesMapping`	object		Template placeholder → source. A source is a contact field path (displayName, locale, timezone, attributes.<key>) or `literal:<text>` for a fixed value; a placeholder with no entry reads attributes.<placeholder>. A contact whose sources resolve to no scalar is excluded with ADDRESSING_UNSUPPORTED and the failing placeholder in detail.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Fetch a campaign

GET /v1/accounts/{AC}/campaigns/{CP}

getV1AccountsByAcCampaignsByCp200

Fetch one campaign with its schedule, audience, counts and cost so far. Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Delete a campaign draft

DELETE /v1/accounts/{AC}/campaigns/{CP}

deleteV1AccountsByAcCampaignsByCp204

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Approve a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/approve

postV1AccountsByAcCampaignsByCpApproveIdempotency-Key required200

Required scope: `approvals:decide`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Record an idempotent campaign click or conversion

POST /v1/accounts/{AC}/campaigns/{CP}/attribution-events

postV1AccountsByAcCampaignsByCpAttributionEventsIdempotency-Key required201

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (8 fields)

Request body
Name	Type	Required
`contactSid`	string (CT… SID)
`currency`	string (pattern ^[A-Z]{3}$)
`eventType`	"click" \| "conversion"	yes
`externalEventId`	string (max 200 chars)	yes
`messageSid`	string (SM… SID)
`occurredAt`	string (date-time)	yes
`properties`	object
`valueMinor`	integer (0–)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List campaign planning batches

GET /v1/accounts/{AC}/campaigns/{CP}/batches

getV1AccountsByAcCampaignsByCpBatchesPaginated200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Cancel a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/cancel

postV1AccountsByAcCampaignsByCpCancelIdempotency-Key required200

Cancel a campaign. Recipients not yet sent to are skipped; this cannot be undone. Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Set the frequency policy, money budget cap, account pacing and transport

PATCH /v1/accounts/{AC}/campaigns/{CP}/controls

patchV1AccountsByAcCampaignsByCpControlsIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (6 fields)

Request body
Name	Type	Required	Description
`budgetCap`	string (pattern ^[0-9][0-9,]*(\.[0-9]+)?$, max 24 chars) \| null
`budgetCapMinor`	integer (0–) \| null
`frequencyPolicy`	object \| null
`headerMediaSid`	string (ME… SID) \| null
`perAccountPerMinute`	integer (1–1000000) \| null
`transport`	"cloud_api" \| "marketing_messages"

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Dry-run campaign admission

POST /v1/accounts/{AC}/campaigns/{CP}/dry-run

postV1AccountsByAcCampaignsByCpDryRunIdempotency-Key required202

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List campaign exclusions

GET /v1/accounts/{AC}/campaigns/{CP}/exclusions

getV1AccountsByAcCampaignsByCpExclusionsPaginated200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Read campaign experiment, holdout and attribution configuration

GET /v1/accounts/{AC}/campaigns/{CP}/experiment

getV1AccountsByAcCampaignsByCpExperiment200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Configure deterministic campaign variants and holdout

PUT /v1/accounts/{AC}/campaigns/{CP}/experiment

putV1AccountsByAcCampaignsByCpExperimentIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (5 fields)

Request body
Name	Type	Required
`attributionWindowDays`	integer (1–90)	yes
`enabled`	boolean	yes
`holdoutBasisPoints`	integer (0–5000)	yes
`primaryEvent`	"click" \| "conversion"	yes
`variants`	object[]	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Report campaign outcomes and cost by variant with honest denominators

GET /v1/accounts/{AC}/campaigns/{CP}/experiment-report

getV1AccountsByAcCampaignsByCpExperimentReport200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Pause a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/pause

postV1AccountsByAcCampaignsByCpPauseIdempotency-Key required200

Pause a running campaign. Messages already handed to WhatsApp still deliver. Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Reject a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/reject

postV1AccountsByAcCampaignsByCpRejectIdempotency-Key required200

Required scope: `approvals:decide`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Resume a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/resume

postV1AccountsByAcCampaignsByCpResumeIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a draft campaign for retryable failed recipients

POST /v1/accounts/{AC}/campaigns/{CP}/retry-eligible

postV1AccountsByAcCampaignsByCpRetryEligibleIdempotency-Key required201

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`name`	string (max 256 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Evaluate the current campaign authorization decision without mutating it

GET /v1/accounts/{AC}/campaigns/{CP}/review

getV1AccountsByAcCampaignsByCpReview200

Required scope: `campaigns:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Acknowledge an allowed campaign review snapshot

POST /v1/accounts/{AC}/campaigns/{CP}/review/acknowledge

postV1AccountsByAcCampaignsByCpReviewAcknowledgeIdempotency-Key required201

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (2 fields)

Request body
Name	Type	Required	Description
`acknowledgeCost`	boolean	yes
`acknowledgeLive`	boolean	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Edit a draft or scheduled campaign window

PATCH /v1/accounts/{AC}/campaigns/{CP}/schedule

patchV1AccountsByAcCampaignsByCpScheduleIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (5 fields)

Request body
Name	Type	Required
`endAt`	string (date-time)	yes
`perSenderPerMinute`	integer (1–1000000)
`quietHours`	object \| null
`startAt`	string (date-time)	yes
`timezoneMode`	"sender" \| "recipient"	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Start a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/start

postV1AccountsByAcCampaignsByCpStartIdempotency-Key required200

Start a campaign. It must have passed review; a campaign that needs approval waits for it. Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Submit a campaign

POST /v1/accounts/{AC}/campaigns/{CP}/submit

postV1AccountsByAcCampaignsByCpSubmitIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`reason`	string (max 512 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Send a billed campaign sample to at most 10 contacts

POST /v1/accounts/{AC}/campaigns/{CP}/test-send

postV1AccountsByAcCampaignsByCpTestSendIdempotency-Key required202

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`contactSids`	string (CT… SID)[]	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Withdraw a pending campaign approval request

POST /v1/accounts/{AC}/campaigns/{CP}/withdraw

postV1AccountsByAcCampaignsByCpWithdrawIdempotency-Key required200

Required scope: `campaigns:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes
`CP`	path · string (CP… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.