# Verification and public log

> Check a signed receipt, read signed Merkle checkpoints and proofs, and fetch the public sealing keys.

Source: https://esigncomply.com/docs/api/verification

These endpoints let anyone holding the right proof check a record without trusting your database. A verification result says whether a record still matches its seal, its ledger entry, its external timestamp and the public log. It does not establish who signed, when the person actually acted, or whether any agreement is valid.

A record ID or a hash alone reveals nothing: not that a record exists, not its documents, not its times. Verification needs the full signed receipt, or a secret key for the record's own domain. For the model behind these checks, read [verification](https://esigncomply.com/docs/concepts/verification.md) and [evidence](https://esigncomply.com/docs/concepts/evidence.md).

| Method and path | Key | Purpose |
|---|---|---|
| `POST /v1/verify` | None with a signed receipt, or a secret key | Return proof status for one record. |
| `GET /v1/log/checkpoint` | None (public) | Latest signed Merkle checkpoint, or an earlier one by tree size. |
| `GET /v1/log/proof` | None (public) | Inclusion proof for a leaf, or consistency proof between two tree sizes. |
| `GET /.well-known/jwks.json` | None (public) | Public sealing keys, current and retired. Served from the site root, not under `/v1`. |

## Verify a record

`POST /v1/verify`

Key: none when you send the full signed receipt. A secret key is needed to check a record by ID or by hash, and only for a record in that key's domain and environment. A client token is refused.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `receipt` | string | One of three | The full signed receipt (compact JWS) as returned by `complete()`, `GET /v1/records/{id}` or `GET /v1/records/{id}/receipt`. |
| `record_id` | string | One of three | A record ID. Accepted only with a secret key of the same domain. |
| `record_hash` | string | One of three | A record hash, with or without the `sha256:` prefix. Accepted only with a secret key, and it names a record only inside that key's domain and environment. |

When more than one is sent, `receipt` is used first, then `record_id`, then `record_hash`.

**Example request**

```bash
curl https://esigncomply.com/v1/verify \
  -H "Content-Type: application/json" \
  -d '{ "receipt": "eyJhbGciOiJFUzI1NiIs..." }'
```

**Example response**

`200 OK`

```json
{
  "object": "verification_result",
  "valid": true,
  "livemode": true,
  "attestation": "live",
  "status": "anchored",
  "checks": {
    "receipt_signature": "pass",
    "record_hash": "pass",
    "ledger_entry": "pass",
    "timestamp_token": "pass",
    "inclusion_proof": "pass",
    "consistency_proof": "pass"
  },
  "checked_at": "2026-11-21T18:40:01.530Z",
  "note": "This result says whether the record matches its seal. It does not establish who signed or whether any agreement is valid or enforceable."
}
```

| Field | Description |
|---|---|
| `valid` | `true` when no check failed and, if a receipt was sent, its signature verified. Checks that are `pending` or `not_applicable` do not make a result invalid. |
| `livemode` | Live or test. |
| `attestation` | `live`, or `none: test record` for test mode. A test record carries no attestation. |
| `status` | The record's status: `recorded`, `timestamped`, `anchored` or `disputed`. |
| `checks` | One result per check: `pass`, `fail`, `pending` (the step has not happened yet, for example no checkpoint) or `not_applicable` (for example no external timestamp on a test record made on the Free plan, or content erased so only the hash remains). |
| `checked_at` | When the checks ran. |

| Check | What is compared |
|---|---|
| `receipt_signature` | The receipt's ES256 signature verifies under the published key with its `kid`, the key belongs to the right environment, and the payload names this record, its hash and its ledger position. |
| `record_hash` | SHA-256 over the stored salt and canonical record equals the sealed hash. |
| `ledger_entry` | The ledger entry hash recomputes and names the record hash. |
| `timestamp_token` | The RFC 3161 token covers the record hash and its signature verifies. |
| `inclusion_proof` | The ledger entry is in the signed checkpoint. |
| `consistency_proof` | The current checkpoint only appends to the one the record is in. |

When verification cannot proceed the response is still `200 OK`, with no detail about any record:

