Entity resolution

Get status of deep research request

GET /v2/entity-resolution/status/{request_id}

View as markdown Open in ChatGPT Open in Claude

Retrieve the status and result of an async deep research request. Poll every 5-10 seconds. Polls are free.

Returns 202 while PENDING, and 200 once the job is terminal — COMPLETED or FAILED. A failure is reported in the body with HTTP 200, not as an error status.

COMPLETED does not mean a match was found. Branch on whether data.entity or data.candidate is populated — they are never both set, and on no_match / not_found neither is.

Path parameters

request_idstring required
ID of the resolution request

Responses

200 The job is terminal. `status` is `COMPLETED` or `FAILED` — both return 200.

request_idstring required
statusstring (enum) required
PENDINGCOMPLETEDFAILED
Job lifecycle state.
- PENDING — still researching; HTTP 202, data is null
- COMPLETED — finished; read data.status for the outcome
- FAILED — did not complete; data is null and the request is refunded
dataobject
The resolution result. null while PENDING and on FAILED.
Show 10 nested fieldsHide nested fields
- request_idstring
  The request ID for this API call
- statusstring (enum)
  matchedpartial_matchinconclusiveno_matchnot_found
  Outcome of the resolution. Distinct from the job lifecycle status on the polling envelope — a COMPLETED job carrying no_match is still a successful call.
  
  matched - confidence 80 or above; entity is populated
  
  partial_match - resolved to a known business, confidence below 80; entity is populated
  
  inconclusive - multiple possible matches, or an entity type not fully supported; candidate may hold a best guess
  
  no_match - no matches found; both entity and candidate are null
  
  not_found - the query did not correspond to a resolvable business; both entity and candidate are null
  
  entity and candidate are never both populated, but they can both be null — that is how "we found nothing" is represented. Always handle the neither-present case.
- typestring (enum)
  businessnonprofitgovernmentpersonotherunknown
  The entity type. Currently the system only fully supports "business" types. Other types may be identified but will be returned as candidates only.
- subtypestring (enum)
  Show 9 possible valuesHide possible values
  incorporated_entityunincorporated_entitynonprofit_entitygovernment_entitynatural_personcomplex_business_structuretrading_name_onlyother_entityunknown
  The entity subtype. Currently the system only fully supports "incorporated_entity" subtypes. Other subtypes (like "unincorporated_entity", "government", "fund") will be returned as candidates only.
- confidenceinteger
  The confidence score of the match (0-100). Higher scores generally correspond to entity records, while lower scores correspond to candidates.
- entityobject
  The matched entity details. This field is populated only for high-confidence matches of supported entity types. Will be null when the candidate field is populated. Currently only entities of type "business" and subtype "incorporated_entity" will have this field populated.
  Show 8 nested fieldsHide nested fields
  idstring
  namestring
  statusstring (enum)
  activeinactive
  websitestring
  descriptionstring
  headquartersobject
  Show 6 nested fieldsHide nested fields
  citystring
  statestring
  addressstring
  countrystring
  state_codestring
  country_codestring
  matching_branchobject
  Show 5 nested fieldsHide nested fields
  notesstring
  addressstring
  state_codestring
  country_codestring
  jurisdictionstring
  primary_legal_entityobject
  Show 5 nested fieldsHide nested fields
  idstring
  namestring
  state_codestring
  country_codestring
  jurisdictionstring
- candidateobject
  Best matching candidate when no high-confidence match exists, or when the entity type is not fully supported yet. This field is populated when the entity field is null. This happens when:
  
  The confidence is too low to create a definitive record
  
  The entity type or subtype is not fully supported yet (e.g., unincorporated entities, governments, funds)
  Show 6 nested fieldsHide nested fields
  namestring
  legal_namestring
  jurisdictionstring
  statusstring (enum)
  activeinactive
  descriptionstring
  primary_addressobject
  Show 3 nested fieldsHide nested fields
  full_addressstring
  state_codestring
  country_codestring
- factorsarray<object>
  Factors contributing to the match decision
  Show 4 nested fieldsHide nested fields
  codestring
  typestring (enum)
  strengthlimitation
  impactstring
  descriptionstring
