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

# The ledger

> Every change to an Agentic ID is an entry in an append-only, hash-linked ledger that you can re-check.

Every Agentic ID has a ledger: the ordered list of everything that happened to it. When the ID was created, which kinds of identifier were linked to it, when it was merged, when a fact changed level.

The ledger is how an answer stays traceable. You can ask at any time what happened to an ID, and whether the record is intact.

## Properties

| Property | Meaning |
| - | - |
| Append-only | Entries are added, never edited or deleted |
| Hash-linked | Each entry carries its own hash and the hash of the entry before it for the same ID. Changing an old entry breaks every link after it |
| Signed | Agentic ID keeps signed copies of the ledger in write-once storage, so a rewrite would show against the copy |
| No contact values | Entries hold IDs, kinds, levels and hashes. They never hold an email, a phone number or a name |

## Read an ID's ledger

`GET /v1/ledger/{id}` returns one ID's entries, re-checked. It is not charged. Your workspace must hold the ID.

```bash theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/ledger/ic-4kQ9xT2mB7nLp0Zr8VwYc3" \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY"
```

```json theme={null}
{
  "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3",
  "summary": "2 ledger entries (minted, fact_assessed); chain verified: every link re-checked.",
  "verified": true,
  "entries": [
    {
      "seq": 1041,
      "kind": "minted",
      "at": "2026-11-13T10:41:55.000Z",
      "hash": "9f2c6b1e0a7d4c3b8e5f1a2d6c9b0e7f4a3d2c1b0e9f8a7d6c5b4a3f2e1d0c9b",
      "prev_hash": null,
      "detail": { "kind": "company", "anchorTypes": ["domain"], "source": "input" }
    },
    {
      "seq": 1187,
      "kind": "fact_assessed",
      "at": "2026-11-14T08:03:12.000Z",
      "hash": "3b8e5f1a2d6c9b0e7f4a3d2c1b0e9f8a7d6c5b4a3f2e1d0c9b9f2c6b1e0a7d4c",
      "prev_hash": "9f2c6b1e0a7d4c3b8e5f1a2d6c9b0e7f4a3d2c1b0e9f8a7d6c5b4a3f2e1d0c9b",
      "detail": { "fact": "company_domain", "level": "verified", "from": null, "voices": 0, "reason": "domain live (probe)" }
    }
  ]
}
```

**id** `string`

The Agentic ID.

**summary** `string`

One plain line: how many entries, which kinds, and whether the chain checked out.

**verified** `boolean`

`true` when every entry passed the re-check. `false` when any entry failed.

**entries** `object[]`

The entries, oldest first.

**entry fields**

**seq** `number`

The entry's place in the whole ledger. It rises over time. Entries of one ID are not consecutive, because other IDs' entries fall in between.

**kind** `string`

What happened. See the table below.

**at** `string`

When it was written. ISO 8601.

**hash** `string`

The entry's own hash, computed from its content.

**prev\_hash** `string | null`

The hash of the previous entry for this ID. `null` on the first entry.

**detail** `object`

What the entry records. Its fields depend on `kind`.

## What "re-checked" means

The check runs every time you call the endpoint. Nothing is read from a stored result. For each entry, in order:

1. The hash is computed again from the entry's content and compared with the stored `hash`.
2. The entry's `prev_hash` is compared with the `hash` of the entry before it.

`verified` is `true` only when both hold for every entry. If any entry was changed, removed or reordered, a link fails, `verified` is `false`, and `summary` says the chain is broken.

You can repeat the link check yourself: walk `entries` in order and confirm each `prev_hash` equals the `hash` before it. The hash itself also covers encrypted content that is not returned, so only Agentic ID can recompute it.

> [!WARNING]
>
> Treat `"verified": false` as a serious signal. Do not act on that ID's record. Report it to your Agentic ID contact with the ID.

## Entry kinds

| `kind` | Written when |
| - | - |
| `minted` | The ID was created |
| `linked` | An identifier was linked to the ID |
| `unlinked` | An identifier was detached, for example because it turned out to be shared between different people |
| `conflict` | Identifiers pointed at more than one ID and were held for review |
| `merged` | Two IDs were found to be the same entity. Written on both IDs |
| `split` | A merge was undone. Written on both IDs |
| `family_linked` | A company was linked to a possibly related company, for review |
| `fact_assessed` | The level of a fact changed. See [Verification levels](https://docs-agentic-id.icustomer.ai/concepts/verification.md) |
| `consent` | A consent event, such as an opt-out |
| `erased` | The ID's data was erased on request |
| `legacy_mapped` | An identifier from an earlier ID scheme was mapped to this ID |

### What detail holds

`detail` names things by type, ID and hash. Some examples:

| `kind` | Typical `detail` fields |
| - | - |
| `minted` | `kind` (person or company), `anchorTypes` (which kinds of identifier, such as `domain` or `work_email`), `source` |
| `linked` | `anchorTypes`, `source` |
| `merged` | `survivorId` on the ID that was merged away, `mergedId` on the one that survived |
| `family_linked` | `with` (the other company's ID), `reason` |
| `fact_assessed` | `fact`, `level`, `from` (the level before), `voices`, `reason`, `recheckAt` |

An entry says that a work email was linked. It never says which address. Treat `detail` as a record to read, and do not depend on a fixed set of fields per kind.

A `fact_assessed` entry is written when a fact's shared level changes. Reports your workspace sends as [feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md) change your own view of a fact and do not add ledger entries.

## Errors

| Status | `code` | When |
| - | - | - |
| 400 | `request.invalid` | The `id` in the path is not an Agentic ID |
| 404 | `id.not_held` | Your workspace does not hold this ID. Resolve it first |

An unknown ID and an ID held only by someone else answer the same way.

## When to use it

* **Audit.** Show when an ID was created and what changed since.
* **Debug a match.** See which kinds of identifier were linked, and when a merge happened.
* **Explain a level.** A `fact_assessed` entry shows the level before and after, with the reason.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.