```json
{ "object": "verification_result", "valid": false, "reason": "receipt_not_on_file" }
```

| `reason` | Meaning |
|---|---|
| `receipt_signature_invalid` | The receipt is malformed, was signed by an unknown key, or its signature does not verify. |
| `receipt_not_on_file` | The signature verifies, but this is not the receipt on file for that record, byte for byte. |
| `not_verifiable` | Nothing can be said. The same answer is given whether or not a record exists. |

Checking by ID from your own server:

```bash
curl https://esigncomply.com/v1/verify \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "record_id": "rec_Z4m8" }'
```

The response has the same shape. An unknown ID returns `valid: false` with `reason: "not_verifiable"`. Checking by hash works the same way, with `{ "record_hash": "sha256:..." }`: a hash that names no record of your domain and environment returns `valid: false` with `reason: "not_verifiable"`.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) `400`: neither a receipt nor a `record_id` or `record_hash` with a secret key was sent. A record ID or hash alone cannot be verified without a key for its domain.
- [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) `403`: a client token was used.
- [`invalid_api_key`](https://esigncomply.com/docs/api/errors.md#invalid_api_key) `401`: the key sent is not valid.

## Verify a receipt locally

You do not need this API to check a receipt. A receipt is a compact JWS with `alg: ES256` and `typ: esc-receipt+jwt`. Its payload is:

```json
{
  "iss": "https://esigncomply.com",
  "rid": "rec_Z4m8",
  "dom": "example.com",
  "hash": "sha256:5be7...",
  "iat": 1795273400,
  "lvl": "simple",
  "asr": "L1",
  "seq": 18244,
  "prev": "sha256:a91c...",
  "live": true
}
```

`rid` is the record ID, `dom` the registered domain, `hash` the record hash, `iat` the signing time, `lvl` the service classification (`simple` or `not_applicable`), `asr` the assurance level, `seq` and `prev` the ledger sequence and the previous entry hash, and `live` the environment.

Verify it against the published keys with the `jose` package:

```ts
import { compactVerify, decodeProtectedHeader, importJWK, type JWK } from "jose";

const JWKS_URL = "https://esigncomply.com/.well-known/jwks.json";

type SealingKey = JWK & { kid: string; esc_env: "live" | "test"; esc_status: "active" | "retired" };

interface ReceiptPayload {
  iss: string;
  rid: string;
  dom: string;
  hash: string;
  iat: number;
  lvl: string;
  asr: string;
  seq: number;
  prev: string;
  live: boolean;
}

export async function verifyReceipt(
  receipt: string,
  expected: { recordId: string; recordHash: string; domain: string; live: boolean },
): Promise<ReceiptPayload> {
  const res = await fetch(JWKS_URL);
  if (!res.ok) throw new Error("Could not load the sealing keys.");
  const { keys } = (await res.json()) as { keys: SealingKey[] };

  const header = decodeProtectedHeader(receipt);
  if (header.alg !== "ES256" || header.typ !== "esc-receipt+jwt") throw new Error("Not an Esign Comply receipt.");
  const jwk = keys.find((k) => k.kid === header.kid);
  if (!jwk) throw new Error("The receipt names an unknown sealing key.");

  // Throws if the signature does not verify.
  const { payload } = await compactVerify(receipt, await importJWK(jwk, "ES256"), { algorithms: ["ES256"] });
  const claims = JSON.parse(new TextDecoder().decode(payload)) as ReceiptPayload;

  // A receipt signed by a test key never verifies as live evidence.
  if (jwk.esc_env !== (claims.live ? "live" : "test")) throw new Error("Key environment does not match the receipt.");
  if (claims.live !== expected.live) throw new Error("Unexpected environment.");
  if (claims.rid !== expected.recordId) throw new Error("The receipt is for another record.");
  if (claims.hash !== expected.recordHash) throw new Error("The receipt names another record hash.");
  if (claims.dom !== expected.domain) throw new Error("The receipt is for another domain.");
  return claims;
}
```

This shows that Esign Comply signed a receipt for that record hash, on that domain, at that ledger position. To also recompute the record hash, check the timestamp token and check the inclusion proof without any network access, export the evidence package and run the [offline verifier](https://esigncomply.com/docs/sdk/verify.md). Retired keys stay published, so old receipts keep verifying.

## Get a checkpoint

`GET /v1/log/checkpoint`

Key: none. Public, cacheable for 30 seconds, readable cross-origin.

Every ledger entry (record, annotation, supplement, certificate) becomes a leaf in a per-region Merkle tree. About once a minute Esign Comply signs a checkpoint over the tree. Each checkpoint names the previous root, so entries cannot be removed, reordered or back-dated without detection. A checkpoint contains hashes only: no personal data and no record-level entries.

**Query parameters**

| Parameter | Description |
|---|---|
| `environment` | `test` reads the test log. Anything else, or omitted, reads the live log. |
| `tree_size` | Return the checkpoint that was signed at exactly this tree size, instead of the latest. |

**Example request**

```bash
curl "https://esigncomply.com/v1/log/checkpoint"
```

**Example response**

`200 OK`

```json
{
  "object": "checkpoint",
  "environment": "live",
  "id": "chk_18f2",
  "tree_size": 48130,
  "root": "3b7e...c41a",
  "prev_root": "a07d...99e2",
  "checkpoint": "eyJhbGciOiJFUzI1NiIs...",
  "kid": "esc-us-live-2026-11",
  "created_at": "2026-11-21T15:03:00.000Z"
}
```

`root` and `prev_root` are lower-case hexadecimal without a prefix. `checkpoint` is a compact JWS (`alg: ES256`, `typ: esc-checkpoint+jwt`) signed with the sealing key named in `kid`. Its payload is:

```json
{
  "iss": "https://esigncomply.com",
  "chk": "chk_18f2",
  "region": "us",
  "live": true,
  "size": 48130,
  "root": "3b7e...c41a",
  "prev_root": "a07d...99e2",
  "iat": 1795273380
}
```

**Errors**

- [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) `404`: the log has no checkpoint yet, or none was signed at that `tree_size`.

## Get a proof

`GET /v1/log/proof`

Key: none. Public. Proofs are lists of hashes and contain no personal data.

The same path serves two kinds of proof, chosen by the query parameters.

**Inclusion proof: query parameters**

| Parameter | Required | Description |
|---|---|---|
| `leaf_index` | Yes | Position of the leaf in the tree, from 0. For a record it is `seal.checkpoint.leaf_index` on the full record object. |
| `tree_size` | No | Tree size to prove against. Defaults to the latest checkpoint. Must be greater than `leaf_index` and at most the current size. |
| `environment` | No | `test` for the test log. |

**Example request**

```bash
curl "https://esigncomply.com/v1/log/proof?leaf_index=48121&tree_size=48130"
```

**Example response**

`200 OK`

```json
{
  "object": "inclusion_proof",
  "environment": "live",
  "leaf_index": 48121,
  "tree_size": 48130,
  "audit_path": ["9c1f...", "02ab...", "77e0..."],
  "root": "3b7e...c41a"
}
```

**Consistency proof: query parameters**

| Parameter | Required | Description |
|---|---|---|
| `first` | Yes | The earlier tree size. |
| `second` | No | The later tree size. Defaults to the latest checkpoint. |
| `environment` | No | `test` for the test log. |

**Example request**

```bash
curl "https://esigncomply.com/v1/log/proof?first=48130&second=51002"
```

**Example response**

`200 OK`

```json
{
  "object": "consistency_proof",
  "environment": "live",
  "first": 48130,
  "second": 51002,
  "proof": ["5d20...", "e1c4..."],
  "first_root": "3b7e...c41a",
  "second_root": "d94b...0f37"
}
```

`first_root` is `null` when `first` is 0.

**Errors**

- [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) `400`: a parameter is not a non-negative integer, `leaf_index` is outside the tree, `tree_size` or `second` is larger than the log, or `first` is larger than `second`. The error names the parameter in `param`.

### Hash rules

The tree follows the RFC 6962 construction ([RFC 6962](https://www.rfc-editor.org/rfc/rfc6962), [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162)).

- Leaf hash: `SHA-256(0x00 || entry_hash_bytes)`, where `entry_hash_bytes` are the 32 raw bytes of the ledger entry hash (`seal.entry_hash` on the record, without the `sha256:` prefix).
- Node hash: `SHA-256(0x01 || left || right)`.
- `audit_path` is ordered from the leaf to the root.

```ts
import { createHash } from "node:crypto";

const sha256 = (...parts: Uint8Array[]) => createHash("sha256").update(Buffer.concat(parts)).digest();

/** RFC 9162 section 2.1.3.2. Returns true when the audit path leads from the leaf to the root. */
export function verifyInclusion(
  entryHash: string, // "sha256:..." from seal.entry_hash
  leafIndex: number,
  treeSize: number,
  auditPath: string[], // hex
  rootHex: string,
): boolean {
  if (leafIndex >= treeSize) return false;
  let fn = leafIndex;
  let sn = treeSize - 1;
  let r = sha256(Buffer.from([0x00]), Buffer.from(entryHash.replace(/^sha256:/, ""), "hex"));
  for (const hex of auditPath) {
    const p = Buffer.from(hex, "hex");
    if (sn === 0) return false;
    if (fn % 2 === 1 || fn === sn) {
      r = sha256(Buffer.from([0x01]), p, r);
      while (fn % 2 === 0 && fn !== 0) {
        fn = Math.floor(fn / 2);
        sn = Math.floor(sn / 2);
      }
    } else {
      r = sha256(Buffer.from([0x01]), r, p);
    }
    fn = Math.floor(fn / 2);
    sn = Math.floor(sn / 2);
  }
  return sn === 0 && r.toString("hex") === rootHex;
}
```

To complete the check, verify the `checkpoint` JWS under the sealing keys and confirm that its `size` and `root` equal the `tree_size` and `root` you used.

## Get the sealing keys

`GET /.well-known/jwks.json`

Key: none. Public, cacheable for 5 minutes, readable cross-origin. This document is served from the site root (`https://esigncomply.com/.well-known/jwks.json`), not under `/v1`.

Returns every public sealing key, current and retired. No key is ever removed, so a receipt signed years ago still verifies. Evidence packages also bundle the keys valid at seal time in `keys/jwks.json`.

**Example request**

```bash
curl https://esigncomply.com/.well-known/jwks.json
```

**Example response**

`200 OK`

```json
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2...",
      "y": "x_FEzRu9...",
      "kid": "esc-us-live-2026-11",
      "use": "sig",
      "alg": "ES256",
      "esc_env": "live",
      "esc_region": "us",
      "esc_status": "active",
      "esc_created_at": "2026-11-01T00:00:00Z"
    }
  ]
}
```

| Field | Description |
|---|---|
| `kid` | Key ID. Matches the `kid` in the header of receipts and checkpoints. |
| `alg`, `kty`, `crv`, `x`, `y` | ECDSA P-256 public key for ES256. |
| `esc_env` | `live` or `test`. A receipt signed by a `test` key is never live evidence. |
| `esc_region` | `us` or `eu`. One key per region and environment. |
| `esc_status` | `active` or `retired`. Retired keys still verify what they signed. |
| `esc_created_at` | When the key was created. |

The same keys verify three kinds of token, told apart by the `typ` header: `esc-receipt+jwt` (record receipts), `esc-checkpoint+jwt` (log checkpoints) and `esc-subject-receipt+jwt` (receipts for annotations, supplements and certificates).

## What a result does and does not say

- It says that the stored record matches the hash that was sealed, that the seal was signed with a published Esign Comply key, that an outside timestamp authority saw that hash no later than the token time, and that the ledger entry is in a signed checkpoint that later checkpoints only extend.
- It does not say who acted, that the person read the documents, or when the act actually occurred. Times reported by a browser are reported, not verified. The independent timestamp bounds when the record hash existed.
- It is not a decision about whether an agreement was formed. That depends on your documents, your implementation and applicable law.
- A test record verifies with the test key and is always reported as carrying no attestation.