- actionsarray<object>
  Suggested actions for the user
  Show 2 nested fieldsHide nested fields
  codestring
  descriptionstring
- metadataobject
  Additional information about the request
  Show 5 nested fieldsHide nested fields
  queryobject
  Show 5 nested fieldsHide nested fields
  modestring
  namestring
  contextstring
  locationstring
  classificationstring
  from_cacheboolean
  Whether the resolution engine answered from its query cache instead of running fresh research. Specific to the research layer, not a general "response was cached" flag.
  updated_atstring <date-time>
  resolved_atstring <date-time>
  cache_hit_typestring (enum)
  exactsimilardomain_cache
  How the cache was hit when from_cache is true; null otherwise.
  
  exact - the same query was resolved before
  
  similar - a semantically equivalent query was reused
  
  domain_cache - answered from a previous domain lookup

202 Still processing. `status` is `PENDING`, `data` is `null`. Keep polling.

request_idstring required
statusstring (enum) required
PENDINGCOMPLETEDFAILED
Job lifecycle state.
- PENDING — still researching; HTTP 202, data is null
- COMPLETED — finished; read data.status for the outcome
- FAILED — did not complete; data is null and the request is refunded
dataobject
The resolution result. null while PENDING and on FAILED.
Show 10 nested fieldsHide nested fields
- request_idstring
  The request ID for this API call
- statusstring (enum)
  matchedpartial_matchinconclusiveno_matchnot_found
  Outcome of the resolution. Distinct from the job lifecycle status on the polling envelope — a COMPLETED job carrying no_match is still a successful call.
  
  matched - confidence 80 or above; entity is populated
  
  partial_match - resolved to a known business, confidence below 80; entity is populated
  
  inconclusive - multiple possible matches, or an entity type not fully supported; candidate may hold a best guess
  
  no_match - no matches found; both entity and candidate are null
  
  not_found - the query did not correspond to a resolvable business; both entity and candidate are null
  
  entity and candidate are never both populated, but they can both be null — that is how "we found nothing" is represented. Always handle the neither-present case.
- typestring (enum)
  businessnonprofitgovernmentpersonotherunknown
  The entity type. Currently the system only fully supports "business" types. Other types may be identified but will be returned as candidates only.
- subtypestring (enum)
  Show 9 possible valuesHide possible values
  incorporated_entityunincorporated_entitynonprofit_entitygovernment_entitynatural_personcomplex_business_structuretrading_name_onlyother_entityunknown
  The entity subtype. Currently the system only fully supports "incorporated_entity" subtypes. Other subtypes (like "unincorporated_entity", "government", "fund") will be returned as candidates only.
- confidenceinteger
  The confidence score of the match (0-100). Higher scores generally correspond to entity records, while lower scores correspond to candidates.
- entityobject
  The matched entity details. This field is populated only for high-confidence matches of supported entity types. Will be null when the candidate field is populated. Currently only entities of type "business" and subtype "incorporated_entity" will have this field populated.
  Show 8 nested fieldsHide nested fields
  idstring
  namestring
  statusstring (enum)
  activeinactive
  websitestring
  descriptionstring
  headquartersobject
  Show 6 nested fieldsHide nested fields
  citystring
  statestring
  addressstring
  countrystring
  state_codestring
  country_codestring
  matching_branchobject
  Show 5 nested fieldsHide nested fields
  notesstring
  addressstring
  state_codestring
  country_codestring
  jurisdictionstring
  primary_legal_entityobject
  Show 5 nested fieldsHide nested fields
  idstring
  namestring
  state_codestring
  country_codestring
  jurisdictionstring
- candidateobject
  Best matching candidate when no high-confidence match exists, or when the entity type is not fully supported yet. This field is populated when the entity field is null. This happens when:
  
  The confidence is too low to create a definitive record
  
  The entity type or subtype is not fully supported yet (e.g., unincorporated entities, governments, funds)
  Show 6 nested fieldsHide nested fields
  namestring
  legal_namestring
  jurisdictionstring
  statusstring (enum)
  activeinactive
  descriptionstring
  primary_addressobject
  Show 3 nested fieldsHide nested fields
  full_addressstring
  state_codestring
  country_codestring
