Bulk deliver multiple audiences

POST

/v1/deliveries/bulk

const url = 'https://api.infiniteaudience.ai/v1/deliveries/bulk';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"audience_ids":["aud_abc123","aud_def456"],"destination":"download","template_id":"standard_iag"}'
};

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://api.infiniteaudience.ai/v1/deliveries/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "audience_ids": [ "aud_abc123", "aud_def456" ], "destination": "download", "template_id": "standard_iag" }'

Accepts a list of audience IDs and shared delivery parameters. Fires N parallel delivery jobs and returns per-audience results as HTTP 207 Multi-Status. Partial failure is acceptable — failed items do not roll back succeeded ones. Download is the currently active destination; LiveRamp and Narrative return 503 before any item or billable record is created. An item whose audience count is unknown and cannot be computed fails with code AUDIENCE_COUNT_UNAVAILABLE. Requires ‘creator’ scope.

Authorizations

bearerAuth

Request Body^required

application/json

object

audience_ids

required

IDs of audiences to deliver. Max 25 per request.

Array<string>

>= 1 items <= 25 items

destination

required

Shared destination. liveramp and narrative currently return DELIVERY_DESTINATION_UNAVAILABLE without billing.

string

Allowed values: download liveramp narrative

template_id

Attribute template ID applied to every audience in the batch. standard_iag is valid; standard_enrichment is valid for pure matched exports and matching. Mutually exclusive with field_list. If neither is provided, the enrichment set is used for pure matched output; otherwise the audience set is used.

string | null

field_list

Explicit attribute list applied to every audience in the batch — every attribute must be a field allowed for that audience. Mutually exclusive with template_id. If neither is provided, the enrichment set is used for pure matched output; otherwise the audience set is used.

Array<string> | null

output_format

Shared download artifact format for the batch.

string

default: csv

Allowed values: csv avro json jsonl

output_compression

Shared artifact compression. gzip is supported for csv/json/jsonl; Avro uses native DEFLATE and rejects gzip.

string

default: none

Allowed values: none gzip

session_id

Chat session ID for push notification routing.

string | null

campaign_id

Campaign context for notification routing.

string | null

Example

{
  "audience_ids": [
    "aud_abc123",
    "aud_def456"
  ],
  "destination": "download",
  "template_id": "standard_iag"
}

Responses

207

Multi-Status — per-audience results. Each entry contains audience_id, delivery_id (if created), status, and error (if failed). Billing capacity errors also expose the same machine-readable code and USD-denominated capacity details as the single-audience delivery endpoint.

application/json

object

results

required

Array<object>

object

audience_id

required

string

delivery_id

Present when a delivery was created or found.

string

status

required

string

Allowed values: processing completed error

error

Error message when status is ‘error’.

string

code

Machine-readable billing code when billing prevents this item.

string

Allowed values: BILLING_INSUFFICIENT_BALANCE BILLING_POSTPAY_CEILING_EXCEEDED BILLING_CONSUMER_POSTPAY_CEILING_EXCEEDED BILLING_PROJECTION_STALE BILLING_NOT_READY

required

Conservative USD requirement for a prepay billing failure.

number

available

Effective USD availability for a prepay billing failure.

number

shortfall

USD shortfall for a prepay billing failure.

number

accrued

Projected USD spend for a postpay ceiling failure.

number

ceiling

Configured USD ceiling for a postpay ceiling failure.

number

output_format

Artifact format when an existing or new download delivery is returned.

string

Allowed values: csv avro json jsonl

output_compression

Artifact compression when an existing or new download delivery is returned.

string

Allowed values: none gzip

Example

{
  "results": [
    {
      "audience_id": "aud_abc123",
      "delivery_id": "dlv_xyz001",
      "status": "processing"
    },
    {
      "audience_id": "aud_def456",
      "status": "error",
      "error": "Audience expired on 2026-05-01. Run a refresh first."
    }
  ]
}

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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

missing_scope

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

503

A required billing provider partnership is temporarily unavailable.

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

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "INVALID_FILTER_SHAPE"
    }
  ]
}

Bulk deliver multiple audiences

Authorizations

Request Bodyrequired

Example

Responses

207

Example

400

Examples

401

Examples

403

Examples

503

Example

Request Body^required