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.
- Manifest. Every listed file exists and matches its hash.
- Record hash. Recompute from the salt and the bytes of
record.json. Compare withseal.record_hash. - Receipt. Verify the ES256 signature against the key whose
kidmatches the header. Then check that the payload'shash,rid,seq,prevandliveagree with the seal and the record. - Ledger entry. Recompute
entry_hashfromseal.ledger. Check thatsubject_hashequals the record hash. - 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.
- 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.
- Documents. The hash of each file equals its
content_hash, and that hash equals the one for the sameversion_idinrecord.json. - Annotations. Each data hash and ledger entry hash recomputes, and each receipt verifies.
- 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
subjectstill 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.
Related
- Evidence for the sealing pipeline behind these checks.
- Certificates for the on-request statement and its share links.
- Verification API for the endpoints on this page.