# Entity Resolution API Turn a company name plus context into one verified legal entity, anchored to a government registration, with a match confidence, the factors behind it, and per-field citations. Turn messy, unstructured business names into verified entity records. Research agents search government registries and the web, then anchor the answer to an official registration. ## Overview The Entity Resolution API automates the entity identification that used to need a manual research team. It is built for the long tail: businesses with little or no web presence, names embedded in legal documents, names carrying tax IDs or legal boilerplate, names in other scripts. - **Registry-anchored.** A confirmed entity is one we could tie to a government registration. No anchor, no match. - **Research, not lookup.** When we do not already hold the company, agents research it live across registries, directories, news and the company's own site. - **Explainable.** Every result carries `match_confidence`, the `factors[]` behind it, the `actions[]` that would sharpen an ambiguous query, and with `include=basis` the citations behind each field. - **One ID everywhere.** The resolved `siq_` ID is the key to [`/v3/entities/{id}`](/docs/apis/business-intelligence) and [Entity Hierarchy](/docs/apis/entity-hierarchy). > **Learn more:** [Entities and candidates](/docs/concepts/entities-and-candidates), [Handling messy data](/docs/guides/handling-messy-data), [Data sources](/docs/concepts/data-sources). ## How it works 1. **Cache check.** A name we have resolved before answers from cache. 2. **Research.** Otherwise agents investigate across sources and build consensus. 3. **Anchor.** The result is tied to an official registration where one exists; otherwise you get a `candidate`. 4. **Explain.** Factors, actions and basis are recorded with the run. Research takes one to five minutes, so the API is asynchronous: submit, then poll or receive a webhook. ## Endpoints ### `POST /v3/entity-resolution/async` Starts a run and returns a `run_id` immediately. `GET` with the same parameters as a query string also works. | Parameter | | | | --- | --- | --- | | `name` | required | Company name, legal or brand. At least 2 characters | | `location` | optional | Free-text location hint: city, state, country, or any combination | | `context` | optional | Free text describing which company you mean: industry, products, customers. Used only to choose between same-name candidates; never overrides registry evidence | | `include=basis` | optional | Record per-field provenance for this run. Repeat it on the poll to read it | | `webhook_url` | optional | Deliver the result to this URL instead of polling. See [Webhooks](/docs/guides/webhooks) | | `custom_id` | optional | Your own correlation key, returned with the result and on the webhook | **cURL** ```bash curl -X POST 'https://api.savvyiq.ai/v3/entity-resolution/async' \ -H 'apikey: YOUR_API_KEY' \ -H 'content-type: application/json' \ -d '{"name": "Datadog", "location": "New York, NY", "include": "basis"}' ``` **JavaScript** ```javascript const res = await fetch('https://api.savvyiq.ai/v3/entity-resolution/async', { method: 'POST', headers: { apikey: 'YOUR_API_KEY', 'content-type': 'application/json' }, body: JSON.stringify({ name: 'Datadog', location: 'New York, NY', include: 'basis' }), }); const { run_id } = await res.json(); ``` **Python** ```python import requests res = requests.post( 'https://api.savvyiq.ai/v3/entity-resolution/async', json={'name': 'Datadog', 'location': 'New York, NY', 'include': 'basis'}, headers={'apikey': 'YOUR_API_KEY'}, ) run_id = res.json()['run_id'] ``` ```json { "status": "pending", "run_id": "run_344tSxhAVACWbuENINJ9D" } ``` ### `GET /v3/runs/{run_id}` Polls a run. `202` while it is running, `200` with the result when it has finished. Pass `include=basis` here as well to read the citations. Polls are free and limited to 100 per minute. ```bash curl -G 'https://api.savvyiq.ai/v3/runs/run_344tSxhAVACWbuENINJ9D' \ --data-urlencode 'include=basis' \ -H 'apikey: YOUR_API_KEY' ``` ## Example result Datadog, from the reference capture. `basis` is shown for two fields only. ```json { "run_id": "run_344tSxhAVACWbuENINJ9D", "status": "matched", "match_confidence": 100, "type": "business", "subtype": "incorporated_entity", "entity": { "id": "siq_33d67jj0wJESjEdFHMhuQ", "display_name": "Datadog", "legal_name": "DATADOG, INC.", "status": "active", "description": "Datadog is a leading cloud monitoring and security platform ...", "website": "https://www.datadoghq.com/", "headquarters": { "address": { "street_address": "620 8th Ave, 45th Floor", "city": "New York", "state_code": "NY", "postal_code": "10018", "country_code": "US" } }, "primary_legal_entity": { "id": "le_2Zp3Yy6S7O6Btccq56WOH", "jurisdiction": "US-DE", "state_code": "DE", "country_code": "US", "registration_authority": { "code": "RA000602", "name": "Division of Corporations, Department of State", "website": "https://corp.delaware.gov/" } }, "identifiers": [ { "type": "registration_id", "value": "4832851", "jurisdiction": "US-DE" }, { "type": "cik", "value": "0001561550", "jurisdiction": null }, { "type": "lei", "value": "549300F6JNO0KRPO1K63", "jurisdiction": null } ], "facets": { "sector": "public", "legal_form": "corporation" }, "industry": { "schemes": { "naics_2022": [ { "code": "513210", "label": "Software Publishers", "confidence": 95, "is_primary": true }, { "code": "541511", "label": "Custom Computer Programming Services", "confidence": 80, "is_primary": false } ], "sic": [ { "code": "7372", "label": "Prepackaged Software", "confidence": 95, "is_primary": true } ] } } }, "candidate": null, "factors": [ { "code": "name_exact_match", "type": "strength", "impact": "Strong identifier for the correct entity.", "description": "The name 'Datadog' provided in the query exactly matches the entity's common name." }, { "code": "headquarters_match", "type": "strength", "impact": "Confirms this is the primary legal entity location.", "description": "The requested location 'New York, NY' precisely matches the entity's registered headquarters." }, { "code": "legal_entity_confirmed", "type": "strength", "impact": "Confirms a valid legal entity through official sources.", "description": "This has been definitively confirmed as the primary legal entity through official registration sources." }, { "code": "registry_identifier_anchored", "type": "strength", "impact": "Safe to use for deterministic record matching and deduplication.", "description": "The match is anchored by a stable government registry identifier." } ], "actions": [], "basis": [ { "field": "legal_name", "citations": [ { "url": "https://datadoghq.com", "source_type": "public_profile", "authority_tier": 2 } ] }, { "field": "primary_legal_entity.jurisdiction", "citations": [ { "url": "https://corp.delaware.gov/", "source_type": "government_registry", "authority_tier": 1 } ] } ], "metadata": { "query": { "mode": "standard", "name": "Datadog", "location": "New York, NY", "context": null, "classification": "specific" }, "from_cache": true, "cache_hit_type": "exact", "updated_at": "2026-07-31T19:22:05.042Z" } } ``` ## Reading the result - `entity` or `candidate`, never both. Branch on which is non-null, not on the score. See [Understanding API responses](/docs/handling-responses). - `match_confidence` is 0-100 for the whole match. `industry` codes carry their own per-code `confidence`. - `primary_legal_entity` is the anchoring registration; `identifiers[]` lists it alongside external IDs (CIK, LEI and others where known), canonicalized per type. - `facets` describe ownership and legal form. Industry lives under `industry.schemes`. - `metadata.from_cache` tells you whether the run answered from a prior resolution. Every code is listed in [Codes & enums](/docs/guides/codes-enums). ## Batch and webhooks For lists, submit with `custom_id` and `webhook_url` and let the results come to you. See [Batch processing](/docs/guides/batch-processing) and [Webhooks](/docs/guides/webhooks). ## Reference - [`POST /v3/entity-resolution/async`](/docs/reference/entity-resolution/post-v3-entity-resolution-async/) - [`GET /v3/runs/{run_id}`](/docs/reference/entity-resolution/get-v3-runs-run-id/) The v2 endpoints (`/v2/entity-resolution/stream`, `/v2/entity-resolution/async`) keep working; their reference is the [2026-07-30 edition](/docs/reference/2026-07-30/).