Understanding API Responses

Technical guide for interpreting Entity Resolution API responses and implementing response handling logic in production systems.

This guide covers response structure, confidence thresholds, entity vs candidate handling, and practical implementation patterns for enterprise integrations.

View as .md

Response Structure

Entity Resolution responses follow this standard format:

{
  "request_id": "req_2ZUKocPbFCPLClZ5XtHlJ",
  "status": "matched",
  "confidence": 95,
  "type": "business", 
  "subtype": "incorporated_entity",
  "entity": { /* High-confidence verified data */ },
  "candidate": null,
  "factors": [ /* Decision reasoning */ ],
  "actions": [ /* Improvement suggestions */ ],
  "metadata": { /* Request context */ }
}

Core Fields

Field	Type	Description
`status`	string	Match quality: `matched`, `partial_match`, `inconclusive`, `no_match`
`confidence`	integer	Certainty score 0-100
`type`	string	Entity type e.g. `business` or `government`
`subtype`	string	Entity legal organization type e.g. `incorporated_entity` or `unincorporated_entity`
`entity`	object\|null	Entity record
`candidate`	object\|null	Best available match
`factors`	array	Decision reasoning and evidence
`actions`	array	Suggestions for improving results

Entity vs Candidate Responses

Entity Response (Confidence >= 80)

Status: matched
entity field populated, candidate is null
Verified legal entity with government identifiers
Safe for automated processing

Candidate Response (Confidence < 50 OR unsupported entity type)

Status: inconclusive
candidate field populated, entity is null
Best available match, manual review recommended
Insufficient data for verification or unsupported entity type

See Entities and Candidates for detailed explanations of when each response type is returned and the different entity types.

Entity Example (High Confidence)

{
  "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,
  "factors": [ /* Decision reasoning */ ],
  "actions": [ /* Improvement suggestions */ ],
  "metadata": { /* Request context */ }
}

Candidate Example (Lower Confidence)

{
  "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": [ /* Decision reasoning */ ],
  "actions": [ /* Improvement suggestions */ ],
  "metadata": { /* Request context */ }
}

Factors and Actions

Factors

Factors provide decision reasoning with two categories:

Strengths: Evidence supporting the match
Limitations: Concerns that reduce confidence

Sample 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": "multiple_sources_corroboration",
        "description": "Multiple authoritative sources confirm details about 'Apple' and its location.",
        "impact": "Increases confidence in the accuracy and reliability of the matched entity."
    },
    {
        "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

Specific suggestions to improve results when confidence is lower than desired.

Sample actions for "Mircon Consulting", a very generic name, with an old address provided:

"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."
    }
],

For comprehensive documentation of factor codes, action types, and implementation patterns, see Confidence and Explainability.