> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallychannel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity State

> How Tally models business identity as a versioned, auditable state object.

Tally models identity not as a static record but as a **durable state object** with a full, immutable version history. The goal is to separate identity state infrastructure from the verification vendors and workflow tools that feed it.

## Subjects

A **subject** is the unit of identity. Every subject is identified by two fields:

| Field          | Values                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------ |
| `subject_type` | `organization` or `individual`                                                             |
| `subject_id`   | Stable identifier within its type namespace. You assign this — Tally does not generate it. |

Subjects are tenant-scoped: a **tenant** owns a subject and controls who else can read it.

## The envelope

All identity data is stored inside an `entityStateEnvelopeV1`. The envelope has three top-level concerns:

* **`attributes`** — the identity payload. An open map: any key/value is accepted. The [canonical v1 attribute groups](#canonical-v1-attribute-groups) define the expected grouped structure for organization and individual subjects, but you can store additional attributes alongside them.
* **`evidence`** — the provenance array. Each entry records where a piece of data came from, when it was verified, and by whom.
* **`audit`** — who created this snapshot, when, and from what source.

The `attribute_paths` field optionally links specific attribute values to specific evidence entries — this is the per-field provenance model.

## Canonical v1 attribute groups

### Organization subjects (`subject_type: "organization"`)

Organization attributes are grouped under `legal`, `contact`, `jurisdiction`, and `identifiers`. `legal.legal_name` is required.

* `legal`: `legal_name`, `alternative_names`, `legal_form`, `legal_form_code`, `status`, `date_of_incorporation`
* `contact`: `email`, `phone`, `addresses.registered_office`, `addresses.principal_place_of_business`, `addresses.mailing`
* `jurisdiction`: `country_of_incorporation`, `region_of_incorporation`, `tax_residencies`
* `identifiers`: array of structured identifiers with type, value, issuer, tax, and primary flags

### Individual subjects (`subject_type: "individual"`)

Individual attributes are grouped under `biographic`, `contact`, `jurisdiction`, and `identifiers`, with `professional` reserved. `biographic.name` is required with at least one of `given_name`, `family_name`, or `formatted_name`.

* `biographic`: `name`, `sex`, `date_of_birth`, `place_of_birth`
* `contact`: `email`, `phone`, `addresses.residential`, `addresses.mailing`, `addresses.work`
* `jurisdiction`: `nationalities`, `citizenships`, `tax_residencies`
* `identifiers`: array of structured identifiers with type, value, issuer, tax, and primary flags

These fields are TypeScript contracts in `@tally/schema`. Additional attributes can be stored freely in the open `attributes` map.

## Writes

Identity state is written in two patterns:

1. **Initial creation** — `POST /v1/tenants/{tenant_id}/entity-states` creates the first snapshot (version 1) for a new subject.
2. **Updates** — subsequent changes use the propose-then-apply flow with RFC 6902 JSON Patch. See [Updates](/concepts/snapshots#updates).

No write mutates a previous snapshot. Every write creates a new version.

## No raw document storage

Tally stores structured state and provenance metadata. It does not store raw identity documents (passport images, utility bills, biometric files) in v1. Evidence providers retain custody of their own artifacts; Tally stores references and hashes only.