Deliveries

Deliver a file match job

Convenience wrapper around POST /v1/audiences/{id}/deliveries for file-based match jobs. Always delivers to the download destination — the enriched file is exported to a time-limited signed URL. Omits DSP-only destinations (LiveRamp, Narrative) and their associated parameters.

Workflow (after POST /v1/match/file):

Upload your file to the upload_url returned by POST /v1/match/file. This upload is what triggers identity resolution to begin — not this endpoint.
(Recommended) POST /v1/match/{segment_id}/analyze — preview column mapping. Check unmapped_columns and confidence values. If mappings look wrong, rename columns in your file and re-upload before triggering delivery.
Poll GET /v1/match/file/{match_id} until matching_status is completed (or use a segment.ready webhook). Calling this endpoint before resolution finishes returns 422 AUDIENCE_PENDING.
POST /v1/match/{match_id}/deliveries (this endpoint) — export the already- resolved match to a signed download URL. Optionally supply template_id or field_list to choose which enriched attributes to include in the output — if neither is given, the enrichment set is used for pure matched output; otherwise the audience set is used.
Poll GET /v1/match/{match_id}/deliveries for status — it takes the match id directly, needs no audience id, and re-signs download_urls on every read. (The audience-scoped GET /v1/audiences/{audience_id}/deliveries/{delivery_id} also works but requires the audience id, which this wrapper is designed to let you avoid.) When status: completed, download_urls (array of signed URLs) is returned.

All billing, dedup, reservation, and usage-outbox logic is handled identically to POST /v1/audiences/{id}/deliveries. Re-running the exact same (match_id × version × template) is always free. Requires 'creator' scope.

post/v1/match/{id}/deliveries

Request

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

Path parameters

idstring required

The match_id returned by POST /v1/match/file.

Request body

include_unmatchedboolean

Include rows that did not resolve to a real graph match in the output file — 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 receive only matched records. Defaults to true. Every exported row (matched or not) also carries a row_id column matching your original upload, for correlating 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.

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 is provided, the Standard Enrichment set (audience plus feature-store fields) is used for a pure matched export.

field_liststring[] nullable

Explicit list of attribute names to append — every attribute must be a valid enrichment attribute. Use GET /v1/catalog/fields to browse available attributes. 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.

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.

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

Output file format. Omit to auto-detect from the uploaded file's format (avro → avro, csv → csv, json → json, jsonl → jsonl). Avro exports preserve native column types including REPEATED/array attributes. CSV is the default when format cannot be determined.

output_compression'none' | 'gzip'

Explicit output artifact compression, independent of the uploaded file. gzip is supported for csv/json/jsonl. Avro uses native DEFLATE and rejects outer gzip.

Response

Delivery initiated — or a free re-delivery if this (match_id × version × template) was already completed.

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.