APIs

Entity Resolution API

View as markdown Open in ChatGPT Open in Claude

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} and Entity Hierarchy.

Learn more: Entities and candidates, Handling messy data, Data sources.

How it works

Cache check. A name we have resolved before answers from cache.
Research. Otherwise agents investigate across sources and build consensus.
Anchor. The result is tied to an official registration where one exists; otherwise you get a candidate.
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
`custom_id`	optional	Your own correlation key, returned with the result and on the webhook

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"}'

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();

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']

{ "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.

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.

{
  "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.
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.

Batch and webhooks

For lists, submit with custom_id and webhook_url and let the results come to you. See Batch processing and Webhooks.

Reference

The v2 endpoints (/v2/entity-resolution/stream, /v2/entity-resolution/async) keep working; their reference is the 2026-07-30 edition.