Snapshot Read API: Query Identity History

The Snapshot Read API lets you query the identity history Tally has built up through submitted entity state envelopes. Every endpoint operates on a subject — an entity or individual identified by subject_type and subject_id — and returns snapshots in the shape written to Tally, optionally enriched with cryptographic verification data. All read endpoints are available in both global (/v1/subjects/…) and tenant-scoped (/v1/tenants/:tenant_id/subjects/…) forms; the tenant-scoped variants require authentication and enforce subject ownership or grant-based access.

View and verify modes

Most endpoints accept view and verify query parameters that control how much data is returned and whether Tally runs integrity checks inline.

`view` parameter

Value	Behavior
`full` (default)	Returns the full snapshot including the complete `envelope` JSON.
`header`	Returns only the snapshot header: `snapshot_id`, `snapshot_version`, `subject`, `generated_at`, and `created_at`. Faster and lighter for list operations.

`verify` parameter

Value	Behavior
`none` (default)	No verification. Response omits the `verification` field.
`hash`	Tally recomputes the SHA-256 envelope hash and compares it against the stored value. Adds a `verification.hash` object to the response.
`chain`	Tally verifies the chain linkage by checking that `prev_hash` matches the parent snapshot’s stored `envelope_hash`. Adds a `verification.chain` object. Use `depth` to walk further back in the chain.

verify=hash forces view=full internally so the envelope bytes are available for hashing, regardless of the view parameter you pass.

GET /v1/subjects/:subject_type/:subject_id

Returns a structured current state summary for a subject: the latest snapshot header, a flattened identity attribute map, and provenance metadata.

GET /v1/subjects/:subject_type/:subject_id
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id

Path parameters

subject_type

string

required

Must be "entity" or "individual".

subject_id

string

required

The stable identifier for the subject, e.g. "ent_acme_001".

Query parameters

verify

string

default:"none"

Verification mode: none, hash, or chain. See the table above.

depth

integer

default:"1"

Number of chain hops to walk back when verify=chain. Must be an integer ≥ 1. Bounded by the server’s MAX_CHAIN_PROOF_DEPTH setting.

Response

subject

object

The subject identifier: subject_type and subject_id.

current_snapshot

object

Summary of the latest snapshot.

Show current_snapshot fields

snapshot_id

string

UUID of the snapshot.

snapshot_version

integer

Version number.

generated_at

string

RFC 3339 generation timestamp.

hash

string | null

The stored envelope_hash, or null if not yet computed.

prev_hash

string | null

The hash of the preceding snapshot’s envelope, forming the chain link.

identity

object

The materialized attributes object from the latest snapshot — a direct copy of envelope.attributes.

provenance

object

High-level provenance indicators.

Show provenance fields

evidence_count

integer

Number of evidence items in the latest snapshot.

has_attribute_paths

boolean

Whether the snapshot includes an attribute_paths attribution map.

has_audit

boolean

Whether the snapshot includes a non-null audit object.

verification

object

Present only when verify is not "none". Contains mode, hash, and chain sub-objects reflecting the result of the requested check.

Example

curl https://api.tally.io/v1/subjects/entity/ent_acme_001

{
  "subject": {
    "subject_type": "entity",
    "subject_id": "ent_acme_001"
  },
  "current_snapshot": {
    "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
    "snapshot_version": 3,
    "generated_at": "2026-02-20T14:25:30Z",
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "prev_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
  },
  "identity": {
    "legal_name": "Acme Industrial Supply, Inc.",
    "trade_names": ["Acme Supply"],
    "jurisdiction": "US-DE",
    "incorporation_date": "2008-05-12",
    "status": "active",
    "registered_address": {
      "line1": "1200 Market St",
      "city": "Wilmington",
      "region": "DE",
      "postal_code": "19801",
      "country": "US"
    }
  },
  "provenance": {
    "evidence_count": 2,
    "has_attribute_paths": true,
    "has_audit": true
  }
}

GET /v1/subjects/:subject_type/:subject_id/snapshots/latest

Returns the latest snapshot for a subject in header or full view, with optional verification.

GET /v1/subjects/:subject_type/:subject_id/snapshots/latest
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/snapshots/latest

Path parameters

subject_type

string

required

"entity" or "individual".

subject_id

