Entity resolution

Deep research for entity by name (async)

GET /v2/entity-resolution/async

View as markdown Open in ChatGPT Open in Claude

Submit an async deep research request (3-5 minutes). Returns 202 with a request_id; poll /v2/entity-resolution/status/{request_id} for the result.

Billed on submission. Polls are free, and a FAILED job is refunded automatically.

For sub-second results, try Instant Search first.

Query parameters

namestring required
Name of the entity to resolve
locationstring
Optional location of the entity

Responses

202 Accepted and queued. Poll `/v2/entity-resolution/status/{request_id}` for the result.

request_idstring required
statusstring (enum) required
PENDING

400 Bad Request

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

401 Unauthorized

messagestring
The error object.
request_idstring
The request ID for the error.

402 Your account balance is too low to cover this request. Top up and retry — nothing was charged and no job was created. Usage is drawn from your prepaid balance per request, so this means the balance ran short, not that a request quota was used up.

errorstring (enum)
insufficient_creditsno_pricing_configuredfree_plan_limitmonthly_cap_reachedmonthly_spend_limit_reachedbilling_error
The reason the request was denied.
messagestring
A human-readable explanation.

403 This API is not enabled for your account. Topping up your balance will not change this — contact support.

errorstring (enum)
insufficient_creditsno_pricing_configuredfree_plan_limitmonthly_cap_reachedmonthly_spend_limit_reachedbilling_error
The reason the request was denied.
messagestring
A human-readable explanation.

429 Either the per-minute rate limit (600 requests/minute per account on this endpoint, body `{ "message": … }`) or a plan limit — free-plan allowance, monthly request cap, monthly spend limit — which uses the `{ "error": …, "message": … }` body shown below. See [rate limits](/docs/rate-limits).

errorstring (enum)
insufficient_creditsno_pricing_configuredfree_plan_limitmonthly_cap_reachedmonthly_spend_limit_reachedbilling_error
The reason the request was denied.
messagestring
A human-readable explanation.

500 Internal Server Error

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

503 Billing is temporarily unavailable. Nothing was charged. Retry with backoff.

errorstring (enum)
insufficient_creditsno_pricing_configuredfree_plan_limitmonthly_cap_reachedmonthly_spend_limit_reachedbilling_error
The reason the request was denied.
messagestring
A human-readable explanation.

504 Gateway Timeout — the request was not accepted in time. Retry with backoff. Submission is not idempotent: if the first attempt did land, a retry creates a second job.

errorobject
An error object.
Show 2 nested fieldsHide nested fields
- messagestring
  The error message
- typestring
  The error code

Example request

cURL

curl --request GET \
  --url 'https://api.savvyiq.ai/v2/entity-resolution/async?name=Apple%20Inc.&location=California%2C%20US' \
  --header 'apikey: YOUR_API_KEY'

Example response

Example202

{
  "request_id": "reqa_2ZUKmavJxCx4GHMnpJsc9",
  "status": "PENDING"
}