Campaigns#

Group activities into campaigns for aggregate reporting.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/campaigns#

Retrieve a paginated list of campaigns for an organization.

bash

GET /v1/campaigns?page_index=0&page_size=25&organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.
status	`'active' \| 'scheduled' \| 'completed' \| 'draft'`	—	Filter by campaign status.
creatorId	`string (UUID)`	—	Filter by creator identifier.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/campaigns/stats#

Aggregate statistics for campaigns matching the given filters.

bash

GET /v1/campaigns/stats?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
status	`'active' \| 'scheduled' \| 'completed' \| 'draft'`	—	Filter by campaign status.
creatorId	`string (UUID)`	—	Filter by creator identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/:id#

Retrieve a single campaign by ID with full details.

bash

GET /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier.

Response#

Returns { data, _meta } with the result.

POST /v1/campaigns#

Create a campaign planning record with a name, summary, objective, audience, key message, desired outcomes, planned channels, owner, tags, dates, and budget. Status is derived from its dates and the response includes a mutation receipt.

bash

POST /v1/campaigns
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.
organizationId	`string (UUID)`	Required	Organization identifier.
name	`string`	Required	Campaign name.
startAt	`string (ISO 8601) \| null`	—	Campaign start date.
endAt	`string (ISO 8601) \| null`	—	Campaign end date.
budget	`number \| null`	—	Total campaign budget (non-negative, max 1B).

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

PATCH /v1/campaigns/:id#

Update a campaign's planning brief, desired outcomes, owner, tags, budget, or dates. Status is derived from its dates and the response identifies the changed fields.

bash

PATCH /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.
id	`string (UUID)`	Required	Campaign identifier to update.
name	`string`	—	Updated campaign name (1-255 characters).
startAt	`string (ISO 8601) \| null`	—	Updated start date.
endAt	`string (ISO 8601) \| null`	—	Updated end date.
budget	`number \| null`	—	Updated budget (non-negative, max 1B).

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

DELETE /v1/campaigns/:id#

Remove a campaign from normal use and unlink its associated activities. The response includes a customer-facing deletion receipt.

bash

DELETE /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier to delete.

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

Destructive action

Deleting a campaign permanently removes the campaign and unlinks all associated activities. This action cannot be undone.

POST /v1/campaigns/preview#

Retrieve a no-write preview of the exact customer-facing target, desired outcomes, budget, changed fields, derived status, and warning for a campaign create, update, delete, or duplicate action.

bash

POST /v1/campaigns/preview
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "operation": "..."
}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.
operation	`'create' \| 'update' \| 'delete' \| 'duplicate'`	Required	Campaign action to preview without changing data.
id	`string (UUID)`	—	Existing campaign identifier for update, delete, or duplicate.
name	`string`	—	Campaign name for create, update, or duplicate.
startAt	`string (ISO 8601) \| null`	—	Proposed campaign start date.
endAt	`string (ISO 8601) \| null`	—	Proposed campaign end date.
budget	`number \| null`	—
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.

Response#

Returns { data, _meta } with the result.

POST /v1/campaigns/:id/duplicate#

Create a new draft by duplicating a campaign planning brief, optionally replacing its name and dates. Activities are not copied because an activity belongs to one campaign at a time.

bash

POST /v1/campaigns/:id/duplicate
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier to duplicate.
name	`string`	—	Name for the duplicated campaign.
startAt	`string (ISO 8601) \| null`	—	Optional replacement start date.
endAt	`string (ISO 8601) \| null`	—	Optional replacement end date.

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

POST /v1/campaigns/:id/activities#

Link an activity to a campaign.

bash

POST /v1/campaigns/:id/activities
Authorization: Bearer {token}
Content-Type: application/json

{
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03",
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
campaignId	`string (UUID)`	Required	Campaign identifier to link the activity to.
activityId	`string (UUID)`	Required	Activity identifier to link.

Response#

Returns { data, _meta } with the result.

DELETE /v1/campaigns/:id/activities/:activityId#

Unlink an activity from a campaign.

bash

DELETE /v1/campaigns/:id/activities/:activityId
Authorization: Bearer {token}
Content-Type: application/json

{
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03"
}

Parameters#

Name	Type	Required	Description
campaignId	`string (UUID)`	Required	Campaign identifier.
activityId	`string (UUID)`	Required	Activity identifier to unlink.

Response#

Returns { data, _meta } with the result.