Understanding API responses

Response structure

{
  "request_id": "req_2ZUKocPbFCPLClZ5XtHlJ",
  "status": "matched",
  "confidence": 95,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": { /* the resolved record */ },
  "candidate": null,
  "factors": [ /* why we decided that */ ],
  "actions": [ /* how to improve the query */ ],
  "metadata": { /* request context */ }
}

Field	Type	Description
status	string	Outcome: matched, partial_match, inconclusive, no_match, not_found
confidence	integer	0-100
type	string	Entity type, e.g. business or government
subtype	string	Legal structure, e.g. incorporated_entity or unincorporated_entity
entity	object|null	The resolved record
candidate	object|null	Best available hypothesis
factors	array	Decision reasoning and evidence
actions	array	Suggestions for improving results

Entity or candidate

entity and candidate are never both populated, and both are null when nothing matched. Branch on which one is non-null. Do not branch on confidence.

status	Populated
matched, confidence 80 or above	entity
partial_match, resolved to a known business with confidence below 80	entity
inconclusive, no record could be committed	candidate, if we formed one
no_match, research finished and found nothing	neither
not_found, research did not complete	neither

partial_match returns a full entity below 80, so a confidence >= 80 test silently discards valid records. Handle the neither-present case too. That is how “we found nothing” is represented.

no_match and not_found differ. no_match is an answer. not_found means the research did not finish, so it is worth retrying rather than recording as a negative result, and it also returns type and subtype as null. It appears on the streaming endpoint; the async endpoint reports the same condition as a FAILED job on the status route.

An entity has a stable id you can reuse. A candidate has no id at all. See Entities and candidates.

Entity example

{
  "status": "matched",
  "confidence": 95,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": {
    "id": "siq_2ZUKocPbFCPLClZ5XtHlJ",
    "name": "Apple",
    "status": "active",
    "website": "apple.com",
    "headquarters": {
      "city": "Cupertino",
      "state": "California",
      "country": "United States"
    },
    "primary_legal_entity": {
      "id": "le_2ZoRp6I3EUgebkUBHaDdk",
      "name": "APPLE INC.",
      "jurisdiction": "California"
    }
  },
  "candidate": null
}

Candidate example

{
  "status": "inconclusive",
  "confidence": 40,
  "type": "business",
  "subtype": "trading_name_only",
  "entity": null,
  "candidate": {
    "name": "Local Coffee Shop",
    "legal_name": null,
    "jurisdiction": "US-CA",
    "primary_address": {
      "full_address": "123 Main St, Anytown, CA 94000",
      "state_code": "CA",
      "country_code": "US"
    }
  }
}

Factors

Each factor is a strength (evidence supporting the match) or a limitation (a concern that reduced confidence). Factors for Apple in cupertino, california, usa:

"factors": [
    {
        "type": "strength",
        "code": "name_exact_match",
        "description": "The provided name 'Apple' exactly matches the legal entity name 'Apple'",
        "impact": "Strong identifier for the correct entity."
    },
    {
        "type": "strength",
        "code": "jurisdiction_match",
        "description": "The entity's jurisdiction (California) matches the query's location (Cupertino, California).",
        "impact": "Confirms the entity operates within the specified jurisdiction."
    },
    {
        "type": "strength",
        "code": "headquarters_match",
        "description": "The provided location 'Cupertino, California' matches the entity's registered headquarters.",
        "impact": "Confirms this is the primary legal entity location"
    },
    {
        "type": "strength",
        "code": "legal_entity_confirmed",
        "description": "A valid legal entity was confirmed through official sources.",
        "impact": "Verifies the legal existence and status of the matched entity."
    }
],

Actions

What to change about the query when confidence is lower than you need. Actions for Mircon Consulting, a generic name given with an outdated address:

"actions": [
    {
        "code": "provide_full_legal_name",
        "description": "Use the complete legal name, including any legal suffixes (e.g., Inc., Ltd., Corp.)"
    },
    {
        "code": "verify_address_details",
        "description": "Double-check the accuracy of the address, including street number, street name, city, and postal code."
    },
    {
        "code": "check_entity_status",
        "description": "Confirm whether the entity is currently active. If it is inactive, provide information about when it was active if available."
    }
],

Factor and action codes are listed in Confidence scoring.