Bulk update audiences

PATCH

/v1/audiences/bulk

curl --request PATCH \
  --url https://dev-api.infiniteaudience.ai/v1/audiences/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "audience_ids": [ "example" ], "set_logic": "union", "add_segment_id": "example", "remove_segment_id": "example", "status": "archived" }'

• Development API Server

Apply set_logic, segment add/remove, or status changes to multiple audiences in a single request. Audiences are subtype-agnostic composition wrappers, so this applies uniformly regardless of which segment subtypes (filter, matched, similarity, propensity) they compose. Fail-closed ownership validation — any unauthorized ID returns 403 before any writes. Max 50 audiences per call. Returns 207 for partial success. Requires ‘purchase’ scope.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

audience_ids

required

IDs of audiences to update (1–50).

Array<string>

>= 1 items <= 50 items

set_logic

New set_logic to apply to all specified audiences.

string

Allowed values: union intersection

add_segment_id

Segment ID to append to the included list of each audience.

string

remove_segment_id

Segment ID to remove from the included list of each audience.

string

status

Valid user-settable transitions, applied to every audience in audience_ids: archived — soft-deletes the audience; excluded from list results by default. active — restores a previously archived audience back to active; rejected with 400 (INVALID_STATUS_TRANSITION) if the current status is not archived. System-managed statuses (pending, expired, failed) cannot be set via this endpoint and are rejected with 400.

string

Allowed values: archived active

Responses

200

All audiences updated.

Media typeapplication/json

object

updated

integer

failed

Array<object>

object

id

string

error

string

Example^generated

{
  "updated": 1,
  "failed": [
    {
      "id": "example",
      "error": "example"
    }
  ]
}

207

Partial success — at least one audience failed. Check the failed array.

Media typeapplication/json

object

updated

Number of audiences successfully updated.

integer

failed

Details for each audience that could not be updated.

Array<object>

object

id

string

error

string

Example^generated

{
  "updated": 1,
  "failed": [
    {
      "id": "example",
      "error": "example"
    }
  ]
}

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

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"
}

{
  "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).

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."
}