Understanding API responses

Response structure

The result of GET /v3/runs/{run_id}:

{
  "run_id": "run_344tSxhAVACWbuENINJ9D",
  "status": "matched",
  "match_confidence": 100,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": { /* the resolved record */ },
  "candidate": null,
  "factors": [ /* why we decided that */ ],
  "actions": [ /* how to improve the query */ ],
  "basis": [ /* per-field citations, with include=basis */ ],
  "metadata": { /* request context */ }
}

Field	Type	Description
status	string	Outcome: matched, partial_match, inconclusive, no_match, not_found
match_confidence	integer	0-100. How certain we are the result is the entity you asked for
type	string	Entity type, e.g. business or government
subtype	string	Legal structure, e.g. incorporated_entity or trading_name_only
entity	object|null	The resolved record, anchored to a government registration
candidate	object|null	Best available hypothesis when no record could be committed
factors	array	Decision reasoning and evidence, with stable codes
actions	array	What to add to the query to sharpen it
basis	array	Per-field provenance, only when you passed include=basis on the poll

On GET /v3/domain-intelligence the same block sits under data, the score is named confidence, and the domain’s own intelligence sits beside it under data.domain_intelligence.

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 match_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 match_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 returns type and subtype as null.

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

Entity example

{
  "status": "matched",
  "match_confidence": 100,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": {
    "id": "siq_33d67jj0wJESjEdFHMhuQ",
    "display_name": "Datadog",
    "legal_name": "DATADOG, INC.",
    "status": "active",
    "website": "https://www.datadoghq.com/",
    "headquarters": { "address": { "city": "New York", "state_code": "NY", "country_code": "US" } },
    "primary_legal_entity": { "id": "le_2Zp3Yy6S7O6Btccq56WOH", "jurisdiction": "US-DE" },
    "identifiers": [ { "type": "registration_id", "value": "4832851", "jurisdiction": "US-DE" } ]
  },
  "candidate": null
}

Candidate example

{
  "status": "inconclusive",
  "match_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 Datadog in New York, NY, from the reference capture:

"factors": [
  {
    "code": "name_exact_match",
    "type": "strength",
    "impact": "Strong identifier for the correct entity.",
    "description": "The name 'Datadog' provided in the query exactly matches the entity's common name."
  },
  {
    "code": "headquarters_match",
    "type": "strength",
    "impact": "Confirms this is the primary legal entity location.",
    "description": "The requested location 'New York, NY' precisely matches the entity's registered headquarters."
  },
  {
    "code": "legal_entity_confirmed",
    "type": "strength",
    "impact": "Confirms a valid legal entity through official sources.",
    "description": "This has been definitively confirmed as the primary legal entity through official registration sources."
  },
  {
    "code": "registry_identifier_anchored",
    "type": "strength",
    "impact": "Safe to use for deterministic record matching and deduplication.",
    "description": "The match is anchored by a stable government registry identifier."
  }
]

Actions

What to change about the query when confidence is lower than you need. A generic name given without a location typically returns:

"actions": [
  { "code": "add_location", "description": "Provide a city, state or country to narrow the search." },
  { "code": "provide_full_legal_name", "description": "Use the complete legal name, including any legal suffixes (e.g., Inc., Ltd., Corp.)" }
]

Basis

With include=basis, each served field lists the citations it was built from. Every citation carries a source_type and an authority_tier (1 government registry, 2 public profile, 3 company website or web).

"basis": [
  {
    "field": "description",
    "citations": [
      {
        "url": "https://datadoghq.com",
        "excerpt": "Datadog, Inc. provides software solutions. The Company offers cloud-based monitoring and analytics platform ...",
        "source_type": "public_profile",
        "authority_tier": 2
      }
    ]
  }
]

Every status, type, factor, action and source code is listed in Codes & enums.