Skip to content
Infinite AudienceInfinite Audience Docs

Update a campaign

PATCH
/v1/campaigns/{id}
curl --request PATCH \
  --url https://api.infiniteaudience.ai/v1/campaigns/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "status": "archived" }'

Rename a campaign, revise its brief, or change its status. Supported status values: archived (soft-delete) and active (restore from archived). Requires ‘purchase’ scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name

New display name.

string
<= 120 characters
description

Campaign brief; send an empty string to clear it.

string
<= 1000 characters
status

archived — soft-deletes the campaign (excluded from list by default). active — restores a previously archived campaign.

string
Allowed values: archived active

Responses

Section titled “Responses”

200

Section titled “200”

Updated campaign.

Media typeapplication/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
id
required

Unique campaign identifier.

string
name
required

Display name of the campaign.

string
description
required

User-authored campaign brief, intended market, goals, and constraints.

string
<= 1000 characters
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
id
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
id
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>

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
id
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

Section titled “400”

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

Media typeapplication/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
Examplevalidation_error
{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Section titled “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).

Media typeapplication/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"
}

403

Section titled “403”

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

Media typeapplication/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
Examplemissing_scope
{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Section titled “404”

Resource not found or not accessible to the calling org.

Media typeapplication/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
Examplenot_found
{
  "error": "Audience not found"
}