# Verification

> How to check that a record matches its seal with the public page, the signer view, the verify endpoint, the offline verifier and the public log.

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

Verification answers two questions about a record: does the stored record still match the hash Esign Comply sealed, and what do parties other than Esign Comply and you say about when that hash existed. Anyone who holds an authorized export can run the checks without an account and without trusting Esign Comply's servers.

## What verification does not establish

A passing verification shows that the record matches its seal and bounds when it existed. It does not establish who signed, that the signer read the documents, when the person actually acted, or whether any agreement is valid or enforceable. Material under `customer_supplied/` was supplied by the customer: the seal shows it was sent no later than the time shown, not that its content is true.

Verification also needs proof. A record ID or a hash alone reveals nothing: not that a record exists, not its documents, timestamps or annotations.

## Channels

| Channel | Who | What it does |
|---|---|---|
| Public page, `https://esigncomply.com/verify/rec_Z4m8` | The holder of an export, or an eligible signed-in user | A generic entry point. It checks exported proofs locally in the browser without disclosing record metadata. |
| Signer view | The signer, following the link in the receipt email | After a one-time code, shows the full record and the executed copy, with "Download" and "This was not me" |
| `POST /v1/verify` | The holder of the full signed receipt, or a caller with an API key for the record's domain | Returns proof status only |
| Offline verifier, `esigncomply-verify` | Anyone with an evidence package | Recomputes every check with public keys only. Needs no network access. |
| Public log, `GET /v1/log/checkpoint` and `GET /v1/log/proof` | Anyone | Signed Merkle checkpoints and proofs. Hashes only. |
| Document check | Anyone with a file | Hashes the file locally in the browser and compares it with the record's content hash. The file is not uploaded. |

### Signer view and disputes

The receipt email Esign Comply sends to the signer links to the signer view. After a one-time code the signer sees their own record and can download the executed copy. "This was not me" adds a `disputed` annotation, sends `record.disputed` to you, and shows the dispute on the evidence report. Esign Comply does not adjudicate disputes. Supplements are never shown in the signer view.

## Verify a receipt with the API

Send the full signed receipt. No API key is needed.

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

```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 | Meaning |
|---|---|
| `valid` | `true` when no check failed and the receipt signature is valid |
| `attestation` | `live`, or `none: test record` for a test receipt |
| `status` | The record's status: `recorded`, `timestamped`, `anchored` or `disputed` |
| `checks.*` | `pass`, `fail`, `pending` (the step has not happened yet) or `not_applicable` |

A check that is `pending` does not make the result invalid. A record that is only `recorded` has `timestamp_token` and `inclusion_proof` pending.

When the receipt cannot be verified the response is still `200`, with a reason and no record data:

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

| `reason` | Meaning |
|---|---|
| `receipt_signature_invalid` | The JWS does not verify under Esign Comply's sealing keys |
| `receipt_not_on_file` | The signature is valid, and the receipt is not the one on file for that record, byte for byte |
| `not_verifiable` | Nothing can be said about this input |

A caller with a secret key may instead send `{ "record_id": "rec_Z4m8" }` to check a record in its own domain and environment. Without a key, a record ID alone returns `400 invalid_request`. With the server SDK: `esc.verify(receipt)`. See the [Verification API](https://esigncomply.com/docs/api/verification.md).

For your own access decisions, do not use `POST /v1/verify`. Confirm the record with `GET /v1/records/{id}` or the `record.completed` webhook. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md).

## Offline verifier

`esigncomply-verify` is an open-source command-line tool and library. It reads an evidence package and repeats every check with the public keys. Nothing is fetched unless you pass an `https` URL to `--jwks`.

```bash
# Download the package (the response holds a short-lived signed URL)
curl -s https://esigncomply.com/v1/records/rec_Z4m8/evidence \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" | jq -r .url | xargs curl -s -o rec_Z4m8.zip

# Verify with the keys bundled in the package
npx esigncomply-verify rec_Z4m8.zip

# Verify against the published keys and your own timestamp trust anchors
npx esigncomply-verify rec_Z4m8.zip \
  --jwks https://esigncomply.com/.well-known/jwks.json \
  --tsa-roots roots.pem
