# Concepts

## Entities and candidates

An **entity** is a confirmed record, anchored to a government registration. A **candidate**
is our best hypothesis when we could not confirm one, either because confidence was too low
to separate two matches or because the entity type is not fully supported yet. Today
confirmed records are incorporated businesses. Sole proprietors, partnerships, governments
and funds come back as candidates. A response populates `entity` or `candidate`, never both.
`type` and `subtype` tell you what was found either way.

## Identifiers

Three ID levels, one system.

| Prefix | Level | Use |
| --- | --- | --- |
| `siq_` | Global entity | Your primary key, and the only ID `/v3/entities/{id}` accepts |
| `op_` | Operational presence | How the entity operates in one country |
| `le_` | Legal entity | One specific registration in one jurisdiction |

A global entity can have many registrations: a Delaware corporation, a UK subsidiary, and so
on. `primary_legal_entity` is the anchoring one. `le_` and `op_` IDs appear inside records
but are not lookup keys.

`siq_` IDs are stable. If two records are consolidated, the response returns
`status: "merged"` with `merged_into` set, and serves the canonical record. Store the new ID.

Entities also carry external identifiers in `identifiers[]`: registry registration IDs, LEI,
CIK and others where known. See [Codes & enums](/docs/v3/guides/codes-enums/).

## Registry-first data

Every confirmed entity is anchored to an official government registration. That anchor is
what keeps IDs stable and what separates two companies that share a name. On top of it,
research agents search
registries, directories, news and the company's own site, then attach what they find to the
registration.

## Confidence and provenance

`match_confidence` (0-100) says how certain we are that the result is the entity you asked
for. `factors[]` lists the strengths and limitations behind that score, and `actions[]`
suggests what to add when a query is ambiguous. Both use stable codes. See
[Codes & enums](/docs/v3/guides/codes-enums/).

Pass `include=basis` for per-field provenance: for each field, the confidence, the reasoning,
and citations back to the sources, each tagged with an authority tier.

## Freshness

Registry data updates on each registrar's cadence. Web-sourced enrichment refreshes
periodically. `/v3/entities/{id}` never blocks: it serves what exists now and reports the
build state in `enrichment.status`. When a record has never been enriched, the first read
starts the build in the background. Poll until `enrichment.status` is `complete`.