Create a delivery for an audience
const url = 'https://dev-api.infiniteaudience.ai/v1/audiences/example/deliveries';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"destination":"download","template_id":"example","field_list":["example"],"include_unmatched":true,"webhook_url":"https://example.com","liveramp_seat_id":"example","narrative_dataset_id":"example","output_format":"csv","output_compression":"none"}'};
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/audiences/example/deliveries \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "destination": "download", "template_id": "example", "field_list": [ "example" ], "include_unmatched": true, "webhook_url": "https://example.com", "liveramp_seat_id": "example", "narrative_dataset_id": "example", "output_format": "csv", "output_compression": "none" }'Initiates a delivery of the audience to the specified destination and emits usage only after successful egress. Download is currently active. LiveRamp and Narrative return 503 before a delivery or billable record is created until their partner pushes are implemented. Returns the new DeliveryObject — poll GET /v1/audiences/{id}/deliveries/{delivery_id} for status updates.
Requires ‘purchase’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Audience document ID.
Request Bodyrequired
Section titled “Request Bodyrequired”object
download is active. liveramp and narrative currently return DELIVERY_DESTINATION_UNAVAILABLE without billing.
Enrichment template ID. Only standard_iag is valid (see templates[] in GET /v1/catalog/fields). Mutually exclusive with field_list. If neither template_id nor field_list is provided, the Standard IAG attribute set (all attributes with product_usage containing audience) is used.
Explicit list of attribute names to include in the export (alternative to template_id) — every attribute must be a valid audience attribute. Mutually exclusive with template_id. If neither is provided, the Standard IAG attribute set is used. For matched-subtype rows, individual-level attributes (e.g. age, gender) come back null for a row whose match_level doesn’t qualify for individual-level data — this is expected, not an error. If iag_household_id is requested and available for a row, it is exported in the same org-scoped, non-reversible format as iag_person_id.
(matched subtype only) When true (default), the export includes rows from your upload that did not resolve to a real graph match — these appear with null enrichment attributes and, in the exported iag_person_id column, a best-effort id deterministically derived from the row’s own identity signals (or null if none qualified) rather than a real platform match. Set to false to export resolved records only. Every exported row (matched or not) also carries a row_id column matching your original upload, so you can correlate a delivered row back to its source input row regardless of match status. Matched rows additionally carry match_level (I/H/A/S/D), match_type (e.g. graph_name_email_match, vector_name_address_match, spatial_match), and match_confidence (0–1) — all null (not derived) on unmatched rows.
Optional HTTPS URL to receive delivery.completed or delivery.failed events for this delivery. Overrides the org-level webhook URL for this request only; if omitted, the org-configured URL is used as the fallback. If a signing secret is set in Settings, the dispatch includes X-CF-Signature: sha256=<hmac-hex> regardless of which URL is used. See the Webhooks tag for payload shapes and signing verification guidance.
(liveramp destination only) Your LiveRamp seat ID.
(narrative destination only) Your Narrative.io dataset ID.
Output file format for download deliveries. Omit to auto-detect: matched audiences default to the format of the original uploaded file (avro → avro, csv → csv, json → json, jsonl → jsonl); all other subtypes default to csv. Avro exports preserve native BigQuery column types including REPEATED/array attributes. Ignored for liveramp and narrative destinations.
Explicit artifact compression; it never inherits matched input compression. gzip is supported for csv/json/jsonl. Avro uses native DEFLATE and rejects outer gzip. Ignored for non-download destinations.
Responses
Section titled “Responses”Delivery created and queued.
object
Conservative USD estimate for usage accepted for billing; not a finalized invoice total.
Pre-flight safety ceiling for a still-processing delivery. It is released into the final local cost estimate once resolution/export completes; the finalized invoice remains authoritative.
true when this exact audience content, resolved field selection, unmatched-row policy, and destination were already delivered — cost is 0 and the existing delivery record is returned.
Human-readable note, present on free re-delivery responses.
Output file format. Present on download deliveries. Avro exports preserve native BigQuery column types (including REPEATED/array columns) rather than flattening everything to strings. Read endpoints normalize legacy records; an immediate DSP-create response may omit this field.
Explicit outer artifact compression, normalized to none for legacy records on read and possibly omitted by an immediate DSP-create response. It never inherits input compression. Avro uses native DEFLATE and therefore reports none here rather than outer gzip.
Exact sum of stored object sizes across every output part. Null until completion or when no downloadable artifact is produced.
Signed GCS download URLs for every completed download artifact part, sorted deterministically. Always an array and may contain multiple BigQuery export shards for any format. Signed URLs expire after 24 hours — call GET /v1/audiences/{id}/deliveries/{did} to regenerate fresh URLs at any time.
Actual row count in the exported file. Set at completion for matched audiences only (where the count is unknown until the TVF runs). For filter, similarity, and propensity audiences this equals the audience’s record_count.
ID of the matched (file-match) segment resolved from the delivered audience’s composition at delivery creation. Populated only when the audience includes a matched segment; null for filter, similarity, and propensity deliveries and for deliveries created before this attribute existed.
The matched segment’s originating file-match job ID — links the delivery back to the file-match event that produced its source data. Populated only when the delivered audience resolves a matched segment that carries a source job; null otherwise (including deliveries created before this attribute existed).
Example
{ "destination": "download", "status": "processing", "output_format": "csv", "output_compression": "none"}Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Bad Request", "code": "MISSING_SEGMENTS", "message": "segment_ids is required for filter audiences."}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).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Unauthorized: Missing or invalid Authorization header"}{ "error": "Unauthorized", "code": "TOKEN_EXPIRED", "message": "Your session has expired. Please sign in again."}The request cannot proceed on billing grounds. BILLING_INSUFFICIENT_BALANCE applies only to prepay accounts and includes required, available, and shortfall in USD. BILLING_POSTPAY_CEILING_EXCEEDED applies to an account ceiling; BILLING_CONSUMER_POSTPAY_CEILING_EXCEEDED applies to an agency child’s routed ceiling. Both ceiling responses include projected accrued and configured ceiling in USD.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Insufficient balance", "code": "BILLING_INSUFFICIENT_BALANCE", "message": "Insufficient effective balance", "required": 1, "available": 0.75, "shortfall": 0.25}{ "error": "Billing capacity unavailable", "code": "BILLING_POSTPAY_CEILING_EXCEEDED", "message": "Postpay ceiling would be exceeded", "accrued": 105, "ceiling": 100}Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the purchase scope."}Resource not found or not accessible to the calling org.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Audience not found"}Request is structurally valid but the resource is in a state that prevents the operation (e.g. expired, pending, or not yet uploaded). See error and code for the specific reason.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Audience expired", "code": "AUDIENCE_EXPIRED", "message": "This audience version expired. Run a refresh to create a new deliverable version."}{ "error": "Audience not ready", "code": "AUDIENCE_PENDING", "message": "This audience is still being processed. Poll GET /v1/audiences/{id} until status is active."}A required billing provider integration is temporarily unavailable.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examplegenerated
{ "error": "example", "message": "example", "code": "example", "request_id": "example"}