---
meta:
  - title: Understanding API Responses - SavvyIQ API Documentation
  - name: description
    content: Learn how to interpret SavvyIQ API responses, understand confidence scores, entity vs candidate differences, and handle factors and actions.
---
# Understanding API Responses

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

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

## Response Structure

Entity Resolution responses follow this standard format:

```json
{
  "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](/docs/concepts/entities-and-candidates) for detailed explanations of when each response type is returned and the different entity types.

### Entity Example (High Confidence)

```json
{
  "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)

```json
{
  "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":

```json
"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:

```json
"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](/docs/concepts/confidence-and-explainability).

## Next Steps

### Core Concepts
- [Entities and Candidates](/docs/concepts/entities-and-candidates) - Data model and entity types
- [Confidence and Explainability](/docs/concepts/confidence-and-explainability) - Scoring methodology and factors
- [Identifiers](/docs/concepts/identifiers) - ID system and cross-API usage

### Integration Guides  
- [Batch Processing](/docs/guides/batch-processing) - Bulk entity processing
- [Handling Messy Data](/docs/guides/handling-messy-data) - Data quality patterns