Entity Resolution

Resolve a company name

POST /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/runs/{run_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.

Also accepts GET with the same parameters as a query string.

Request body

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.
custom_idstring
Your own identifier for this request — an order id, an account id, a row id. Returned on this 202, on every GET /v3/runs/{run_id}, and on the webhook event, so you can match our response to your record without keeping a run_id table.

A label only: it does not route the webhook, does not have to be unique, and cannot be used to look a request up. Rejected with 400 rather than trimmed if it is too long or contains anything outside printable ASCII.
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/runs/{run_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
run_idstring
The run's identifier, and what you poll with. Distinct from request_id, which identifies a single HTTP call: a run outlives the call that started it.
custom_idstring
Your custom_id from the request that started this job. Absent if you did not send one.

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 POST \
  --url 'https://api.savvyiq.ai/v3/entity-resolution/async' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"name":"Datadog","location":"New York, NY","context":"cloud monitoring and security platform","custom_id":"order_88213","include":"basis"}'

Example response

Example202

{
  "status": "pending",
  "run_id": "run_344tSxhAVACWbuENINJ9D",
  "custom_id": "order_88213"
}