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 status and results of async deep research. Poll every 5-10 seconds until status is "COMPLETED".

Path parameters

request_idstring required
ID of the resolution request

Responses

200 Successful response

request_idstring required
statusstring (enum) required
PENDINGCOMPLETEDFAILED
dataobject required
Response for entity resolution requests.

Important Notes:
- Either the entity or the candidate field will be populated, but never both.
- The entity field is present when we have high confidence and have created a record in our system.
- The candidate field is present when we have low confidence or the entity type is not fully supported yet.
- Initially, only entities with type "business" and subtype "incorporated_entity" will be returned as entity objects.
- The schema of the entity field may vary based on the type and subtype fields as support for different entity types is added.
Show 10 nested fieldsHide nested fields
- request_idstring
  The request ID for this API call
- statusstring (enum)
  matchedpartial_matchinconclusiveno_match
  Status of the resolution:
  
  matched - High confidence match found (entity field will be populated)
  
  partial_match - Lower confidence match (candidate field will be populated)
  
  inconclusive - Multiple possible matches (candidate field may be populated with best guess)
  
  no_match - No matches found
- 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
  updated_atstring <date-time>
  resolved_atstring <date-time>
  cache_hit_typestring

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.

500 Internal Server Error

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

502 Request timeout

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