- factorsarray<object>
  Factors contributing to the match decision
  Show 4 nested fieldsHide nested fields
  codestring
  typestring (enum)
  strengthlimitation
  impactstring
  descriptionstring
- actionsarray<object>
  Suggested actions for the user
  Show 2 nested fieldsHide nested fields
  codestring
  descriptionstring
- metadataobject
  Additional information about the request
  Show 5 nested fieldsHide nested fields
  queryobject
  Show 5 nested fieldsHide nested fields
  modestring
  namestring
  contextstring
  locationstring
  classificationstring
  from_cacheboolean
  Whether the resolution engine answered from its query cache instead of running fresh research. Specific to the research layer, not a general "response was cached" flag.
  updated_atstring <date-time>
  resolved_atstring <date-time>
  cache_hit_typestring (enum)
  exactsimilardomain_cache
  How the cache was hit when from_cache is true; null otherwise.
  
  exact - the same query was resolved before
  
  similar - a semantically equivalent query was reused
  
  domain_cache - answered from a previous domain lookup

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.

404 No such `request_id` for this account. IDs are account-scoped, so another account's `request_id` returns 404 rather than revealing that it exists. A malformed `request_id` returns 500, not 404.

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

429 Rate limit exceeded — 600 requests/minute per account on this endpoint. See [rate limits](/docs/rate-limits).

messagestring
The error message

500 Internal Server Error

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

504 Gateway Timeout — retry the poll with backoff.

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/status/reqa_2ZUKmavJxCx4GHMnpJsc9' \
  --header 'apikey: YOUR_API_KEY'

Example response

High confidence match with entity record200

{
  "request_id": "reqa_2ZUKmavJxCx4GHMnpJsc9",
  "status": "COMPLETED",
  "data": {
    "status": "matched",
    "confidence": 98,
    "type": "business",
    "subtype": "incorporated_entity",
    "entity": {
      "id": "siq_2ZUKocPbFCPLClZ5XtHlJ",
      "name": "Apple",
      "status": "active",
      "website": "apple.com",
      "description": "Designs, develops, and sells consumer electronics, computer software, and online services.",
      "headquarters": {
        "city": "Cupertino",
        "state": "California",
        "address": "ONE APPLE PARK WAY",
        "country": "United States",
        "state_code": "CA",
        "country_code": "US"
      },
      "primary_legal_entity": {
        "id": "le_2ZoRp6I3EUgebkUBHaDdk",
        "name": "APPLE INC.",
        "state_code": null,
        "country_code": "US",
        "jurisdiction": "California"
      },
      "matching_branch": {
        "notes": "Headquarters is located in California",
        "address": "ONE APPLE PARK WAY, CUPERTINO, CA, 95014, United States",
        "state_code": "CA",
        "country_code": "US",
        "jurisdiction": "California"
      }
    },
    "candidate": null,
    "factors": [
      {
        "code": "name_close_match",
        "type": "strength",
        "impact": "High confidence that this is the correct entity due to brand recognition.",
        "description": "The provided name 'Apple Inc.' closely matches the legal entity name 'Apple'. While not an exact match, the common usage of 'Apple' for 'Apple Inc.' makes this a strong indicator."
      },
      {
        "code": "jurisdiction_match",
        "type": "strength",
        "impact": "Confirms this is the primary legal entity location.",
        "description": "The provided location 'California, US' matches the entity's registered jurisdiction."
      },
      {
        "code": "multiple_sources_corroboration",
        "type": "strength",
        "impact": "Very high confidence due to broad confirmation across sources.",
        "description": "Multiple authoritative sources confirm this entity's details, increasing the confidence in the match."
      },
      {
        "code": "legal_entity_confirmed",
        "type": "strength",
        "impact": "This ensures that the result is a properly registered business",
        "description": "A valid legal entity was confirmed through official sources"
      }
    ],
    "actions": [],
    "metadata": {
      "query": {
        "mode": "standard",
        "name": "Apple Inc.",
        "context": null,
        "location": "California, US",
        "classification": "specific"
      },
      "from_cache": false,
      "updated_at": "2025-05-14T22:02:02.819Z",
      "resolved_at": "2025-05-14T22:02:05.343Z",
      "cache_hit_type": null
    }
  }
}