Enrich a file with the API

File enrichment is the clean path for larger customer lists. Create the job, upload the file, let Infinite Audience do the matching, then export the result.

The workflow

Create a file job with POST /v1/match/file.
Upload the file to the returned signed URL.
Check GET /v1/match/file/{match_id} until matching is complete.
Create an export with POST /v1/match/{match_id}/deliveries.
Check GET /v1/match/{match_id}/deliveries, then download the completed result.

1. Create the job

curl -X POST https://api.infiniteaudience.ai/v1/match/file \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: q1-customer-file" \
  -d '{"name":"Q1 customer list","file_format":"csv"}'

Keep the returned match_id; it is the handle used throughout this workflow. The response also includes an upload_url, its expiration, and file settings.

For a file containing both home and workplace addresses, set "spatial_mode":"auto" when creating the job. Phase 3 matching then applies the wider commuter trade area to geocoded commercial addresses and the normal residential trade area to other inputs. The default is residential; work always uses commuter expansion. Coordinate-only inputs and ZIP5 centroid fallbacks do not trigger commercial expansion under auto. The selected mode applies to the file job and cannot be changed at delivery time.

2. Upload the file

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @customers.csv

The upload URL is already authorized, so do not add your bearer token. Upload URLs last 30 minutes. Use the content type that matches the declared format: text/csv, application/json, application/x-ndjson, or application/avro.

For large exports, request 2–50 shards and upload every returned URL. Repeat the same header row in each CSV shard.

3. Wait for matching

curl https://api.infiniteaudience.ai/v1/match/file/$MATCH_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Continue when matching_status is completed; stop and inspect error_message if it is failed. A segment.ready or segment.failed webhook can replace polling.

4. Create the export

curl -X POST https://api.infiniteaudience.ai/v1/match/$MATCH_ID/deliveries \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"include_unmatched":true}'

Add field_list or template_id when you want a specific enrichment set. The account’s pricing and active record licenses determine the final charge; use the quote endpoint before starting when you need a preview.

5. Download the result

curl https://api.infiniteaudience.ai/v1/match/$MATCH_ID/deliveries \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Find your delivery_id and wait for status: completed. Download URLs last 24 hours; call the same endpoint again whenever you need a fresh signed URL.

Understand the returned IDs

Resolved rows receive a tier 01 iag_person_id that is salted for your organization. Save it for supported refresh, segment, and audience workflows. An unmatched row may receive a derived tier 02–05 ID so it stays recognizable in your file; that value is not a real match or a refresh key. Use the match fields and totals—not ID presence alone—to separate resolved records from derived-only rows.

You can also upload a tier 01 ID from a licensed audience export of any subtype for direct refresh. That ID refers to a real person, but an audience delivery without matching does not establish a match_level. Include I in the requested match_level list for direct ID lookup (or omit the list to use the default). Submit independent identity signals when an ID cannot be resolved.

Learn how identity resolution works: inputs, matching levels, and the spatial engine →

Learn how person IDs and derived IDs work →

Review unusual columns first

Set hitl: true when your file uses internal or ambiguous column names. Upload the file, call POST /v1/match/{match_id}/analyze, review the suggested mapping, then confirm the complete map with POST /v1/segments/{match_id}/mappings. Matching begins after confirmation.