string

required

The subject’s stable identifier.

Query parameters

view

string

default:"full"

"full" or "header".

verify

string

default:"none"

"none", "hash", or "chain".

depth

integer

default:"1"

Chain proof depth. Only meaningful when verify=chain.

Response

Returns the snapshot object. In full view, the response includes snapshot_id, snapshot_version, subject, generated_at, created_at, and envelope (the full stored envelope JSON). In header view, envelope is omitted.

{
  "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
  "snapshot_version": 3,
  "subject": {
    "subject_type": "entity",
    "subject_id": "ent_acme_001"
  },
  "generated_at": "2026-02-20T14:25:30Z",
  "created_at": "2026-02-20T14:25:31.042Z",
  "envelope": {
    "envelope_version": "entity_state_envelope_v1",
    "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
    "snapshot_version": 3,
    "generated_at": "2026-02-20T14:25:30Z",
    "subject": { "subject_type": "entity", "subject_id": "ent_acme_001" },
    "attributes": { "legal_name": "Acme Industrial Supply, Inc." },
    "evidence": [],
    "audit": {
      "created_by": "kyc_service",
      "created_at": "2026-02-20T14:25:30Z",
      "source": "tally_ingest"
    }
  }
}

GET /v1/subjects/:subject_type/:subject_id/snapshots/:snapshot_version

Returns a specific historical snapshot by its integer version number.

GET /v1/subjects/:subject_type/:subject_id/snapshots/:snapshot_version
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/snapshots/:snapshot_version

Path parameters

subject_type

string

required

"entity" or "individual".

subject_id

string

required

The subject’s stable identifier.

snapshot_version

integer

required

The integer version to retrieve. Must be ≥ 1.

Query parameters

view

string

default:"full"

"full" or "header".

verify

string

default:"none"

"none", "hash", or "chain".

depth

integer

default:"1"

Chain proof depth. Only meaningful when verify=chain.

Response

Same shape as /snapshots/latest. Returns 404 not_found if no snapshot exists for the requested version.

curl https://api.tally.io/v1/subjects/entity/ent_acme_001/snapshots/2

GET /v1/snapshots/:snapshot_id

Fetch any snapshot by its UUID, regardless of which subject it belongs to.

GET /v1/snapshots/:snapshot_id
GET /v1/tenants/:tenant_id/snapshots/:snapshot_id

Path parameters

snapshot_id

string

required

The UUID of the snapshot. Must be a valid UUID; Tally returns 400 validation_error for malformed values.

Query parameters

view

string

default:"full"

"full" or "header".

verify

string

default:"none"

"none", "hash", or "chain".

depth

integer

default:"1"

Chain proof depth. Only meaningful when verify=chain.

Response

Same shape as /snapshots/latest. On the tenant-scoped path, Tally verifies that the authenticated principal has ownership of or a grant over the subject before returning the snapshot.

GET /v1/snapshots/:snapshot_id/proof

Returns the cryptographic proof record for a single snapshot: its stored envelope hash, the hash of its predecessor, and the algorithm and canonicalization method used.

GET /v1/snapshots/:snapshot_id/proof
GET /v1/tenants/:tenant_id/snapshots/:snapshot_id/proof

Path parameters

snapshot_id

string

required

UUID of the snapshot whose proof you want to inspect.

Response

snapshot_id

string

UUID of this snapshot.

subject_id

string

The subject’s stable identifier.

snapshot_version

integer

The integer version of this snapshot.

envelope_hash

string | null

SHA-256 hash of the canonicalized envelope. null if not yet computed.

prev_hash

string | null

The envelope_hash of the immediately preceding snapshot for this subject. null for version 1.

canonicalization_method

string

The algorithm used to normalize the envelope before hashing (e.g. "json-canonicalize-rfc8785").

hash_algorithm

string

The hashing algorithm (e.g. "sha-256").

Example

curl https://api.tally.io/v1/snapshots/3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2/proof

{
  "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
  "subject_id": "ent_acme_001",
  "snapshot_version": 3,
  "envelope_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "prev_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "canonicalization_method": "json-canonicalize-rfc8785",
  "hash_algorithm": "sha-256"
}

GET /v1/subjects/:subject_type/:subject_id/history

