Create a campaign

POST

/v1/campaigns

const url = 'https://dev-api.infiniteaudience.ai/v1/campaigns';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Q3 2026 Prospecting"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Q3 2026 Prospecting" }'

Creates a new campaign workspace. A Campaign is a named container that groups related audiences and deliveries under a single context — useful for organising a body of work such as a quarterly prospecting initiative or a product-launch outreach.

Campaign association is optional. Audiences, file-match jobs, and deliveries all work independently without a campaign. Use campaigns when you want to track related work together — e.g. filtering GET /v1/operations to campaign_id for a specific initiative’s activity.

After creation, associate audiences with the campaign by:

Passing campaign_id to POST /v1/audiences or POST /v1/match/file at creation time (auto-links on creation).
Calling POST /v1/campaigns/{id}/audiences/{audience_id} to link an existing audience.

Requires ‘purchase’ scope.

Authorizations

bearerAuth

Request Body^required

application/json

object

name

required

Display name for the campaign.

string

>= 1 characters <= 120 characters

Examples

basic

Create a campaign

{
  "name": "Q3 2026 Prospecting"
}

Responses

201

Campaign created.

application/json

A named workspace grouping related audiences and deliveries. There is no audience_ids[] field — audiences[] (below) is the only audience-linkage field the handler ever returns.

object

required

Unique campaign identifier.

string

name

required

Display name of the campaign.

string

status

required

Lifecycle state of the campaign.

string

Allowed values: active archived

session_ids

required

Associated chat session IDs.

Array<string>

audiences

required

Audiences linked to this campaign — expanded on GET /v1/campaigns/{id}; empty array on list responses.

Array<object>

object

string

name

string

status

string

Allowed values: active archived expired

record_count

integer | null

segment_ids

IDs of include-role segments in this audience.

Array<string>

excluded_segment_ids

IDs of exclude-role segments in this audience.

Array<string>

segments

Expanded summaries of the include-role segments, in segment_ids order (best-effort — missing or deleted segment docs are skipped). The first entry is the primary segment; its subtype determines the audience’s subtype-specific behavior.

Array<object>

Lightweight summary of a constituent segment, expanded server-side from the audience’s composition. Returned on both list and single-GET audience responses. subtype is the segment’s own subtype — use the first entry of segments (the primary included segment) to derive subtype-specific presentation for the audience.

object

required

Segment document ID.

string

name

required

Segment display name.

string

record_count

required

Cached record count of the segment. Null if never counted.

integer | null

subtype

required

Subtype of the constituent segment.

string

Allowed values: filter matched similarity propensity

input_record_count

required

Matched subtype only. Count of records in the uploaded identity file. Null otherwise.

integer | null

match_count

required

Matched subtype only. Count of records successfully matched. Null otherwise.

integer | null

excluded_segments

Expanded summaries of the exclude-role segments, same semantics as segments.

Array<object>

object

required

Segment document ID.

string

name

required

Segment display name.

string

record_count

required

Cached record count of the segment. Null if never counted.

integer | null

subtype

required

Subtype of the constituent segment.

string

Allowed values: filter matched similarity propensity

input_record_count

required

Matched subtype only. Count of records in the uploaded identity file. Null otherwise.

integer | null

match_count

required

Matched subtype only. Count of records successfully matched. Null otherwise.

integer | null

set_logic

string

Allowed values: union intersection

snapshot_version

integer

parent_audience_id

string | null

linked_at

When this audience was linked to the campaign.

string | null format: date-time

linked_by

UID of the user who linked this audience to the campaign.

string | null

created_by

required

UID of the user who created the campaign.

string | null

updated_by

required

UID of the user who last updated the campaign.

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "status": "active",
  "audiences": [
    {
      "status": "active",
      "segments": [
        {
          "subtype": "filter"
        }
      ],
      "excluded_segments": [
        {
          "subtype": "filter"
        }
      ],
      "set_logic": "union"
    }
  ]
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

validation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

Create a campaign

Authorizations

Request Bodyrequired

Examples

Responses

201

Example

400

Examples

401

Examples

403

Examples

Request Body^required