Enrichment

Micro-batch synchronous match

Synchronous inline matching for small record sets (up to 100 records). Submit your records and the list of attributes you want appended, and receive matched results immediately.

Person IDs: A real match returns a tier 01 iag_person_id: a stable, non-reversible ID salted for your organization. The same real identity is consistent inside your organization and different in every other organization. An unmatched row may receive a derived tier 02–05 ID from its own submitted signals. That derived value is a continuity label—not a graph match, licensed identity, refresh key, or resolved audience member. Use the match metadata and match_count, not ID presence alone, to identify real matches.

Billing: Usage is emitted per matched record only (unmatched records are free). The platform reserves a conservative ceiling and durably queues finalized usage for billing rather than debiting a local balance field. amount_charged is the conservative USD estimate accepted for provider delivery; it is not a finalized invoice amount. Independent workflows for your organization can settle concurrently. License reuse is checked per distinct identity against confirmed canonical history before settlement. If two overlapping workflows settle before either confirmation is visible, both can be charged for that identity; the canonical ledger retains one license period.

Records array: one output record per input record — matched or not. Unmatched rows carry match_level/match_type/match_confidence: null and a best-effort iag_person_id derived from the row's own identity signals (or null if none qualified) — only real matches are billed. Use match_count vs record_count to distinguish real matches from derived-only rows.

For datasets larger than 100 records, use POST /v1/match/file instead. Upload, analysis, and async matching are free until egress. The first successful delivery involving that file-match run emits its one aggregate match usage set together with normal delivery usage.

Retries: pass an Idempotency-Key header to make a retried call safe to repeat without a duplicate charge. The same key with an identical body returns the original response verbatim, at zero additional charge (honored for 24 hours); the same key with a different body is rejected with 409 IDEMPOTENCY_KEY_CONFLICT. Without this header, every call reserves and charges independently — recommended for any client that may retry on timeout. Requires 'creator' scope.

post/v1/match

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/match
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional. Makes a retried call safe to repeat — see the endpoint description's Retries section.

Request body

field_liststring[]

Enrichment attribute names to append on match — every attribute must be a field allowed for this output (see GET /v1/catalog/fields). Mutually exclusive with template_id. If neither is provided, the Standard Enrichment set (fields tagged audience or feature_store) is used. Populated enrichment attributes are returned for every accepted match level.

template_idstring

Pre-built enrichment bundle ID. standard_iag and standard_enrichment are valid (see templates[] in GET /v1/catalog/fields). Mutually exclusive with field_list. If neither is provided, the Standard Enrichment set is used.

match_levelstring[]

Filter results to specific match levels. I = individual, H = household, D = digital (email/phone only match), S = spatial (nearby-address proximity match), A = address-level. Defaults to all 5 levels (['I', 'H', 'D', 'S', 'A']) if omitted. A prior real match at one of the requested levels or a settled record license can authorize direct Refresh of a tier-01 ID. An identity without a prior real match at a requested level reports null match_level. Include I when requesting direct ID lookup because the engine classifies that path as I.

spatial_mode'residential' | 'work' | 'auto'

Phase 3 spatial trade-area profile. residential is the default; use work for workplace-oriented spatial matching, or auto for dynamic commercial workplace routing.

create_scratch_segmentboolean

When true, materialize the real matched identities from this completed response as a reusable 24-hour matched scratch segment. This reuses the already-paid result and does not run matching or billing again. The response's scratch_segment is null when no identities matched.

Response

Matched records.

record_countinteger

Total number of input records processed.

match_countinteger

Number of authorized records returned for a known identity.

license_approval_required_countinteger

Matched inputs withheld because the integration operation did not authorize a new licence or renewal. These inputs produce no enrichment output or licence charge and require explicit purchase approval. Ordinary manually requested matching returns zero.

billable_identity_countinteger

Number of unique real identities charged for this operation, deduplicated by internal identity rather than row count. Duplicate rows resolving to the same identity are counted once; a resubmitted iag_person_id for an identity with an active license contributes zero (free Refresh). May be less than or equal to match_count, and is the value actually billed — match_count describes matching, not billing.

match_ratenumber

match_count / record_count.

amount_chargednumber

Conservative platform estimate in USD for usage accepted for delivery (e.g. 0.30 means $0.30 estimated). This legacy-named field is not a local credit debit or finalized invoice amount; unmatched records emit no usage.

run_idstring

Unique identifier for this match run. Pass to GET /v1/match/runs/{runId} to retrieve full details or audit this call later. Requires 'discovery' scope to read.

Changes

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