```

| Option | Effect |
|---|---|
| `--jwks <file or https URL>` | Check signatures against these sealing keys instead of the keys inside the package. Use a source you trust to rule out re-signing. |
| `--tsa-roots <pem file>` | Trust anchors for the timestamp authority. Without it the token's certificate chain is reported as skipped, not passed. |
| `--evidence <zip or directory>` | With a certificate: the evidence package of a record it covers |
| `--json` | Print the report as JSON |

Exit code `0` means every required check passed and no check failed. `1` means verification failed. `2` means the command could not run. The report ends with `Result: VERIFIED`, `Result: VERIFIED (TEST: no attestation)` or `Result: NOT VERIFIED (...)`. A test-mode package verifies with the test key and is always reported as a test.

To check an on-request certificate, pass its JSON form and the evidence package of a record it covers:

```bash
npx esigncomply-verify certificate.json --evidence rec_Z4m8.zip
```

The verifier checks the certificate's own receipt and ledger entry, then repeats the record checks. See [esigncomply-verify](https://esigncomply.com/docs/sdk/verify.md) for the library API.

## Public log

Every ledger entry becomes a leaf in a per-region Merkle tree. A signed checkpoint is produced each minute and names the previous root, so entries cannot be removed, reordered or back-dated without detection. The log endpoints are public and return hashes only.

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

```json
{
  "object": "checkpoint",
  "environment": "live",
  "id": "chk_18f2",
  "tree_size": 48130,
  "root": "6a1f...",
  "prev_root": "0c7e...",
  "checkpoint": "eyJhbGciOiJFUzI1NiIs...",
  "kid": "esc-us-live-2026-11",
  "created_at": "2026-11-21T15:03:00.000Z"
}
```

| Request | Returns |
|---|---|
| `GET /v1/log/checkpoint` | The latest signed checkpoint. `?tree_size=` reads an earlier one. `?environment=test` reads the test log. |
| `GET /v1/log/proof?leaf_index=48121&tree_size=48130` | An inclusion proof: `audit_path` and `root` for one leaf |
| `GET /v1/log/proof?first=48130&second=52004` | A consistency proof that the larger tree only appends to the smaller one |

Compare the checkpoint inside a package with the public log to confirm that Esign Comply's log still extends the tree the record was sealed in.

## Package format summary

The evidence package is a ZIP file. All JSON files are UTF-8. Hashes are SHA-256 in lower-case hexadecimal with the prefix `sha256:`. The normative description ships with the verifier as `FORMAT.md`. This is a summary.

### Files

| Path | Required | Content |
|---|---|---|
| `manifest.json` | Yes | `format: "esc-evidence-package"`, `version: 1`, record ID, and the path, hash and size of every other file |
| `record.json` | Yes, unless the content was erased or purged | The canonical record (`schema: "esc-record-v1"`): exactly the bytes that were hashed. Never re-serialize before hashing. When the content is no longer held the file is omitted and `seal.json` carries `content_available: false` and `salt: null`. |
| `seal.json` | Yes | Record hash, salt, status, issuer, key ID and the ledger entry |
| `receipt.jws` | Yes | Compact JWS, `alg: ES256`, `typ: esc-receipt+jwt` |
| `keys/jwks.json` | Yes | Public sealing keys valid at seal time (P-256, with `kid` and `esc_env` of `live` or `test`) |
| `timestamp.tsr`, `timestamp.json` | When timestamped | RFC 3161 token whose message imprint is the record hash, and a readable summary. The token is authoritative. A test record made on the Free plan has no token: its `timestamp.json` is `{ "authority": null, "simulated": true }`. A live record made on the Free plan has the token. |
| `validation/tsa-chain.pem` | When timestamped | Certificates embedded in the token |
| `validation/policy.json` | Yes | Which checks and algorithms the package was produced under |
| `inclusion-proof.json` | When checkpointed | Audit path, root and the signed checkpoint (`typ: esc-checkpoint+jwt`) |
| `anchors.json` | When anchored | Public anchors covering the checkpoint |
| `documents/manifest.json`, `documents/<file>` | Yes | Each document version with its content hash, and the exact stored bytes |
| `notice/` | When captured | The `notice.captured` data and the serialized assent region |
| `report.pdf` | Yes | The evidence report |
| `annotations.json` | Yes | Later facts, each with its hash, ledger entry and receipt. May be empty. |
| `customer_supplied/` | Unless `?supplements=false` | A manifest and supplement content as received. Each manifest entry states the `subject` its content hash covers. |
| `rules.json` | Yes | Packs, rules fired with each condition's state and result, guidance release, API version |
| `VERIFY.md` | Yes | Manual verification steps |

### Record hash

```text
record_hash = "sha256:" + hex( SHA-256( salt_bytes || record_json_bytes ) )
```

`salt_bytes` are the 32 bytes of `seal.json` `salt` (base64url). `record_json_bytes` are the exact bytes of `record.json`, which is JSON Canonicalization Scheme (RFC 8785) output.

### Ledger entry hash

The UTF-8 bytes of these nine lines joined with a line feed, with no trailing newline, hashed with SHA-256 and prefixed `sha256:`:

```text
esc-ledger-v1
<domain_id>
<environment>
<seq>
<entry_type>
<subject_id>
<subject_hash>
<prev_hash>
<created_at>
```

`created_at` is RFC 3339 UTC with exactly three fractional digits. The first entry of a chain has a `prev_hash` of `sha256:` followed by 64 zeros.

### Inclusion proof

```json
{
  "tree": "RFC 6962",
  "leaf": "sha256:... (the ledger entry_hash)",
  "leaf_index": 48121,
  "tree_size": 48130,
  "audit_path": ["<hex>", "..."],
  "root": "<hex>",
  "checkpoint": "<compact JWS, typ esc-checkpoint+jwt>"
}
```

Leaf hash is `SHA-256(0x00 || entry_hash_bytes)`. Node hash is `SHA-256(0x01 || left || right)`. The audit path is ordered leaf to root. The checkpoint payload is `{ iss, chk, region, live, size, root, prev_root, iat }`.

### The nine checks

A verifier reports each check as `pass`, `fail` or `skipped` with the reason, and never reports overall success when a required check fails.

1. **Manifest.** Every listed file exists and matches its hash.
2. **Record hash.** Recompute from the salt and the bytes of `record.json`. Compare with `seal.record_hash`.
3. **Receipt.** Verify the ES256 signature against the key whose `kid` matches the header. Then check that the payload's `hash`, `rid`, `seq`, `prev` and `live` agree with the seal and the record.
4. **Ledger entry.** Recompute `entry_hash` from `seal.ledger`. Check that `subject_hash` equals the record hash.
5. **Timestamp.** The token's imprint equals the record hash and its signature verifies under the certificate embedded in the token. Chain validation to a trust anchor runs only when you supply roots. Otherwise it is skipped, not passed.
6. **Inclusion.** The leaf equals the ledger entry hash, the audit path recomputes the root, and the checkpoint JWS verifies and names that root and tree size.
7. **Documents.** The hash of each file equals its `content_hash`, and that hash equals the one for the same `version_id` in `record.json`.
8. **Annotations.** Each data hash and ledger entry hash recomputes, and each receipt verifies.
9. **Customer-supplied material.** Each supplement's receipt verifies and names its content hash, and each file matches its hash. Where the manifest states the item's `subject`, the content hash recomputes as the SHA-256 of the canonical form of `{ text, data, files, subject, type, occurred_at }`. Otherwise it is reported as not recomputed. These are reported in a separate section.

Checks 2, 3 and 4 are always required. Check 5 is required once the seal status is `timestamped`, and check 6 once it is `anchored`.

Three cases are worth knowing:

- **Simulated timestamp.** For a test record made on the Free plan, check 5 is skipped, never passed, and the report says the record has no external timestamp. On a live record a simulated timestamp is a failure. Live records on the Free plan carry a real token.
- **Erased or purged content.** Check 2 is skipped because there is no `record.json`. The seal over the hash is still checked, but the verifier does not report success: nothing in the package shows what the record said.
- **Older packages.** A package exported before the manifest carried `subject` still verifies. The supplement's content hash is reported as not recomputed.

## Verify by hand

`VERIFY.md` in every package lists the manual steps. The record hash needs only a few lines:

```bash
python3 - <<'PY'
import base64, hashlib, json
seal = json.load(open("seal.json"))
salt = base64.urlsafe_b64decode(seal["salt"] + "==")
print("sha256:" + hashlib.sha256(salt + open("record.json", "rb").read()).hexdigest())
print(seal["record_hash"])
PY
```

The two printed lines must be equal. The timestamp token can be checked with `openssl ts -verify` against the authority's root of your choice.

## Related

- [Evidence](https://esigncomply.com/docs/concepts/evidence.md) for the sealing pipeline behind these checks.
- [Certificates](https://esigncomply.com/docs/guides/certificates.md) for the on-request statement and its share links.
- [Verification API](https://esigncomply.com/docs/api/verification.md) for the endpoints on this page.
