One published contract
The downloadable OpenAPI document is the source of truth for entity resolution, enrichment jobs, record results, graph queries, evidence, review decisions, and result artifacts.
Synchronous resolution, asynchronous enrichment
POST /entity-resolution/resolve returns one identity decision immediately. POST /enrichment-jobs accepts a durable batch, applies the same resolution model, enriches accepted facts, and returns 202 for asynchronous processing.
Asynchronous job states
A successful submission returns 202 and a Location header. Poll the durable job until it reaches completed, failed, or cancelled. A completed job may still contain review cases.
Safe retries
Use one Idempotency-Key for one exact batch. Repeating the same request returns the original job; reusing the key for different records returns 409.
Freshness and source conflicts stay visible
Every accepted fact carries observed_at and freshness. When allowed sources disagree, status becomes conflicted and observations retains each provider value, trust tier, confidence, and selection state. Source policy can exclude providers, licenses, cost tiers, or trust levels before selection.
Production-realistic fake scenarios
| X-Fake-Scenario | Behavior |
|---|---|
| async-job | queued → processing → completed across job reads |
| source-conflict | Retains authoritative and curated conflicting observations |
| partial-failure | Completes the batch while one record fails retryably |
| webhook-retry | Records a 503 delivery and deterministic next retry |
| server-error-once | Returns one retryable 503, then succeeds |
| rate-limited | Returns 429 with Retry-After and reset headers |
| slow | Adds a bounded deterministic delay |