Entity Resolution

Resolve a company name

GET /v3/entity-resolution/async

View as markdown Open in ChatGPT Open in Claude

Starts a resolution job and returns immediately with a job ID. Research typically takes one to five minutes; poll GET /v3/jobs/{job_id} for the result.

Resolution finds the company through government registries and live web research, then anchors it to an official registration. Use context to say which company you mean when a name is ambiguous.

Query parameters

namestring required
Company name, legal or brand. At least 2 characters.
locationstring
Free-text location hint: city, state, country, or any combination. Narrows an ambiguous name considerably.
contextstring
Free text describing which company you mean: industry, products, customers, anything distinguishing. Used only to choose between same-name candidates. It never overrides government-registry evidence and never changes what is searched.

name=Delta on its own is ambiguous. name=Delta with context=major commercial passenger airline resolves to Delta Air Lines, Inc.
includestring (enum)
basis
Set to basis to attach the provenance plane to the result: per-field confidence, reasoning, and citations back to the sources.

Pass it on the poll as well. Asking here is what makes the job record provenance; asking again on GET /v3/jobs/{job_id} is what puts it in the response body. A job kicked off without basis cannot gain it later, and a poll without basis omits the plane even when the job recorded one.

Responses

202 Job accepted.

statusstring (enum)
pending
job_idstring
Job identifier, accepted by GET /v3/jobs/{job_id}.
request_idstring
The reqa_ form of the same job. Also accepted by GET /v3/jobs/{job_id}, and useful as a correlation ID in support requests.

400 Invalid or missing parameters.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

401 Missing or invalid API key.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

402 Credit balance exhausted.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

403 This account is not enabled for the v3 API.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

429 Rate limit exceeded.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

500 Something went wrong on our side.

errorobject
Show 2 nested fieldsHide nested fields
- typestring
  Stable, machine-readable error code.
- messagestring
  Human-readable explanation. Do not match on this.

Example request

cURL

curl --request GET \
  --url 'https://api.savvyiq.ai/v3/entity-resolution/async?name=Datadog&location=New%20York%2C%20NY&include=basis' \
  --header 'apikey: YOUR_API_KEY'

Example response

Example202

{
  "status": "pending",
  "job_id": "019fe975-186e-707c-b59a-b0a6c9914221",
  "request_id": "reqa_344tSxhAVACWbuENINJ9D"
}