Skip to main content
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 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.
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.