Lists snapshots for a subject in paginated, cursor-based pages. Equivalent to /snapshots on the same subject path.

GET /v1/subjects/:subject_type/:subject_id/history
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/history

Path parameters

subject_type

string

required

"entity" or "individual".

subject_id

string

required

The subject’s stable identifier.

Query parameters

limit

integer

default:"50"

Number of snapshots to return per page. Must be between 1 and 200. Also bounded by the server’s MAX_HISTORY_LIMIT setting.

order

string

default:"desc"

Sort order by snapshot_version: "asc" (oldest first) or "desc" (newest first).

cursor

string

Opaque pagination cursor returned in the previous page’s page.next_cursor. Omit on the first request.

view

string

default:"full"

"full" or "header".

verify

string

default:"none"

"none", "hash", or "chain". Applied to each item in the page independently.

Response

items

array

Array of snapshot objects (header or full, depending on view).

page

object

Pagination metadata.

Show page fields

order

string

The order used for this page.

limit

integer

The effective page size.

next_cursor

string | null

null when you have reached the last page.

Example

curl "https://api.tally.io/v1/subjects/entity/ent_acme_001/history?limit=2&order=desc&view=header"

{
  "items": [
    {
      "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
      "snapshot_version": 3,
      "subject": { "subject_type": "entity", "subject_id": "ent_acme_001" },
      "generated_at": "2026-02-20T14:25:30Z",
      "created_at": "2026-02-20T14:25:31.042Z"
    },
    {
      "snapshot_id": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
      "snapshot_version": 2,
      "subject": { "subject_type": "entity", "subject_id": "ent_acme_001" },
      "generated_at": "2026-01-15T09:00:00Z",
      "created_at": "2026-01-15T09:00:01.300Z"
    }
  ],
  "page": {
    "order": "desc",
    "limit": 2,
    "next_cursor": "eyJzdiI6MSwic2lkIjoiYWJjZGVmMTIzNDU2In0"
  }
}

GET /v1/subjects/:subject_type/:subject_id/chain-proof

Returns the chain proof record for each snapshot in a subject’s history — a lightweight list of (snapshot_version, snapshot_id, envelope_hash, prev_hash) tuples you can use to independently verify the full chain without downloading every envelope.

GET /v1/subjects/:subject_type/:subject_id/chain-proof
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/chain-proof

Path parameters

subject_type

string

required

"entity" or "individual".

subject_id

string

required

The subject’s stable identifier.

Query parameters

limit

integer

default:"50"

Number of chain proof items per page. Bounded by the server’s MAX_CHAIN_PROOF_DEPTH setting.

order

string

default:"desc"

"asc" or "desc".

cursor

string

Pagination cursor from a previous page.

Response

items

array

Array of chain proof items. Each item contains snapshot_version, snapshot_id, envelope_hash, and prev_hash.

page

object

Pagination metadata: order, limit, next_cursor.

Example

curl "https://api.tally.io/v1/subjects/entity/ent_acme_001/chain-proof?order=asc"

{
  "items": [
    {
      "snapshot_version": 1,
      "snapshot_id": "a0b1c2d3-e4f5-6789-abcd-000000000001",
      "envelope_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "prev_hash": null
    },
    {
      "snapshot_version": 2,
      "snapshot_id": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
      "envelope_hash": "b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1",
      "prev_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
    },
    {
      "snapshot_version": 3,
      "snapshot_id": "3f0b2c2c-2e46-4b58-8c45-3b5c58f4e9b2",
      "envelope_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "prev_hash": "b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1"
    }
  ],
  "page": {
    "order": "asc",
    "limit": 50,
    "next_cursor": null
  }
}

GET /v1/subjects/:subject_type/:subject_id/export

Downloads the complete snapshot history for a subject in a single response, including every envelope and its hash data. Designed for audits, migrations, and offline verification.

GET /v1/subjects/:subject_type/:subject_id/export
GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/export

Path parameters

subject_type

string

required

"entity" or "individual".

subject_id

string

required

The subject’s stable identifier.

Export is limited by the server’s MAX_EXPORT_SIZE (default: 1000 snapshots). If a subject has more snapshots than this limit, Tally returns 400 validation_error. Use the paginated /history endpoint to retrieve large histories incrementally.

Response

subject

object

The subject identifier: subject_type and subject_id.

