Skip to content

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.

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.

curl https://esigncomply.com/v1/verify \
  -H "Content-Type: application/json" \
  -d '{ "receipt": "eyJhbGciOiJFUzI1NiIs..." }'
{
  "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:

{ "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.

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.

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.

# 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:

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 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.

curl https://esigncomply.com/v1/log/checkpoint
{
  "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

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::

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

{
  "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:

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.