Skip to content

Verification and public log

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

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

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

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

Example response

200 OK

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

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

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 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 403: a client token was used.
  • 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:

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

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

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

Example response

200 OK

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

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

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

Example response

200 OK

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

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

Example response

200 OK

{
  "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 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, RFC 9162).

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

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

Example response

200 OK

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