Deliveries

Create a delivery for an audience

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. An audience whose record_count is unknown is counted before the delivery is reserved; if that count cannot be computed the request returns 503 AUDIENCE_COUNT_UNAVAILABLE and nothing is created. Requires 'creator' scope.

post/v1/audiences/{id}/deliveries

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/audiences/{id}/deliveries
  • Auth: HTTP bearer

Path parameters

idstring required

Audience document ID.

Headers

X-Integration-Run-Idstring

OAuth partnership workflows only. Re-authorizes the private audience against the same provider grant and binds delivery, native billing, history, and promotion to the exact partnership run.

Request body

destination'download' | 'liveramp' | 'narrative' required

download is active. liveramp and narrative currently return DELIVERY_DESTINATION_UNAVAILABLE without billing.

template_idstring nullable

Enrichment template ID. standard_iag and standard_enrichment are valid for enrichment (see templates[] in GET /v1/catalog/fields). Mutually exclusive with field_list. If neither template_id nor field_list is provided, the enrichment set is used for pure matched output; otherwise the audience set is used.

field_liststring[] nullable

Explicit list of attribute names to include in the export (alternative to template_id) — 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. Populated enrichment attributes are returned for every match level. 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.

include_unmatchedboolean

(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.

webhook_urlstring uri

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. Every dispatch is signed regardless of which URL is used — see the Webhooks tag for the envelope shape and signing scheme.

liveramp_seat_idstring

(liveramp destination only) Your LiveRamp seat ID.

narrative_dataset_idstring

(narrative destination only) Your Narrative.io dataset ID.

output_format'csv' | 'avro' | 'json' | 'jsonl' nullable

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 source column types including REPEATED/array attributes. Ignored for liveramp and narrative destinations.

output_compression'none' | 'gzip'

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.

Response

Delivery created and queued.

delivery_idstring required
audience_idstring required
audience_versioninteger required
destination'download' | 'liveramp' | 'narrative' required
template_idstring nullable
field_liststring[] nullable
status'processing' | 'completed' | 'failed' required
costnumber required

Conservative USD estimate for usage accepted for billing; not a finalized invoice total.

estimated_costnumber

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.

already_deliveredboolean

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.

messagestring

Human-readable note, present on free re-delivery responses.

created_atstring required
completed_atstring nullable
expires_atstring required
output_format'csv' | 'avro' | 'json' | 'jsonl'

Output file format. Present on download deliveries. Avro exports preserve native source 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.

output_compression'none' | 'gzip'

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.

output_bytesinteger nullable

Exact sum of stored object sizes across every output part. Null until completion or when no downloadable artifact is produced.

download_urlsstring[] nullable

Signed download URLs for every completed download artifact part, sorted deterministically. Always an array and may contain multiple export parts for any format. Signed URLs expire after 24 hours — call GET /v1/audiences/{id}/deliveries/{did} to regenerate fresh URLs at any time.

output_record_countinteger nullable

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.

failure_reasonstring nullable
matched_segment_idstring nullable

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.

source_job_idstring nullable

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

integration_run_idstring

Present only for an authorized private partnership workflow.

Changes

No recorded changes to this operation across all 1 revision of this API.