Skip to main content
Enrichment is the other direction from search. You have a list — competitor storefronts from a spreadsheet, creators from an outreach tool, products from a supplier catalogue — and you want Unif data attached to it.
One call does resolution and retrieval together, for up to 100 inputs. Beyond that, use an enrichment job.

​
Requesting fields

fields takes dot-paths. Omit it to get the full record.
Narrowing the field set is worth doing for two reasons: it lowers the credit cost of the call, and it makes meta.completeness meaningful — completeness is measured against what you asked for, so a full-record request will almost always report less than 1 for reasons you do not care about.
Request the narrowest field set that satisfies your use case, then widen it when a feature needs more. Starting from the full record and trimming later means re-testing everything.

​
Joining results back

Set ref on every input. Unif echoes it untouched, and results arrive in the order sent.
Store result["data"]["id"] on your row the first time. Every later refresh is then a direct lookup by ID, which is cheaper than resolving a URL again and immune to the entity being renamed.

​
Handling each status

One input failing never fails the batch, so every result needs a branch.
Everything you asked for came back. data is populated.
Resolved, but some requested fields were unavailable. data is populated and meta.missing_fields names the gaps. Usually a coverage limit in that market rather than a problem with the row.
The cascade ran to the end and no source verified a match — a dead listing, a typo, or an entity outside your enabled markets. Every step missed, so the row cost nothing. Retrying will not help; route it to a human or drop it.
Several entities matched. candidates lists them. Pick one with your own rule and store the decision, or the same input stays ambiguous forever.
The channel or entity type is not enabled for your workspace. An entitlement problem, not a data problem — check GET /channels.
A miss rate that jumps is nearly always an input problem — a stale export, or URLs copied from a different market — and it is worth alerting on rather than discovering in a dashboard.

​
Refreshing on a schedule

Enrichment is not a one-time step. Metrics move, so a row enriched last month is stale.

Scheduled re-enrichment

Re-enrich by stored ID on your own cadence. Cheapest for a set you want a fresh number on every day regardless of whether it moved.

Trackers

Let Unif watch the set and post a webhook only when a metric crosses your threshold. Cheapest when you only care about change.
For a set you re-check often, put it in a list — then a refresh is one call to GET /lists/{id}/items with the period you want, rather than a batch you have to rebuild each time.

​
Idempotency

Enrich accepts an Idempotency-Key header. Retrying with the same key returns the original response instead of doing — and charging for — the work twice.
Use it whenever a retry could be triggered by something other than you: a queue redelivery, a timeout your client retried, a job runner that restarts. See Idempotency.