canonicalization_method

string

The canonicalization algorithm used when computing envelope_hash values (e.g. "json-canonicalize-rfc8785").

hash_algorithm

string

The hash algorithm (e.g. "sha-256").

snapshots

array

Ordered array of all snapshots. Each item includes snapshot_version, snapshot_id, envelope (full JSON), envelope_hash, and prev_hash.

Example

curl https://api.tally.io/v1/subjects/individual/ind_jordan_lee_99/export

{
  "subject": {
    "subject_type": "individual",
    "subject_id": "ind_jordan_lee_99"
  },
  "canonicalization_method": "json-canonicalize-rfc8785",
  "hash_algorithm": "sha-256",
  "snapshots": [
    {
      "snapshot_version": 1,
      "snapshot_id": "a0b1c2d3-e4f5-6789-abcd-000000000011",
      "envelope": {
        "envelope_version": "entity_state_envelope_v1",
        "snapshot_id": "a0b1c2d3-e4f5-6789-abcd-000000000011",
        "snapshot_version": 1,
        "generated_at": "2026-01-10T08:00:00Z",
        "subject": { "subject_type": "individual", "subject_id": "ind_jordan_lee_99" },
        "attributes": { "full_name": "Jordan Lee" },
        "evidence": [],
        "audit": {
          "created_by": "kyc_service",
          "created_at": "2026-01-10T08:00:00Z",
          "source": "tally_ingest"
        }
      },
      "envelope_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "prev_hash": null
    },
    {
      "snapshot_version": 2,
      "snapshot_id": "9a33c76e-0b08-4e90-b3fb-5e0f8f6c9a1d",
      "envelope": {
        "envelope_version": "entity_state_envelope_v1",
        "snapshot_id": "9a33c76e-0b08-4e90-b3fb-5e0f8f6c9a1d",
        "snapshot_version": 2,
        "generated_at": "2026-02-20T15:05:10Z",
        "subject": { "subject_type": "individual", "subject_id": "ind_jordan_lee_99" },
        "attributes": {
          "full_name": "Jordan Lee",
          "date_of_birth": "1987-11-04",
          "nationality": "US"
        },
        "evidence": [],
        "audit": {
          "created_by": "kyc_service",
          "created_at": "2026-02-20T15:05:10Z",
          "source": "tally_ingest"
        }
      },
      "envelope_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b856",
      "prev_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
    }
  ]
}

​View and verify modes

​view parameter

​verify parameter

​GET /v1/subjects/:subject_type/:subject_id

​Path parameters

​Query parameters

​Response

​Example

​GET /v1/subjects/:subject_type/:subject_id/snapshots/latest

​Path parameters

​Query parameters

​Response

​GET /v1/subjects/:subject_type/:subject_id/snapshots/:snapshot_version

​Path parameters

​Query parameters

​Response

​GET /v1/snapshots/:snapshot_id

​Path parameters

​Query parameters

​Response

​GET /v1/snapshots/:snapshot_id/proof

​Path parameters

​Response

​Example

​GET /v1/subjects/:subject_type/:subject_id/history

​Path parameters

​Query parameters

​Response

​Example

​GET /v1/subjects/:subject_type/:subject_id/chain-proof

​Path parameters

​Query parameters

​Response

​Example

​GET /v1/subjects/:subject_type/:subject_id/export

​Path parameters

​Response

​Example

View and verify modes

`view` parameter

`verify` parameter

GET /v1/subjects/:subject_type/:subject_id

Path parameters

Query parameters

Response

Example

GET /v1/subjects/:subject_type/:subject_id/snapshots/latest

Path parameters

Query parameters

Response

GET /v1/subjects/:subject_type/:subject_id/snapshots/:snapshot_version

Path parameters

Query parameters

Response

GET /v1/snapshots/:snapshot_id

Path parameters

Query parameters

Response

GET /v1/snapshots/:snapshot_id/proof

Path parameters

Response

Example

GET /v1/subjects/:subject_type/:subject_id/history

Path parameters

Query parameters

Response

Example

GET /v1/subjects/:subject_type/:subject_id/chain-proof

Path parameters

Query parameters

Response

Example

GET /v1/subjects/:subject_type/:subject_id/export

Path parameters

Response

Example