Identity State

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: 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 field lists define the expected fields for entity 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 fields

​

Entity subjects (subject_type: "entity")

legal_name, entity_kind (always "organization"), legal_form, legal_form_code, formation_jurisdiction_code, registry_identifier, formation_date, registered_address, entity_status, lei, tax_identifier, website

​

Individual subjects (subject_type: "individual")

name (first_name, middle_name, last_name, name_suffix), birth_date, nationalities, residential_address, tax_identifier, email, phone 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.

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.