# Entities and candidates

Every resolution response carries an entity or a candidate. Which one you get, and what it means for your integration.

Every entity resolution response carries both an `entity` and a `candidate` key. Exactly one of them is populated, or neither if nothing matched.

## Entities

A record in the SavvyIQ graph, anchored to a government registration. It has an `id` (`siq_…`) that stays stable and works across every API: pass it to [`/v3/entities/{id}`](/docs/apis/business-intelligence) for the full record, or to [Entity Hierarchy](/docs/apis/entity-hierarchy) for ownership.

## Candidates

The best hypothesis we could form for a query that did not resolve to a record.

A candidate carries descriptive fields like `name`, `legal_name`, `jurisdiction`, `status`, `description` and `primary_address`, but **no `id`**. It cannot be enriched, referenced later, or passed to another endpoint, and resolving the same query again may return a different one.

You get a candidate when the match is too weak to commit to a record, or when the entity type is one we do not create records for. `factors[]` tells you which. Look for a `limitation` entry.

## Which one you get

| `status` | Meaning | Populated |
|---|---|---|
| `matched` | Confidence 80 or above | `entity` |
| `partial_match` | Resolved to a known business, confidence below 80 | `entity` |
| `inconclusive` | Too weak to commit, or a type we do not record | `candidate`, if we formed one |
| `no_match` | Research finished and found nothing | neither |
| `not_found` | Research did not complete | neither |

Branch on which key is non-null, not on `match_confidence`. A `partial_match` returns a full entity below 80.

`no_match` and `not_found` are not the same outcome. `no_match` is an answer: we researched the query and there was nothing to return. `not_found` means the research itself did not finish, so the query is worth retrying. On `not_found`, `type` and `subtype` are `null` as well, so guard for that before reading them.

## Type and subtype

`type` and `subtype` sit at the top level of the response, beside `entity` and `candidate`. They are not inside the entity object.

```json
{
  "status": "matched",
  "match_confidence": 100,
  "type": "business",
  "subtype": "incorporated_entity",
  "entity": { "id": "siq_33d67jj0wJESjEdFHMhuQ", "display_name": "Datadog", "legal_name": "DATADOG, INC." },
  "candidate": null
}
```

On `GET /v3/entities/{id}` the same two fields live inside the record instead.

| `type` | |
|---|---|
| `business` | Commercial entities |
| `nonprofit` | Nonprofit organizations |
| `government` | Agencies and departments at national, state and local level. Not international organizations |
| `person` | An individual, including sole proprietors |
| `other` | Trusts, funds, international organizations, other specialized structures |
| `unknown` | Could not determine |

| `subtype` | |
|---|---|
| `incorporated_entity` | A separate legal entity such as a corporation or LLC |
| `unincorporated_entity` | Partnerships, sole proprietorships |
| `nonprofit_entity` | A nonprofit organization |
| `government_entity` | Government agencies and departments |
| `natural_person` | An individual, not a business entity |
| `complex_business_structure` | SPVs, joint ventures, professional corporations, mixed legal characteristics |
| `trading_name_only` | A DBA or trade name with no associated legal entity |
| `other_entity` | International organizations, trusts, funds |
| `unknown` | Could not determine |

## Coverage

Entity records today are almost entirely incorporated businesses: corporations, LLCs, and their equivalents in other jurisdictions. That focus is deliberate. It is the population we can resolve with the most confidence, so it is where we built coverage first.

The other organization types are still researched and classified, and you will see them in `type` and `subtype`. Most of them come back as candidates rather than records, and government entities always do, carrying `unsupported_entity_type` in `factors[]`. Broader type coverage is close behind.