# Esign Comply documentation (full text) > Every documentation page in one file, in navigation order. Each page starts with its title as a level-one heading, > followed by its source URL and the URL of its Markdown version. The index is at https://esigncomply.com/llms.txt. Pages: 41. Jurisdiction packs are not included here; each pack is at https://esigncomply.com/docs/jurisdictions/.md and the catalogue at https://esigncomply.com/docs/jurisdictions.md. --- # Esign Comply documentation Source: https://esigncomply.com/docs Markdown: https://esigncomply.com/docs.md Section: Start > Build the signing screen in your own interface. Esign Comply records the ceremony, checks selected conditions on its own record, and seals evidence you can verify without us. Esign Comply is a signature compliance API. You build the signing screen; for direct browser ceremonies, we record events we receive and check selected conditions on our own record. Your team still owns legal duties such as sending renewal reminders, honoring cancellations, and delivering required copies. The prompt separates "Your obligations" from "Recommendations." We do not perform or verify your duties. Send free text, JSON, and files through `POST /v1/supplements`. We seal each supplement with our receipt time and label it customer-supplied and unverified. Updates to state and country rules are delivered as guidance; new blocking conditions do not affect existing profiles until adopted. Read notices in the dashboard, email, webhook, API, or public changelog feed. Adding or removing a state does not require a code change to keep recording, but your flow may still need changes to meet new obligations. Start with the [quickstart](https://esigncomply.com/docs/quickstart.md) to record your first test signature on `localhost`, or [generate a prompt](https://esigncomply.com/product/prompt-generator) and let your AI coding tool do it. ## Start here | Page | What it gives you | |---|---| | [Quickstart](https://esigncomply.com/docs/quickstart.md) | A test key, a first sealed test record with curl or the SDK, a registered domain, and the steps to go live | | [Generate a prompt](https://esigncomply.com/product/prompt-generator) | A prompt for your AI coding tool, assembled from reviewed blocks for your use case, stack and rule packs | | [Browser SDK](https://esigncomply.com/docs/sdk/browser.md) | The headless SDK that observes the elements you built and reports the ceremony | | [API reference](https://esigncomply.com/docs/api.md) | Conventions, every endpoint, every error code | | [Webhooks](https://esigncomply.com/docs/api/webhooks.md) | Event types, signature verification, retries | | [Verify a record](https://esigncomply.com/docs/concepts/verification.md) | The verification page, the API, and the offline verifier | | [Compliance: United States](https://esigncomply.com/compliance/united-states) | How the product is designed for U.S. federal and state rules | | [Compliance: Europe](https://esigncomply.com/compliance/europe) | How the product is designed for the EU, the United Kingdom and Switzerland | ## For AI tools Every documentation page has a Markdown version at the same path plus `.md`, for example `/docs/quickstart.md`. The index is at [/llms.txt](https://esigncomply.com/llms.txt). | File | Use | |---|---| | [/llms.txt](https://esigncomply.com/llms.txt) | The index of every page, with rules for agents | | [/llms-full.txt](https://esigncomply.com/llms-full.txt) | Every documentation page in one file | | [/setup.md](https://esigncomply.com/setup.md) | The runbook an AI coding tool follows with a test key | | [/auth.md](https://esigncomply.com/auth.md) | How to handle keys: server only, never in chat, never committed | | [/pricing.md](https://esigncomply.com/pricing.md) | Plans, what counts as a signature event, certificate charges | | [/openapi.json](https://esigncomply.com/openapi.json) | OpenAPI 3.1 description of the `/v1` API | You create the account and accept the terms once. No card. After that your AI agent can do the rest: create keys, register documents, build the flow, verify the domain and go live. ## How it fits together 1. Your server registers each document version, so the text is fixed and hashed before anyone signs. 2. Your server creates a session for one signer and a bundle of document versions, and passes the session's client token to the browser. 3. The browser SDK observes the screen you built and sends each step straight to Esign Comply: the documents presented, the notice, the signer's own action. 4. Esign Comply writes the record, signs a receipt, and later attaches an external timestamp and a place in a public checkpoint. 5. Your server confirms the record with its secret key before it grants access. Each field in a record is labelled observed (seen by Esign Comply directly) or asserted (supplied by you). Verification checks integrity and the timestamp. It does not establish who acted or when the act actually occurred. ## Guides | Guide | Covers | |---|---| | [Next.js with Supabase](https://esigncomply.com/docs/guides/nextjs.md) | The full application: server module, migration, document pages, signup, confirmation, webhook, gate, NDA | | [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md) | Never trust the browser response: what to check and where | | [Test mode](https://esigncomply.com/docs/guides/test-mode.md) | Test keys, test origins, reserved test signers, what is watermarked | | [Register a domain](https://esigncomply.com/docs/guides/domains.md) | The one-domain rule, DNS and file verification, statuses, lapse | | [Consumer e-consent](https://esigncomply.com/docs/guides/consumer-econsent.md) | The ESIGN consumer consent steps: disclosure, access demonstration, consent | | [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md) | A one-time code by email or SMS inside the ceremony | | [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md) | A passkey challenge bound to the transaction | | [Re-acceptance](https://esigncomply.com/docs/guides/reacceptance.md) | Material changes, outstanding signers, the blocking screen | | [Supplements](https://esigncomply.com/docs/guides/supplements.md) | Customer-supplied text, JSON and files, sealed on receipt | | [Certificates](https://esigncomply.com/docs/guides/certificates.md) | The on-request Contemporaneous Record Statement: quote, confirm, share | | [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md) | Selecting packs, modes, `signer.region`, facts, the dry run | | [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md) | Notices, update prompts, advise until adopted, adopt and roll back | | [AI app builders](https://esigncomply.com/docs/guides/ai-builders.md) | v0, Lovable, Bolt and Replit: where the secret key goes | ## Concepts | Concept | Covers | |---|---| | [The ceremony](https://esigncomply.com/docs/concepts/ceremony.md) | Sessions, steps, assurance levels, signature methods, failure modes | | [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md) | What Esign Comply saw, what you told it, and what you sent later | | [Evidence](https://esigncomply.com/docs/concepts/evidence.md) | The sealing pipeline, the receipt, the evidence report, the evidence package | | [Verification](https://esigncomply.com/docs/concepts/verification.md) | Checking a record with and without Esign Comply | | [Compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md) | What can change, what cannot, and what you have to do in each case | ## SDKs and tools | Package | Use | |---|---| | [`@esigncomply/browser`](https://esigncomply.com/docs/sdk/browser.md) | Browser SDK: attaches to your elements and reports ceremony events | | [`@esigncomply/react`](https://esigncomply.com/docs/sdk/react.md) | Hooks over the browser SDK. No visual components. | | [`esigncomply`](https://esigncomply.com/docs/sdk/node.md) | Node server SDK: every method returns `{ data, error }` | | [`esigncomply` CLI](https://esigncomply.com/docs/sdk/cli.md) | `demo`, `check`, `documents publish`, `webhooks listen`, `verify` | | [`esigncomply-verify`](https://esigncomply.com/docs/sdk/verify.md) | Offline verification of evidence packages | ## API reference | Area | Endpoints | |---|---| | [Conventions](https://esigncomply.com/docs/api.md) | Base URLs, keys, idempotency, rate limits, pagination, versioning, the error envelope | | [Errors](https://esigncomply.com/docs/api/errors.md) | Every code, with status, type and what to do | | [Webhooks](https://esigncomply.com/docs/api/webhooks.md) | Events, signatures, retries | | [Documents](https://esigncomply.com/docs/api/documents.md) | Documents and immutable versions | | [Profiles](https://esigncomply.com/docs/api/profiles.md) | Ceremony profiles | | [Jurisdictions](https://esigncomply.com/docs/api/jurisdictions.md) | The pack catalogue and the dry run | | [Sessions](https://esigncomply.com/docs/api/sessions.md) | Sessions, events, verifications, completion | | [Records](https://esigncomply.com/docs/api/records.md) | Records, evidence report, evidence package, receipt, annotations | | [Signers](https://esigncomply.com/docs/api/signers.md) | Records and status per signer, consent withdrawal, erasure | | [Certificates](https://esigncomply.com/docs/api/certificates.md) | Quotes, issue, share links | | [Supplements and files](https://esigncomply.com/docs/api/supplements.md) | Customer-supplied material | | [Guidance and adoption](https://esigncomply.com/docs/api/guidance.md) | Notices, releases, update prompts, adopt and roll back | | [Verification and public log](https://esigncomply.com/docs/api/verification.md) | `/verify`, checkpoints, proofs, public keys | | [Account](https://esigncomply.com/docs/api/account.md) | Domains, API keys, webhook endpoints, usage, conformance runs, prompts | | [Agent account API](https://esigncomply.com/docs/api/agent.md) | For AI agents with an agent token: account state, API keys, the domain, going live on the Free plan | ## Conformance and rule packs - [Conformance rules](https://esigncomply.com/docs/conformance.md): the 28 automated checks, what each measures, and how to fix a finding. Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable. - [Jurisdiction packs](https://esigncomply.com/docs/jurisdictions.md): the catalogue of rule packs with every rule, fixed string, exclusion and fact key. A pack records which rules Esign Comply applied. It is not a statement that a flow meets the law of a jurisdiction. Esign Comply is a record-keeping and compliance tooling service. It is not a law firm and does not provide legal advice. Whether an agreement is enforceable depends on your documents, your implementation, and applicable law. --- # Quickstart Source: https://esigncomply.com/docs/quickstart Markdown: https://esigncomply.com/docs/quickstart.md Section: Start > Create a test key, record your first test signature on localhost with curl or the SDK, register your domain, and go live. Use this prompt to have your AI coding tool build this integration. It includes what to build, what never to do, and how to check the result. ```text copy="Copy prompt" open="cursor" You are adding an Esign Comply acceptance ceremony to this application's signup form. Esign Comply is the independent record keeper. This application renders every screen. The Esign Comply browser SDK observes the screen and the API seals the record. Read these first and follow them exactly. If something conflicts with existing code, or you are unsure how to implement a step, stop and ask. Do not invent API methods, packages, or legal wording. - https://esigncomply.com/agents.md (the account: what the person does once, and what you do with an agent token) - https://esigncomply.com/setup.md (runbook: the order of API calls) - https://esigncomply.com/auth.md (how to handle the agent token and the keys) - https://esigncomply.com/docs/quickstart.md - https://esigncomply.com/docs/guides/nextjs.md (if this is a Next.js application) Context - Packages (the only ones that exist): esigncomply (server), @esigncomply/browser (client). - API host: https://esigncomply.com/v1 - The person creates the Esign Comply account and accepts the terms once. After that you do the rest. With an agent token in ESIGNCOMPLY_AGENT_TOKEN you create the keys yourself: POST https://esigncomply.com/v1/agent/api-keys. - The secret key is in the server environment variable ESIGNCOMPLY_API_KEY (a test key, esc_test_...). Never print it, never ask for it in chat, never expose it to client code. - Server SDK calls return { data, error } and do not throw. Check error every time. Build 1. Verify the key: GET /v1/usage. Stop if it fails. 2. Create two documents (Terms of Service, type "terms"; Privacy Notice, type "privacy_notice") and publish one version of each from the documents in this project. If the project has none, register short sample documents, put "Sample" in their names, and say so in your report. Never write or change the wording of the real documents. 3. Create a profile: jurisdictions ["US-FED"], method "checkbox", assurance_level "L1". 4. Server: create the session with the secret key and an Idempotency-Key. Send only client_token and documents to the browser. Save the signer ID and the pinned version IDs in server-owned state. 5. Browser: attach with the client token, present each document, observe the assent region (notice text, document links, an unchecked checkbox, one primary button), and call complete() from the user's real click. 6. Server: before creating the account, read the record with GET /v1/records/{id} and require: status is "recorded", "timestamped" or "anchored"; livemode is as expected; the signer ID and version IDs equal the server-owned state. Never - Never pre-check a box, auto-submit, or call .click() on the user's behalf. - Never treat sign-in, scrolling, or continued use as acceptance. - Never use "By continuing" or "By clicking below" wording. - Never put the secret key, or any call that uses it, in a client component. - Never proxy @esigncomply/browser calls through this application's server. - Never copy document text into the repository. Render the registered version. - Never show "signed" or "accepted" before the server has confirmed the record. - Never tick the acceptance box on the Esign Comply sign-up page or type the emailed code: creating the account is the person's step. - Never ask for a key in chat. When the person says go live, create the live key yourself with POST /v1/agent/go-live. Keep live keys out of the repository and out of client code. Check before you report success - Read required_steps from the session and satisfy each one. Do not hard-code steps. - Take the signer's state from the form or account data and pass it as signer.region. Never infer it from an IP address. - Run: npx esigncomply check --url http://localhost:3000/signup Fix every finding marked "block". List every finding marked "warn". - Confirm by test that submitting with the box unchecked does nothing, and that the server refuses a made-up record ID. - Report: files created or changed, anything you did not implement and why, and the conformance summary. ``` Pass the signer's state from your own form or account data as `signer.region`. The integration reads applied packs, rules, wording, and required steps at runtime. Review advisories before adopting new rules; adding or removing a state does not stop recording. A prompt generated in the dashboard carries your own document and profile IDs and the rule packs you selected. The prompt above is the generic one. The rest of this page is the same integration by hand, in four steps. ## Before you start - You create the Esign Comply account and accept the terms once. No card. After that your AI agent can do the rest: create keys, register documents, build the flow, verify the domain and go live. - To hand over to an agent, start at [`/signup?next=/dashboard/agent`](https://esigncomply.com/signup?next=/dashboard/agent). Sign-up ends on **Agent access**, where you press **Create agent token** and paste the token to your agent, or the agent presses it in your logged-in browser. The agent keeps it in `ESIGNCOMPLY_AGENT_TOKEN`, logs in with it at `/agent-login`, or calls the [agent account API](https://esigncomply.com/docs/api/agent.md). Every step for agents is in the [guide for AI agents](https://esigncomply.com/agents.md). - The Free plan includes the full test mode, which needs no domain, and 10 live signature events per calendar month on one verified domain. - Node.js 20 or later for the SDK and the CLI. The API itself is plain HTTPS and JSON. - For the curl path: `curl` and `jq`. ## Step 1. Create an API key In the dashboard, choose **Create test key**. The key is shown once. Test keys start with `esc_test_us_` or `esc_test_eu_` and work on `localhost`, `127.0.0.1`, and configured preview hosts. An agent with an agent token creates the key itself: ```bash curl -s -X POST https://esigncomply.com/v1/agent/api-keys \ -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "test" }' ``` Store the key as a server environment variable: ```bash # .env.local (never commit this file) ESIGNCOMPLY_API_KEY=esc_test_us_... ``` The browser SDK receives a short-lived `esc_ct_` session token, never a secret API key. The rules for handling keys are in [/auth.md](https://esigncomply.com/auth.md). Check that the key works: ```bash export ESIGNCOMPLY_API_KEY=esc_test_us_... curl https://esigncomply.com/v1/usage \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" ``` The response, abbreviated: ```json { "object": "usage", "plan": "sandbox", "plan_name": "Free", "events": { "used": 0, "quota": 10, "period": "month" }, "test_events": { "used_this_month": 0, "quota_per_month": 500 } } ``` `sandbox` is the id of the Free plan. `events` counts live signature events: the Free plan includes 10 per calendar month. Test records are counted under `test_events`. A `401` means the key is wrong or revoked. A `421` means the key belongs to the other region: use the host named in the error. ## Step 2. Record a test signature Choose the packs for your ceremony and preview the applied rules. State packs are research drafts until reviewed by counsel admitted in that state. This quickstart uses the Federal pack only. There are three ways to produce a first test record. Each one ends with a sealed test record and its evidence report, watermarked TEST. ### Option A: one command ```bash npx esigncomply@latest demo ``` The command serves a local signup page, runs a ceremony against it with your test key, and prints the record ID. It reads `ESIGNCOMPLY_API_KEY` from the environment and accepts test keys only. ### Option B: curl This is the whole ceremony as API calls. In a real integration the middle part (the events) is sent by the browser SDK from the signer's device. In test mode you may send it with curl, which makes the sequence easy to see. The Free plan allows 2 requests per second per key, so the script pauses between secret-key calls. ```bash ESC=https://esigncomply.com/v1 KEY="Authorization: Bearer $ESIGNCOMPLY_API_KEY" JSON="Content-Type: application/json" # 1. Two documents, one version each. TOS=$(curl -s $ESC/documents -H "$KEY" -H "$JSON" \ -d '{"name":"Terms of Service","type":"terms"}' | jq -r .id); sleep 1 PRIV=$(curl -s $ESC/documents -H "$KEY" -H "$JSON" \ -d '{"name":"Privacy Notice","type":"privacy_notice"}' | jq -r .id); sleep 1 TOS_V=$(curl -s $ESC/documents/$TOS/versions -H "$KEY" -H "$JSON" \ -H "Idempotency-Key: tos-2026-11-21" \ -d '{"version_label":"2026-11-21","language":"en","content":{"format":"markdown","text":"# Terms of Service\n\nThese are the terms."},"material_change":true}'); sleep 1 PRIV_V=$(curl -s $ESC/documents/$PRIV/versions -H "$KEY" -H "$JSON" \ -H "Idempotency-Key: privacy-2026-11-21" \ -d '{"version_label":"2026-11-21","language":"en","content":{"format":"text","text":"We keep your data safe."}}'); sleep 1 TOS_DV=$(echo "$TOS_V" | jq -r .id); TOS_RH=$(echo "$TOS_V" | jq -r .render_hash) PRIV_DV=$(echo "$PRIV_V" | jq -r .id) # 2. A profile: Federal pack, checkbox plus button, L1. PROF=$(curl -s $ESC/profiles -H "$KEY" -H "$JSON" \ -d '{"name":"Signup","jurisdictions":["US-FED"],"method":"checkbox","assurance_level":"L1"}' | jq -r .id); sleep 1 # 3. A session for one signer and both documents. SESSION=$(curl -s $ESC/sessions -H "$KEY" -H "$JSON" \ -H "Idempotency-Key: signup-user_7c1d-1" \ -d "{ \"profile\": \"$PROF\", \"signer\": { \"external_id\": \"user_7c1d\", \"email\": \"dana@example.org\", \"name\": \"Dana Whitfield\", \"class\": \"consumer\", \"country\": \"US\", \"region\": \"US-CA\" }, \"documents\": [ { \"document\": \"$TOS\", \"version\": \"current\" }, { \"document\": \"$PRIV\", \"version\": \"current\" } ], \"context\": { \"url\": \"http://localhost:3000/signup\", \"locale\": \"en-US\", \"purpose\": \"account_signup\" } }") SES=$(echo "$SESSION" | jq -r .id); CT=$(echo "$SESSION" | jq -r .client_token) echo "$SESSION" | jq '{id, status, required_steps, applied_jurisdictions, warnings}' ``` The session response lists the steps this ceremony needs: ```json { "id": "ses_5nWq", "status": "created", "required_steps": [ "client.attached", "document.presented:dv_3kT9", "document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied" ], "applied_jurisdictions": [{ "code": "US-FED", "version": "2026-11-21", "reason": "base" }], "warnings": ["jurisdiction_not_enabled:US-CA"] } ``` The warning says that the signer is in California and this profile enables only the Federal pack. It is not an error: the session runs on Federal rules and the record says so. To apply a state pack, add it to the profile. See [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md). Now send the ceremony events with the client token. These are the calls the browser SDK makes. ```bash CLIENT="Authorization: Bearer $CT" event() { curl -s $ESC/sessions/$SES/events -H "$CLIENT" -H "$JSON" -d "$1" \ | jq -c '{type, status: .conformance.status, remaining_steps}'; } event '{"type":"client.attached","data":{"sdk_version":"1.0.0","page_url":"http://localhost:3000/signup","viewport":{"width":390,"height":844}}}' event "{\"type\":\"document.presented\",\"version_id\":\"$TOS_DV\",\"data\":{\"mode\":\"hyperlink\",\"link_text\":\"Terms of Service\",\"link_visible\":true,\"link_style\":{\"underlined\":true,\"contrast_ratio\":7.2,\"font_px\":14},\"link_target_render_hash\":\"$TOS_RH\"}}" event "{\"type\":\"document.presented\",\"version_id\":\"$PRIV_DV\",\"data\":{\"mode\":\"hyperlink\",\"link_text\":\"Privacy Notice\",\"link_visible\":true,\"link_style\":{\"underlined\":true,\"contrast_ratio\":7.2,\"font_px\":14}}}" event '{"type":"notice.captured","data":{"text":"By checking the box and clicking Create account, you agree to the Terms of Service and acknowledge the Privacy Notice.","styles":{"font_px":14,"body_font_px":14,"contrast_ratio":10.3},"layout":{"same_viewport":true,"notice_above_action":true,"notice_to_action_px":12,"viewport":{"width":390,"height":844}},"controls":{"primary_buttons":1,"competing_controls":0,"checkbox":{"initial_checked":false,"label_text":"I agree to the Terms of Service and Privacy Notice"},"submit":{"label":"Create account"}}}}' event '{"type":"intent.captured","client_time":"2026-11-21T10:03:17-05:00","data":{"control":"checkbox","label_text":"I agree to the Terms of Service and Privacy Notice","initial_state":"unchecked","trusted":true}}' # The signing act. The record is written and its receipt signed before the response returns. RECORD=$(curl -s $ESC/sessions/$SES/complete -H "$CLIENT" -H "$JSON" \ -H "Idempotency-Key: $SES-complete" \ -d '{"signature":{"method":"checkbox","label_text":"I agree to the Terms of Service and Privacy Notice","button_text":"Create account"},"client_time":"2026-11-21T10:03:20.004-05:00"}') REC=$(echo "$RECORD" | jq -r .id) echo "$RECORD" | jq '{id, status, signature_level, assurance_level, record_hash, verify_url, seal}' ``` ```json { "id": "rec_Z4m8", "status": "recorded", "signature_level": "simple", "assurance_level": "L1", "record_hash": "sha256:5be7...", "verify_url": "https://esigncomply.com/verify/rec_Z4m8", "seal": { "ledger_seq": 1, "timestamp": "pending", "anchor": "pending" } } ``` Each event response carries a conformance result. In test mode findings never block: they are reported so that you, or your coding tool, can read them and repair the interface. Calling `complete` before the required steps are recorded returns `422` [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) with `missing_steps`. The completion response goes to the browser, so your server must not trust it. Confirm the record with the secret key: ```bash sleep 1 curl -s $ESC/records/$REC -H "$KEY" \ | jq '{id, status, livemode, signer: .signer.external_id, versions: [.documents[].version_id]}' ``` ```json { "id": "rec_Z4m8", "status": "recorded", "livemode": false, "signer": "user_7c1d", "versions": ["dv_3kT9", "dv_Lm02"] } ``` Grant access only when `status` is `recorded`, `timestamped` or `anchored`, `livemode` is what you expect, and the signer and versions equal what your server saved when it created the session. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). ### Option C: the SDK Install the two packages: ```bash npm install esigncomply @esigncomply/browser ``` Create the server module. The `server-only` import makes the build fail if a client component ever imports it. ```ts // lib/esigncomply.ts import "server-only"; import { EsignComply } from "esigncomply"; export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!); ``` Create the session on your server and return only the client token and the pinned documents: ```ts // app/api/ceremony/route.ts import { esc } from "@/lib/esigncomply"; export async function POST(request: Request) { const { signerId, email, name, region, attempt } = await request.json(); const { data: session, error } = await esc.sessions.create( { profile: "prof_signup_4f1a", signer: { external_id: signerId, email, name, class: "consumer", country: "US", region }, documents: [ { document: "doc_8Hq2", version: "current" }, // Terms of Service { document: "doc_Pv71", version: "current" }, // Privacy Notice ], context: { url: "http://localhost:3000/signup", locale: "en-US", purpose: "account_signup" }, }, { idempotencyKey: `signup-${signerId}-${attempt}` }, ); if (error) return Response.json({ error: error.code }, { status: 502 }); // Save signerId and session.documents[].version_id in server-owned state here. return Response.json({ clientToken: session.client_token, documents: session.documents }); } ``` Run the ceremony in the browser. The SDK renders nothing: it observes the elements you built and reports to Esign Comply directly. ```ts // A client-side module. The SDK is loaded in the browser only. import { EsignComply } from "@esigncomply/browser"; const response = await fetch("/api/ceremony", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ signerId, email, name, region: "US-CA", attempt: 1 }), }); const { clientToken, documents } = await response.json(); const ceremony = await EsignComply.attach({ clientToken }); await ceremony.presentDocument({ versionId: documents[0].version_id, mode: "hyperlink", link: document.querySelector("#tos-link"), }); await ceremony.presentDocument({ versionId: documents[1].version_id, mode: "hyperlink", link: document.querySelector("#privacy-link"), }); await ceremony.observeAssent({ region: document.querySelector("#assent"), // notice text, links, checkbox, button checkbox: document.querySelector("#agree"), submit: document.querySelector("#create-account"), }); // Call this from the real submit handler, after the signer has ticked the box. async function finishSignup() { const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status } await fetch("/api/signup/confirm", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ recordId: result.recordId }), }); } ``` The markup the SDK observes: ```html

By checking the box and clicking Create account, you agree to the Terms of Service and acknowledge the Privacy Notice.

``` The checkbox starts unchecked. The notice sits directly above the one primary button and names it by its label. The document links are underlined and differ in color from the surrounding text. Confirm on the server before creating the account: ```ts // app/api/signup/confirm/route.ts import { esc } from "@/lib/esigncomply"; export async function POST(request: Request) { const { recordId } = await request.json(); const expected = await loadCeremonyState(request); // your server-owned state const { data: record, error } = await esc.records.get(recordId); if (error) return Response.json({ confirmed: false }, { status: 409 }); const versions = record.documents.map((d) => d.version_id).sort(); const confirmed = ["recorded", "timestamped", "anchored"].includes(record.status) && record.livemode === (process.env.VERCEL_ENV === "production") && record.signer.external_id === expected.signerId && JSON.stringify(versions) === JSON.stringify([...expected.versionIds].sort()); if (!confirmed) return Response.json({ confirmed: false }, { status: 409 }); // Only now create the account. return Response.json({ confirmed: true }); } ``` `loadCeremonyState` is yours: it returns the signer ID and version IDs your server saved when it created the session. The full application, with the Supabase migration, the webhook, the re-acceptance gate and an NDA signed at L2, is in the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). ### Check the result Run the conformance check against your page: ```bash npx esigncomply check --url http://localhost:3000/signup ``` Fix every finding marked `block` and read every finding marked `warn`. Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable. The rules are listed on [Conformance rules](https://esigncomply.com/docs/conformance.md). When your first test record is sealed, it appears in the dashboard with what was observed, what was asserted, and its evidence report (watermarked TEST). ## Step 3. Register and verify your domain You need a registered and verified domain to go live. Test mode works without one. Every plan, Free included, covers one registrable domain and every subdomain: registering `app.example.com` covers `example.com` and all hosts under it. Register it in the dashboard, or with a `full_access` key: ```bash curl https://esigncomply.com/v1/domains \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "app.example.com", "region": "us" }' ``` ```json { "object": "domain", "id": "dom_4Kx9", "domain": "example.com", "entered_host": "app.example.com", "region": "us", "status": "pending", "verification": { "method": "dns", "type": "TXT", "name": "_esigncomply.example.com", "host": "_esigncomply", "value": "esc-verify=" }, "api_url": "https://esigncomply.com/v1" } ``` Add a TXT record named `_esigncomply` (for example, `_esigncomply.example.com`) with value `esc-verify=`. If you host on a shared platform address such as `myapp.vercel.app`, serve the token at `/.well-known/esigncomply.txt` instead. An AI agent that has no access to your DNS provider asks you to add this one record. Choose your data region now; it is fixed for this domain. The Free plan records live in the US region only: the EU region needs a paid plan. Esign Comply checks every minute for the first hour, then every 15 minutes for 72 hours. To check at once: ```bash curl -X POST https://esigncomply.com/v1/domains/dom_4Kx9/verify \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" ``` Leave the record in place after verification: it is checked again every day. Details, statuses and the file method are in [Register a domain](https://esigncomply.com/docs/guides/domains.md). ## Step 4. Go live Going live takes three steps. There is no plan to choose and no checkout. 1. Register and verify your domain (Step 3). 2. Add the organization's legal name, country and address under **Go live** in the dashboard. The legal name is printed on every evidence report. 3. Create a live key (`esc_live_us_` or `esc_live_eu_`). It is shown once. The default permission is `recording_access`: it can create sessions and read record status and receipts for server confirmation, and it cannot download evidence. An agent does steps 2 and 3 in one call, [`POST /v1/agent/go-live`](https://esigncomply.com/docs/api/agent.md#go-live-on-the-free-plan), with the organization's details from you. You accepted the customer terms and the data-processing agreement once, at sign-up, so there is nothing to accept here. An organization created before sign-up recorded the data-processing agreement is asked to accept it once on the Go live page, and that step needs the account owner in person. On the Free plan you can now record 10 live signature events per calendar month (UTC) on your verified domain. They are real records: an outside RFC 3161 timestamp, signed checkpoints, a public anchor, the public verification page, the signer copy by email, the evidence report and the evidence package. Free covers 10 live signatures a month. If you use all 10 in a month, the account locks until you upgrade to a paid plan. It does not unlock at the start of the next month. Past the limit, new live signatures can be refused, so upgrade before you get there. A refused request returns `402` [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted). See [Free plan limits](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits). A paid plan is optional. The account owner chooses Starter or Unlimited on the Go live page or under Settings, Billing. Both are annual and cover one domain and its subdomains. Prices are at [/pricing.md](https://esigncomply.com/pricing.md). Then switch your application over: - Set the live key as `ESIGNCOMPLY_API_KEY` in your production environment only. Keep the test key for preview and development. - Test and live share nothing. Copy your test documents, profiles and webhook endpoints to live from the dashboard, or create them again with the live key, and use the live IDs in production. In live mode, `context.url` must be within your registered domain, browser calls must come from it, and a Block finding that your profile has adopted stops a record from being sealed. Run the conformance check until nothing blocks before you switch keys. ## Next steps - [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md): the one place access is granted. - [Webhooks](https://esigncomply.com/docs/api/webhooks.md): `record.completed`, signatures and retries. - [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md): add state packs and pass `signer.region`. - [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md): verify an email address or phone number inside the ceremony for NDAs and contracts. - [Browser SDK](https://esigncomply.com/docs/sdk/browser.md) and [API conventions](https://esigncomply.com/docs/api.md). --- # Next.js with Supabase Source: https://esigncomply.com/docs/guides/nextjs Markdown: https://esigncomply.com/docs/guides/nextjs.md Section: Guides > Build signup acceptance and NDA signing in a Next.js App Router application with Supabase and Vercel, with Esign Comply recording each ceremony. This guide adds two flows to a Next.js App Router application that uses Supabase for authentication and data and deploys on Vercel: acceptance of the Terms of Service and Privacy Notice at signup (L1, checkbox and button), and signing of a Mutual NDA (L2, email code and typed name). You build every screen. The browser SDK observes the screens you build and reports each step to Esign Comply, which seals the record. It follows the same structure as a generated prompt. If you would rather have an AI coding tool do the work, [generate a prompt](https://esigncomply.com/product/prompt-generator) and paste it into your tool. If you have not recorded a test signature yet, start with the [quickstart](https://esigncomply.com/docs/quickstart.md). ## Before you start You need: - A test key (`esc_test_us_...`). Test keys work on `localhost` without a registered domain. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). - Three documents with a published version each: Terms of Service (`doc_8Hq2`), Privacy Notice (`doc_Pv71`) and Mutual NDA (`doc_Nd55`). See the [Documents API](https://esigncomply.com/docs/api/documents.md). The document names must match the titles you print in the notice text, because [CR-02](https://esigncomply.com/docs/conformance.md#cr-02) looks for each title. - Two profiles: `prof_signup_4f1a` (method `checkbox`, assurance level `L1`, failure mode `fail_closed`) and `prof_nda_9c2e` (method `typed`, assurance level `L2`). See the [Profiles API](https://esigncomply.com/docs/api/profiles.md). - A Supabase project with a `public.profiles` table keyed by `auth.users.id`. Files this guide creates: | File | Purpose | |---|---| | `lib/esigncomply.ts` | Server-only SDK client | | `lib/supabase-admin.ts` | Server-only Supabase service-role client | | `lib/esign-confirm.ts` | Server confirmation of a record | | `supabase/migrations/…_esign.sql` | Tables, with row-level security | | `app/legal/[slug]/page.tsx` | Document pages that render the registered version | | `app/signup/actions.ts`, `app/signup/signup-form.tsx` | Signup ceremony | | `app/api/esigncomply/webhook/route.ts` | Webhook handler | | `app/nda/[id]/actions.ts`, `app/nda/[id]/nda-signing.tsx` | NDA signing | ## Rules for the interface Esign Comply checks these on its own record. Rule IDs link to the [conformance rules](https://esigncomply.com/docs/conformance.md). In test mode a failed check is reported and never blocks, so you can read the finding and repair the page. 1. Create every session on the server with the secret key. Send only `client_token` to the browser. 2. Read `required_steps` from the session and satisfy each one. Do not hard-code steps. 3. Show the notice text directly above the action button, in the same container, visible without scrolling at 390 x 844 ([CR-04](https://esigncomply.com/docs/conformance.md#cr-04)). 4. Notice wording for signup, verbatim, with links: "By checking the box and clicking Create account, you agree to the Terms of Service and acknowledge the Privacy Notice." Use "Create account" only if signup does not create a payment obligation ([CR-02](https://esigncomply.com/docs/conformance.md#cr-02), [CR-03](https://esigncomply.com/docs/conformance.md#cr-03)). 5. Underline document links and give them a color that differs from the surrounding text by a contrast ratio of at least 3:1, and at least 4.5:1 against the background. Notice text is at least 14px and never lighter than body text ([CR-05](https://esigncomply.com/docs/conformance.md#cr-05), [CR-06](https://esigncomply.com/docs/conformance.md#cr-06)). 6. Every checkbox starts unchecked. Every typed-name field starts empty ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)). 7. Only one primary button inside the assent container. Give any other button in it `type="button"`. Put social sign-in buttons in a separate container with their own notice and their own session ([CR-07](https://esigncomply.com/docs/conformance.md#cr-07)). 8. Serve each document at a stable page on your domain that renders the registered version fetched from Esign Comply, unmodified ([CR-08](https://esigncomply.com/docs/conformance.md#cr-08)). 9. Treat the browser result as untrusted. Grant access only after your server has confirmed the record with the secret key. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). 10. Pass an `Idempotency-Key` on session creation. 11. Below the Create account button, inside the same container, show: "{Company} uses Esign Comply to record this event on its behalf. See {Company}'s Privacy Notice for purposes and roles." Nothing may sit between the notice and the button. This line is information, not a request for consent. > **Never.** Never pre-check a box, auto-submit, or call `.click()` on the user's behalf. Never treat sign-in, scrolling, or continued use as acceptance. Never use "By continuing" or "By clicking below" wording. Never put the secret key, or any call that uses it, in a client component. Never proxy `@esigncomply/browser` calls through your own server. Never cache or copy document text into the repository: always render the registered version. Never write to `esign_acceptances` from the browser. Never show "signed" or "accepted" before the server has confirmed the record. Never write or change the text of the Terms, Privacy Notice, or NDA in code. ## 1. Install and configure ```bash npm install esigncomply @esigncomply/browser ``` Add the key and the webhook secret to `.env.local`, and to the Vercel project's environment variables (test key for Preview and Development, live key for Production). Neither name starts with `NEXT_PUBLIC_`. ```bash ESIGNCOMPLY_API_KEY=esc_test_us_... ESIGNCOMPLY_WEBHOOK_SECRET=whsec_... SUPABASE_SERVICE_ROLE_KEY=... ``` Create `lib/esigncomply.ts`. The `server-only` import makes the build fail if a client component imports it. ```ts import "server-only"; import { EsignComply } from "esigncomply"; export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!); ``` Create `lib/supabase-admin.ts`: ```ts import "server-only"; import { createClient } from "@supabase/supabase-js"; export const supabaseAdmin = createClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!, { auth: { persistSession: false, autoRefreshToken: false } }, ); ``` Server SDK calls return `{ data, error }` and do not throw. Check `error` every time. ## 2. Database Keep your own table of acceptances and store the Esign Comply record ID in it. One record can cover several documents, so the table holds one row per record and document. ```sql create table public.esign_acceptances ( id uuid primary key default gen_random_uuid(), user_id uuid references auth.users(id) on delete cascade, signer_id uuid not null, record_id text not null, document_id text not null, version_id text not null, purpose text not null, signed_at timestamptz not null, disputed_at timestamptz, created_at timestamptz not null default now(), unique (record_id, document_id) ); alter table public.esign_acceptances enable row level security; create policy "read own" on public.esign_acceptances for select using (auth.uid() = user_id); -- No insert, update, or delete policies. Only the service role writes. -- Server-owned state: which versions each session pinned, for confirmation. create table public.esign_ceremonies ( session_id text primary key, signer_id uuid not null, purpose text not null, version_ids text[] not null, created_at timestamptz not null default now() ); alter table public.esign_ceremonies enable row level security; -- No policies. Only the service role reads and writes. -- Webhook deliveries already handled, keyed by webhook-id. create table public.esign_webhook_events ( id text primary key, type text not null, received_at timestamptz not null default now() ); alter table public.esign_webhook_events enable row level security; alter table public.profiles add column if not exists signer_id uuid unique; ``` ## 3. Document pages Create `app/legal/[slug]/page.tsx` for `terms`, `privacy` and `nda`. The page renders the HTML that Esign Comply returns for one exact version, inside `
`. Put nothing else inside the article: the browser SDK hashes the article's text and compares it with the version's `render_hash`. Resolve `current` only when a session is created. Links inside a ceremony carry the pinned version ID (`?v=dv_3kT9`), and the page fetches by that ID. In this Next.js version `params` and `searchParams` are Promises. ```tsx import { notFound } from "next/navigation"; import { esc } from "@/lib/esigncomply"; import { PrintButton } from "./print-button"; const DOCUMENTS: Record = { terms: "doc_8Hq2", privacy: "doc_Pv71", nda: "doc_Nd55", }; export default async function LegalPage({ params, searchParams, }: { params: Promise<{ slug: string }>; searchParams: Promise<{ v?: string }>; }) { const { slug } = await params; const { v } = await searchParams; const documentId = DOCUMENTS[slug]; if (!documentId) notFound(); const { data, error } = await esc.documents.versions.getContent(documentId, v ?? "current"); if (error || !data?.html) notFound(); return (

Download {" "}

); } ``` `app/legal/[slug]/print-button.tsx`: ```tsx "use client"; export function PrintButton() { return ( ); } ``` `app/legal/[slug]/download/route.ts` returns the stored text of the same version as a file: ```ts import { esc } from "@/lib/esigncomply"; const DOCUMENTS: Record = { terms: "doc_8Hq2", privacy: "doc_Pv71", nda: "doc_Nd55" }; export async function GET(request: Request, { params }: { params: Promise<{ slug: string }> }) { const { slug } = await params; const version = new URL(request.url).searchParams.get("v") ?? "current"; const documentId = DOCUMENTS[slug]; if (!documentId) return new Response("Not found", { status: 404 }); const { data, error } = await esc.documents.versions.getContent(documentId, version); if (error || !data?.text) return new Response("Not found", { status: 404 }); return new Response(data.text, { headers: { "Content-Type": "text/plain; charset=utf-8", "Content-Disposition": `attachment; filename="${slug}-${data.version_id}.txt"`, }, }); } ``` The HTML returned by the API is already sanitized. Do not transform it, wrap it in extra text, or copy it into the repository. Render the article on the server, as above: for a linked document the browser SDK fetches the page behind the link and reads the article from its HTML without running scripts, so text that only appears after client-side rendering is not seen. It also looks for the `data-esc-download` and `data-esc-print` controls on that page. ## 4. Signup ceremony ### Signup server action `app/signup/actions.ts` creates the session. The signer ID is generated on the server and kept in an httpOnly cookie that lives as long as the signup. ```ts "use server"; import { cookies, headers } from "next/headers"; import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; import { confirmRecord } from "@/lib/esign-confirm"; export interface StartInput { email: string; accountType: "consumer" | "business"; country: string; // from the form, never from IP region?: string; // ISO 3166-2, for example "US-CA"; omit when unknown locale: string; attempt: number; // increases when a session expires or the inputs change } export async function startSignupCeremony(input: StartInput) { const jar = await cookies(); let signerId = jar.get("esc_signer")?.value; if (!signerId) { signerId = crypto.randomUUID(); jar.set("esc_signer", signerId, { httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "lax", maxAge: 60 * 60, path: "/", }); } const h = await headers(); const origin = h.get("origin") ?? `https://${h.get("host")}`; const { data, error } = await esc.sessions.create( { profile: "prof_signup_4f1a", signer: { external_id: signerId, email: input.email, class: input.accountType, country: input.country, region: input.region, }, documents: [ { document: "doc_8Hq2", version: "current" }, { document: "doc_Pv71", version: "current" }, ], context: { url: `${origin}/signup`, locale: input.locale, purpose: "account_signup" }, }, { idempotencyKey: `signup-${signerId}-${input.attempt}` }, ); if (error) return { ok: false as const, code: error.code, message: error.message }; // Server-owned state: the versions this session pinned. await supabaseAdmin.from("esign_ceremonies").upsert({ session_id: data.id, signer_id: signerId, purpose: "account_signup", version_ids: data.documents.map((d) => d.version_id), }); return { ok: true as const, clientToken: data.client_token, apiUrl: data.api_url, documents: data.documents.map((d) => ({ documentId: d.document_id, versionId: d.version_id, title: d.title })), requiredStrings: data.required_strings, warnings: data.warnings, }; } ``` Notes: - `class` is `consumer` or `business` from the account type field. Take `country` and `region` from the form or your own account data. Do not guess them from an IP address. For U.S. signers, `region` is the state as an ISO code such as `US-CA`. If the state is unknown, omit it: the profile's `on_unknown_region` setting decides which packs apply. See [Jurisdictions](https://esigncomply.com/docs/guides/jurisdictions.md). - Do not hard-code which state rules apply. Read `applied_jurisdictions`, `rules_fired` and `required_strings` from the response and render every required string verbatim in the slot it names. - A state without a pack returns the warning `state_pack_unavailable:` and the session runs on Federal rules. Do not tell the user anything about that state's law. - A repeat with the same idempotency key and the same body returns the original session. Increase `attempt` when the session has expired or the signer changed the email, account type or state, so that a new session is created. ### Signup form `app/signup/signup-form.tsx` attaches the SDK to the elements you rendered. The SDK watches the checkbox and records `intent.captured` when the signer ticks it. Your code never sets `checked`. ```tsx "use client"; import { useEffect, useRef, useState } from "react"; import { EsignComply, type Ceremony, type EsignComplyError } from "@esigncomply/browser"; import { finishSignup, reconcileSignup, startSignupCeremony } from "./actions"; type Started = Extract>, { ok: true }>; const INCONCLUSIVE = "We could not confirm whether your acceptance was recorded. Please wait while we check."; export function SignupForm({ company }: { company: string }) { const formRef = useRef(null); const assentRef = useRef(null); const checkboxRef = useRef(null); const submitRef = useRef(null); const tosLinkRef = useRef(null); const privacyLinkRef = useRef(null); const ceremonyRef = useRef(null); const attemptRef = useRef(1); const activeRef = useRef(false); // a session exists or is being created const [started, setStarted] = useState(null); const [ready, setReady] = useState(false); const [pending, setPending] = useState(false); const [message, setMessage] = useState(null); const tos = started?.documents.find((d) => d.documentId === "doc_8Hq2"); const privacy = started?.documents.find((d) => d.documentId === "doc_Pv71"); // Start the ceremony once the email is entered, not on submit. async function start() { if (activeRef.current || !formRef.current) return; const form = new FormData(formRef.current); const email = String(form.get("email") ?? ""); if (!/^\S+@\S+\.\S+$/.test(email)) return; const country = String(form.get("country") ?? "").toUpperCase(); const state = String(form.get("state") ?? "").toUpperCase(); const attempt = attemptRef.current; activeRef.current = true; const res = await startSignupCeremony({ email, accountType: form.get("accountType") === "business" ? "business" : "consumer", country, region: country === "US" && state ? `US-${state}` : undefined, locale: navigator.language, attempt, }); if (attempt !== attemptRef.current) return; // the inputs changed while the request was in flight if (res.ok) setStarted(res); else { activeRef.current = false; setMessage(res.message); } } // The session is bound to the email, account type and state it was created with. // When one of them changes, or the session expires, drop it and start a new one. function reset() { attemptRef.current += 1; activeRef.current = false; if (checkboxRef.current) checkboxRef.current.checked = false; // back to the clear state for the new session setStarted(null); setReady(false); } useEffect(() => { if (!started || !tos || !privacy) return; let cancelled = false; let ceremony: Ceremony | undefined; (async () => { try { ceremony = await EsignComply.attach({ clientToken: started.clientToken, apiUrl: started.apiUrl }); if (cancelled) return ceremony.destroy(); ceremonyRef.current = ceremony; ceremony.on("change", ({ remainingSteps }) => { setReady(remainingSteps.length === 1 && remainingSteps[0] === "signature.applied"); }); ceremony.on("expired", () => { reset(); void start(); }); await ceremony.presentDocument({ versionId: tos.versionId, mode: "hyperlink", link: tosLinkRef.current }); await ceremony.presentDocument({ versionId: privacy.versionId, mode: "hyperlink", link: privacyLinkRef.current }); await ceremony.observeAssent({ region: assentRef.current, // contains notice, links, checkbox, button checkbox: checkboxRef.current, submit: submitRef.current, }); } catch (err) { if (!cancelled) setMessage((err as EsignComplyError).message); } })(); return () => { cancelled = true; ceremony?.destroy(); ceremonyRef.current = null; }; // eslint-disable-next-line react-hooks/exhaustive-deps }, [started]); function onSignerFieldChange() { if (activeRef.current) reset(); // the next blur starts a new session } async function onSubmit(event: React.FormEvent) { event.preventDefault(); const ceremony = ceremonyRef.current; if (!ceremony || !ready || !formRef.current) return; const form = new FormData(formRef.current); setPending(true); setMessage(null); try { const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status } const outcome = await finishSignup(form, result.recordId); // step 5 if (outcome.ok) window.location.assign("/app"); else setMessage(outcome.message); } catch (err) { const error = err as EsignComplyError; if (error.code === "client_token_expired") { reset(); void start(); setMessage("Your session expired. Check the box again to continue."); } else if (error.code === "network_error" || error.status >= 500) { // Never proceed without a record, and never ask for a second act before reconciling. setMessage(INCONCLUSIVE); const outcome = await reconcileSignup(form); if (outcome.ok) window.location.assign("/app"); } else { setMessage(error.message); // typed error with the rule ID and a fix } } finally { setPending(false); } } return (
void start()}>

{company} uses Esign Comply to record this event on its behalf. See {company}'s Privacy Notice for purposes and roles.

{message ?

{message}

: null}
); } ``` The button stays disabled until `ceremony.remainingSteps()` contains only `"signature.applied"`. The `change` event fires whenever that list changes, including when the signer unticks the box. The only place this component writes to the checkbox is `reset()`, which returns it to unchecked when a session is replaced. A new session must find the control in its clear state ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)). Nothing ever sets it to checked. ## 5. Server confirmation This is the only place access is granted. `lib/esign-confirm.ts` reads the record with the secret key and compares it with server-owned state. The checks are explained in [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). ```ts import "server-only"; import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; const SEALED = new Set(["recorded", "timestamped", "anchored"]); export async function confirmRecord(input: { recordId: string; signerId: string; purpose: string }) { const { data: ceremonies } = await supabaseAdmin .from("esign_ceremonies") .select("session_id, version_ids") .eq("signer_id", input.signerId) .eq("purpose", input.purpose); const { data: record, error } = await esc.records.get(input.recordId); if (error) return { ok: false as const, reason: error.code }; const versions = record.documents.map((d) => d.version_id).sort().join(","); const pinned = (ceremonies ?? []).some((c) => [...c.version_ids].sort().join(",") === versions); const ok = SEALED.has(record.status) && record.signer.external_id === input.signerId && record.livemode === (process.env.VERCEL_ENV === "production") && pinned; return ok ? { ok: true as const, record } : { ok: false as const, reason: "record_mismatch" }; } export async function saveAcceptances( record: { id: string; signed_at: string; documents: Array<{ document_id: string; version_id: string }> }, input: { signerId: string; userId: string | null; purpose: string }, ) { return supabaseAdmin.from("esign_acceptances").upsert( record.documents.map((d) => ({ user_id: input.userId, signer_id: input.signerId, record_id: record.id, document_id: d.document_id, version_id: d.version_id, purpose: input.purpose, signed_at: record.signed_at, })), { onConflict: "record_id,document_id" }, ); } ``` Add `finishSignup` and `reconcileSignup` to `app/signup/actions.ts`, and extend its import to `import { confirmRecord, saveAcceptances } from "@/lib/esign-confirm";`: ```ts const INCONCLUSIVE = "We could not confirm whether your acceptance was recorded. Please wait while we check."; export async function finishSignup(form: FormData, recordId: string) { const signerId = (await cookies()).get("esc_signer")?.value; if (!signerId) return { ok: false as const, message: "Your signup session has ended. Start again." }; const confirmed = await confirmRecord({ recordId, signerId, purpose: "account_signup" }); if (!confirmed.ok) return { ok: false as const, message: INCONCLUSIVE }; // do not create the account const { data: created, error } = await supabaseAdmin.auth.admin.createUser({ email: String(form.get("email")), password: String(form.get("password")), }); if (error || !created.user) return { ok: false as const, message: "We could not create your account. Try again." }; await supabaseAdmin.from("profiles").upsert({ id: created.user.id, signer_id: signerId }); await saveAcceptances(confirmed.record, { signerId, userId: created.user.id, purpose: "account_signup" }); return { ok: true as const }; } // Called when the browser lost the response: look for the record on the existing session. export async function reconcileSignup(form: FormData) { const signerId = (await cookies()).get("esc_signer")?.value; if (!signerId) return { ok: false as const, message: INCONCLUSIVE }; const { data: ceremony } = await supabaseAdmin .from("esign_ceremonies") .select("session_id") .eq("signer_id", signerId) .eq("purpose", "account_signup") .order("created_at", { ascending: false }) .limit(1) .maybeSingle(); if (!ceremony) return { ok: false as const, message: INCONCLUSIVE }; const { data: session, error } = await esc.sessions.get(ceremony.session_id); if (error || !session.record_id) return { ok: false as const, message: INCONCLUSIVE }; return finishSignup(form, session.record_id); } ``` Test it: calling `finishSignup` with a made-up record ID must not create a user. ## 6. Webhook `app/api/esigncomply/webhook/route.ts` covers a browser that closed before step 5 ran. Read the raw body before anything parses it, verify the signature, and handle each delivery once, keyed by `webhook-id`. Route handlers run on the Node.js runtime by default; keep it that way. Return `200` within 5 seconds. Event types and payloads are listed under [Webhooks](https://esigncomply.com/docs/api/webhooks.md). ```ts import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; import { confirmRecord, saveAcceptances } from "@/lib/esign-confirm"; export async function POST(request: Request) { const rawBody = await request.text(); const { data: event, error } = await esc.webhooks.verify( rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!, ); if (error) return new Response("Invalid signature", { status: 400 }); // Deliveries are at-least-once. Handle each webhook-id once. const webhookId = request.headers.get("webhook-id")!; const { error: seen } = await supabaseAdmin .from("esign_webhook_events") .insert({ id: webhookId, type: event.type }); if (seen) return new Response(null, { status: 200 }); switch (event.type) { case "record.completed": { const signerId = event.data.signer_external_id; const purpose = event.data.purpose ?? "account_signup"; const confirmed = await confirmRecord({ recordId: event.data.record_id, signerId, purpose }); if (confirmed.ok) { const { data: profile } = await supabaseAdmin .from("profiles") .select("id") .eq("signer_id", signerId) .maybeSingle(); await saveAcceptances(confirmed.record, { signerId, userId: profile?.id ?? null, purpose }); } break; } case "record.disputed": await supabaseAdmin .from("esign_acceptances") .update({ disputed_at: new Date().toISOString() }) .eq("record_id", event.data.record_id); await notifyAdmin("A signer disputed a record", `Record ${event.data.record_id}`); break; case "signer.reacceptance_required": break; // the gate in step 7 handles it case "guidance.notice_published": { const { data: notice } = await esc.guidance.notices.get(event.data.notice_id); if (notice) await notifyAdmin(notice.title, notice.summary); break; // forward only; do not change application behavior } default: break; // ignore event types you do not recognize } return new Response(null, { status: 200 }); } async function notifyAdmin(subject: string, text: string) { // Send with your own email provider to your admin address. console.info(`[esigncomply] ${subject}: ${text}`); } ``` To receive test webhooks on `localhost`, run `npx esigncomply webhooks listen`. See the [CLI](https://esigncomply.com/docs/sdk/cli.md). ## 7. Gate and re-acceptance When you publish a version with `material_change: true`, earlier acceptances of that document become outstanding. In the authenticated layout, ask Esign Comply whether the signed-in user has anything outstanding, cache the answer for 5 minutes per user, and redirect to `/accept-updates` if so. That page runs the same ceremony as signup with `purpose: "policy_update"`, an unchecked checkbox labelled "I agree to the updated [document titles]", and a button labelled "Accept and continue". Offer "Log out" as the alternative. Do not offer "Remind me later". `lib/esign-gate.ts`: ```ts import "server-only"; import { esc } from "@/lib/esigncomply"; export interface OutstandingDocument { documentId: string; name: string; summaryOfChanges: string | null; } const TTL_MS = 5 * 60_000; const cache = new Map(); export async function outstandingDocuments(signerId: string): Promise { const hit = cache.get(signerId); if (hit && Date.now() - hit.at < TTL_MS) return hit.value; const { data, error } = await esc.signers.status(signerId); if (error) return hit?.value ?? []; // keep the last known answer; see the Re-acceptance guide const value = data.documents .filter((d) => d.outstanding) .map((d) => ({ documentId: d.document_id, name: d.name, summaryOfChanges: d.summary_of_changes })); cache.set(signerId, { at: Date.now(), value }); return value; } export function clearOutstanding(signerId: string) { cache.delete(signerId); } ``` `app/(app)/layout.tsx`: ```tsx import { redirect } from "next/navigation"; import { getSignedInUser } from "@/lib/auth"; // your Supabase Auth helper import { outstandingDocuments } from "@/lib/esign-gate"; export default async function AppLayout({ children }: { children: React.ReactNode }) { const user = await getSignedInUser(); if (!user) redirect("/login"); if ((await outstandingDocuments(user.signerId)).length > 0) redirect("/accept-updates"); return <>{children}; } ``` Keep `/accept-updates` outside this layout. The blocking page, its server actions, the response of the status call and the choice of what to do when the check fails are in [Re-acceptance](https://esigncomply.com/docs/guides/reacceptance.md). ## 8. NDA signing The NDA profile is L2 with a typed name, so the session's `required_steps` include `identity.verified` in addition to the document, notice, intent and final act. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). ### NDA server action `app/nda/[id]/actions.ts`: ```ts "use server"; import { headers } from "next/headers"; import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; import { confirmRecord, saveAcceptances } from "@/lib/esign-confirm"; import { getSignedInUser } from "@/lib/auth"; // your Supabase Auth helper export async function startNdaCeremony(ndaId: string, attempt: number) { const user = await getSignedInUser(); // { id, email, name, signerId } const h = await headers(); const origin = h.get("origin") ?? `https://${h.get("host")}`; const { data, error } = await esc.sessions.create( { profile: "prof_nda_9c2e", signer: { external_id: user.signerId, email: user.email, name: user.name, class: "business", country: "US" }, documents: [{ document: "doc_Nd55", version: "current" }], context: { url: `${origin}/nda/${ndaId}`, locale: "en-US", purpose: "nda" }, metadata: { nda_id: ndaId }, }, { idempotencyKey: `nda-${ndaId}-${user.signerId}-${attempt}` }, ); if (error) return { ok: false as const, message: error.message }; const pinned = data.documents[0]; await supabaseAdmin.from("esign_ceremonies").upsert({ session_id: data.id, signer_id: user.signerId, purpose: "nda", version_ids: [pinned.version_id], }); // The exact pinned version, to render inline. const content = await esc.documents.versions.getContent("doc_Nd55", pinned.version_id); if (content.error) return { ok: false as const, message: content.error.message }; return { ok: true as const, clientToken: data.client_token, apiUrl: data.api_url, versionId: pinned.version_id, html: content.data.html as string, signerName: user.name, }; } export async function finishNda(recordId: string) { const user = await getSignedInUser(); const confirmed = await confirmRecord({ recordId, signerId: user.signerId, purpose: "nda" }); if (!confirmed.ok) { return { ok: false as const, message: "We could not confirm whether your signature was recorded. Please wait while we check." }; } await saveAcceptances(confirmed.record, { signerId: user.signerId, userId: user.id, purpose: "nda" }); return { ok: true as const }; } ``` ### NDA signing component `app/nda/[id]/nda-signing.tsx`. Page layout, top to bottom: the full pinned NDA inline with download and print; email verification; then the assent container with the review line, the notice, the name field and the button. "Decline" sits outside the container. The review line is inside the assent container so that the captured notice text names the document ([CR-02](https://esigncomply.com/docs/conformance.md#cr-02)). ```tsx "use client"; import { useEffect, useRef, useState } from "react"; import { EsignComply, type Ceremony, type EsignComplyError } from "@esigncomply/browser"; import { finishNda, startNdaCeremony } from "./actions"; type Started = Extract>, { ok: true }>; export function NdaSigning({ ndaId, company }: { ndaId: string; company: string }) { const articleRef = useRef(null); const reviewRef = useRef(null); const assentRef = useRef(null); const nameRef = useRef(null); const submitRef = useRef(null); const ceremonyRef = useRef(null); const [started, setStarted] = useState(null); const [destination, setDestination] = useState(null); const [verified, setVerified] = useState(false); const [canSend, setCanSend] = useState(true); const [ready, setReady] = useState(false); const [done, setDone] = useState<{ verifyUrl: string | null } | null>(null); const [message, setMessage] = useState(null); const requestedRef = useRef(false); useEffect(() => { if (requestedRef.current) return; // one session per page load requestedRef.current = true; startNdaCeremony(ndaId, 1).then((res) => (res.ok ? setStarted(res) : setMessage(res.message))); }, [ndaId]); useEffect(() => { if (!started) return; let cancelled = false; let ceremony: Ceremony | undefined; (async () => { try { ceremony = await EsignComply.attach({ clientToken: started.clientToken, apiUrl: started.apiUrl }); if (cancelled) return ceremony.destroy(); ceremonyRef.current = ceremony; ceremony.on("change", ({ remainingSteps }) => { setReady(remainingSteps.length === 1 && remainingSteps[0] === "signature.applied"); }); await ceremony.presentDocument({ versionId: started.versionId, mode: "inline", container: articleRef.current }); await ceremony.reviewPresented({ container: reviewRef.current }); await ceremony.observeAssent({ region: assentRef.current, typedName: nameRef.current, submit: submitRef.current }); } catch (err) { if (!cancelled) setMessage((err as EsignComplyError).message); } })(); return () => { cancelled = true; ceremony?.destroy(); ceremonyRef.current = null; }; }, [started]); async function sendCode() { try { const v = await ceremonyRef.current!.verify.start({ method: "email_otp" }); setDestination(v.destination); // masked, for example d***@example.org setCanSend(false); setTimeout(() => setCanSend(true), 30_000); // allow resend after 30 seconds } catch (err) { setMessage((err as EsignComplyError).message); } } async function confirmCode(form: FormData) { try { const result = await ceremonyRef.current!.verify.confirm({ code: String(form.get("code")) }); if (result.status === "confirmed") setVerified(true); else setMessage(`That code did not match. Attempts left: ${result.attemptsRemaining}.`); } catch (err) { setMessage((err as EsignComplyError).message); // lockout ends the session } } async function sign(event: React.FormEvent) { event.preventDefault(); try { const result = await ceremonyRef.current!.complete(); const outcome = await finishNda(result.recordId); if (outcome.ok) setDone({ verifyUrl: result.verifyUrl }); else setMessage(outcome.message); } catch (err) { setMessage((err as EsignComplyError).message); } } if (!started) return

{message ?? "Loading the agreement."}

; if (done) { return (

Signed. A copy has been emailed to you by Esign Comply.{" "} {done.verifyUrl ? Verify this record : null}{" "} Download copy

); } return (

Download{" "}

{verified ? (

Email verified.

) : ( <> {destination ? (
) : null} )}

You are signing the Mutual NDA between {company} and {started.signerName} as {started.signerName}.

By typing your name and clicking Sign NDA, you agree to sign this agreement electronically and to be bound by it.

{message ?

{message}

: null}
); } ``` The name field starts empty and is never prefilled from the account. The SDK reads the name once, at the signing act, and does not send keystrokes. Do not render a signature image or a cursive font as the signature. ## 9. Language Disclose the languages you offer before contracting. The session locale is a default. Render the version the signer selects or reasonably understands, and record a choice that differs from the locale: ```ts await ceremony.languageSelected("de"); ``` If a mandatory local language is not available, do not start the ceremony. ## 10. Errors Browser SDK methods reject with a typed `EsignComplyError` that carries `code`, `rule`, `fix` and `docUrl`. Server SDK calls return `{ data, error }`. | Situation | What to do | |---|---| | `ceremony.complete()` rejected with a rule ID ([`conformance_failed`](https://esigncomply.com/docs/api/errors.md#conformance_failed), [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete)) | Show the message, keep the form, do not retry automatically. | | Network failure or a `5xx` | Show "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the same session before asking for another act. Never proceed without a record. | | [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired) | Create a new session with a new idempotency key and attach again. | | [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active) | The session is completed or cancelled. Read its `record_id` on the server, or create a new session. | | [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) | Wrong or expired code. After 5 wrong attempts the session ends: create a new one. | ## Verify before you report success 1. `npm run build` passes, and no file under `app/**` marked `"use client"` imports `esigncomply` or reads `ESIGNCOMPLY_API_KEY`. 2. Run `npx esigncomply check --url http://localhost:3000/signup` and `npx esigncomply check --url http://localhost:3000/nda/test`. Fix every finding marked `block`. List every finding marked `warn`. 3. Confirm by test that submitting with the box unchecked does nothing, and that calling `finishSignup` with a made-up record ID does not create a user. 4. Open the test record in the dashboard: it shows what was observed, what was asserted, and the conformance findings. Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable. ## Your obligations and recommendations A generated prompt also lists duties that the selected rule packs identify for your company, and practices Esign Comply recommends. Esign Comply lists them and does not perform, monitor, or verify them. Examples for this flow: letting EU and UK consumers correct input errors before an order, keeping your own copy of records for any period another law requires, and notifying users in advance of a material terms update. Read them for your profile with the [Guidance API](https://esigncomply.com/docs/api/guidance.md), and see [Supplements](https://esigncomply.com/docs/guides/supplements.md) for the optional reports you can file about them. --- # Server confirmation Source: https://esigncomply.com/docs/guides/server-confirmation Markdown: https://esigncomply.com/docs/guides/server-confirmation.md Section: Guides > Confirm every record on your server with a secret key or a verified webhook before your application grants access. `POST /v1/sessions/{id}/complete` answers the signer's browser. Your server must not trust that answer. A browser can be scripted, a response can be replayed, and a record ID can be made up. Before your application creates an account, unlocks a feature, or shows "signed", your server confirms the record itself. There are two ways to confirm, and most integrations use both: | Way | When it runs | Use it for | |---|---|---| | `GET /v1/records/{id}` with a secret key | In the request that follows the signing act | The normal path: the signer is waiting | | The `record.completed` webhook | When the record is written and its receipt is signed | The backstop: the browser closed or lost its connection before your server heard about the record | ## What to check Compare the record with state your server owns. Save that state when you create the session: the signer's external ID and the `version_id` of every entry in the session's `documents`. | Check | Rule | |---|---| | The call succeeded | No `error`. A made-up ID, a record from another domain or environment, and a voided record all return [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found). | | `status` | One of `recorded`, `timestamped`, `anchored`. | | `livemode` | What you expect for this deployment: `true` in production, `false` everywhere else. A test record must never unlock production access. | | `signer.external_id` | Equals the signer ID your server holds for this user or signup. | | `documents[].version_id` | Exactly the set of versions the session pinned. Not a subset, not an older version. | Do not use anything else the browser sends. The only value your server takes from the browser is the record ID, and it treats that as a claim to check. A record whose `status` is `disputed` exists and is sealed, and the signer has since used "This was not me" on the receipt. That happens after completion, so it does not appear in the first confirmation. Decide in your own policy what a dispute means for access. Esign Comply records the dispute and does not adjudicate it. ## Confirm with the server SDK Server SDK calls return `{ data, error }` and do not throw. ```ts import "server-only"; import { esc } from "@/lib/esigncomply"; const SEALED = new Set(["recorded", "timestamped", "anchored"]); export async function confirmRecord(input: { recordId: string; // from the browser: untrusted expectedSignerId: string; // from your server expectedVersionIds: string[]; // saved when the session was created expectedLivemode: boolean; }) { const { data: record, error } = await esc.records.get(input.recordId); if (error) return { ok: false as const, reason: error.code }; const actual = record.documents.map((d) => d.version_id).sort(); const expected = [...input.expectedVersionIds].sort(); const ok = SEALED.has(record.status) && record.livemode === input.expectedLivemode && record.signer.external_id === input.expectedSignerId && actual.length === expected.length && actual.every((v, i) => v === expected[i]); return ok ? { ok: true as const, record } : { ok: false as const, reason: "record_mismatch" }; } ``` Call it from the server action or route that grants access: ```ts const confirmed = await confirmRecord({ recordId, expectedSignerId: signerId, expectedVersionIds: ceremony.version_ids, expectedLivemode: process.env.VERCEL_ENV === "production", }); if (!confirmed.ok) { return { ok: false, message: "We could not confirm whether your acceptance was recorded. Please wait while we check." }; } // Only now grant access, and store confirmed.record.id and confirmed.record.receipt in your own table. ``` ## Confirm with fetch The same check without the SDK: ```ts const res = await fetch(`https://esigncomply.com/v1/records/${encodeURIComponent(recordId)}`, { headers: { Authorization: `Bearer ${process.env.ESIGNCOMPLY_API_KEY}` }, cache: "no-store", }); if (!res.ok) throw new Error("Esign Comply confirmation failed"); const record = await res.json(); const actual = record.documents.map((d: { version_id: string }) => d.version_id).sort(); if ( !["recorded", "timestamped", "anchored"].includes(record.status) || record.signer.external_id !== expectedSignerId || record.livemode !== expectedLivemode || JSON.stringify(actual) !== JSON.stringify([...expectedVersionIds].sort()) ) { throw new Error("Unexpected record"); } ``` ## What the key can read `GET /v1/records/{id}` works with every key permission. A `recording_access` key, the default for an application, receives the reduced view below: enough for confirmation and nothing that would let a leaked key export evidence. `full_access` and `read_only` keys receive the full record. See the [Records API](https://esigncomply.com/docs/api/records.md). ```json { "object": "record", "id": "rec_Z4m8", "livemode": false, "status": "recorded", "signed_at": "2026-11-21T15:03:20.291Z", "signature_level": "simple", "assurance_level": "L1", "capture_mode": "direct", "signer": { "external_id": "user_7c1d" }, "documents": [ { "document_id": "doc_8Hq2", "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." }, { "document_id": "doc_Pv71", "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." } ], "record_hash": "sha256:5be7...", "receipt": "eyJhbGciOiJFUzI1NiIs...", "verify_url": "https://esigncomply.com/verify/rec_Z4m8", "seal": { "timestamp": "pending", "anchor": "pending", "ledger_seq": 18244 }, "metadata": { "plan": "pro" }, "quota_locked": false } ``` Store `record.id` and `record.receipt` in your own database. The receipt is a compact signed token that names the record hash. You can present it later to [`POST /v1/verify`](https://esigncomply.com/docs/api/verification.md) or check it offline. See [Verification](https://esigncomply.com/docs/concepts/verification.md). ## Confirm from the webhook `record.completed` is sent once the record is durably written and its receipt is signed. Verify the signature on the raw body first, handle each `webhook-id` once, then run the same comparison. The payload carries IDs and status, and no personal data beyond the signer's external ID. ```json { "object": "event", "id": "whe_8Rt4", "type": "record.completed", "api_version": "2026-11-21", "livemode": false, "created_at": "2026-11-21T15:03:20.412Z", "data": { "record_id": "rec_Z4m8", "session_id": "ses_5nWq", "signer_external_id": "user_7c1d", "status": "recorded", "record_hash": "sha256:5be7...", "signed_at": "2026-11-21T15:03:20.291Z", "assurance_level": "L1", "signature_level": "simple", "documents": [ { "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." }, { "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." } ], "purpose": "account_signup" } } ``` ```ts export async function POST(request: Request) { const rawBody = await request.text(); const { data: event, error } = await esc.webhooks.verify( rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!, ); if (error) return new Response("Invalid signature", { status: 400 }); if (event.type === "record.completed") { const ceremony = await loadCeremonyBySession(event.data.session_id); // your server-owned state const versions = event.data.documents.map((d: { version_id: string }) => d.version_id).sort(); const matches = ceremony !== null && event.livemode === (process.env.VERCEL_ENV === "production") && event.data.signer_external_id === ceremony.signer_id && JSON.stringify(versions) === JSON.stringify([...ceremony.version_ids].sort()); if (matches) await grantAccess(ceremony, event.data.record_id); // idempotent upsert } return new Response(null, { status: 200 }); } ``` A verified webhook already comes from Esign Comply, so the handler does not need a second API call to trust it. Fetch the record anyway when you need fields the payload does not carry, such as `document_id`. Signature verification, retries and the full event list are under [Webhooks](https://esigncomply.com/docs/api/webhooks.md). ## Records that are still being sealed The record is written and the receipt is signed before the completion response returns. One exception: if the signing key service cannot be reached, the record is still committed, the response carries `status: "pending_seal"` and `receipt: null`, and the receipt is signed within 60 seconds. `record.completed` fires only once the receipt exists. For a `pending_seal` record, the default is to wait: show a short "Finishing up" state and continue when the webhook arrives or when `GET /v1/records/{id}` returns `recorded`. You may treat `pending_seal` as provisional access at your own choice. The external timestamp (target: within 60 seconds) and the public anchor follow asynchronously and move the status to `timestamped` and `anchored`. You do not need to wait for them before granting access. ## When the result is inconclusive A network failure, a `5xx`, or a mismatch on any check means your server does not know that a matching record exists. In that case: 1. Do not grant access and do not create the account. 2. Show: "We could not confirm whether your acceptance was recorded. Please wait while we check." 3. Reconcile the existing session before asking the signer to act again. Read it with the secret key: ```ts const { data: session, error } = await esc.sessions.get(sessionId); if (!error && session.status === "completed" && session.record_id) { // The act was recorded. Confirm session.record_id as above. } ``` If the session is still active, the signer can repeat the final act on the same session: the browser SDK sends the completion with the same idempotency key, so a repeat never creates a second record. If the session is `expired` or `cancelled`, create a new one. The browser SDK already does part of this. When the completion response is lost, `ceremony.complete()` looks for the record on the session and resolves with `status: "unknown"` and the record ID. Your server confirms in every case, whatever the browser reports. ## Test it - Call your confirmation code with a made-up record ID. It must not grant access. - Call it with the ID of a real test record that belongs to a different signer. It must not grant access. - In production, call it with a test record ID. The `livemode` check must refuse it. - Run `npx esigncomply check --url http://localhost:3000/signup`. The active checker posts a forged success to your application and expects access to stay blocked. See the [CLI](https://esigncomply.com/docs/sdk/cli.md). For the complete flow in a Next.js application, see [Next.js with Supabase](https://esigncomply.com/docs/guides/nextjs.md). --- # Test mode Source: https://esigncomply.com/docs/guides/test-mode Markdown: https://esigncomply.com/docs/guides/test-mode.md Section: Guides > What test keys can do, where they work, the reserved test signer addresses, how test records differ from live ones, and the limits of the Free and Starter plans. Test mode runs the whole product without a registered domain, a card, or an approval step. A test key creates sessions on `localhost`, the browser SDK reports the ceremony, and the record goes through the same sealing pipeline as a live one, on a separate test ledger. Use it to build the integration, to run the conformance checker, and in continuous integration. ## Test keys Test keys start with `esc_test_us_` or `esc_test_eu_`. Create one in the dashboard. The key is shown once: store it as a server environment variable. ```bash ESIGNCOMPLY_API_KEY=esc_test_us_... ``` A test key and a live key use the same API host and the same endpoints. The key decides the environment. Objects are separate per environment: a document, profile or record created with a test key does not exist for a live key, and reading it with one returns [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found). Every object carries `livemode: false` or `livemode: true`. Every plan includes test mode, the Free plan too. Live keys (`esc_live_...`) need a verified domain. They do not need a paid plan: the Free plan includes 10 live signature events per calendar month. See [Register a domain](https://esigncomply.com/docs/guides/domains.md), [Free plan limits](#free-plan-limits) and [Starter limits](#starter-limits). ## Where test keys work Live keys accept browser calls only from the verified registered domain. Test keys accept them from: | Origin | Notes | |---|---| | `localhost` and `*.localhost` | Any port | | `127.0.0.1` and `[::1]` | Any port | | The registered domain and its subdomains | Only if the organization has registered one | | Preview hosts you list | Up to 25 hosts, set under Domains in the dashboard or with `PATCH /v1/domains/{id}` (`test_origins`). An entry also covers its subdomains. | Two checks use this list: - `context.url` on `POST /v1/sessions`. In test mode it is optional. If you send it, it must be on the list, otherwise the call returns [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch). - The `Origin` header of every browser call made with a client token. An origin outside the list returns [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch). A test-mode request with no `Origin` header is accepted, so scripts, `curl` and test runners can drive a ceremony with the client token. In live mode a browser endpoint refuses a request without an origin. To use a hosted preview, for example a deployment URL of an AI app builder, add its host to the list first. See [AI app builders](https://esigncomply.com/docs/guides/ai-builders.md). ## What is the same and what differs | | Test | Live | |---|---|---| | Ceremony, required steps, events | Full | Full | | Sealing | Full pipeline on a separate test ledger, signed with a test key | Production ledger and sealing key | | Evidence reports and certificates | Watermarked "TEST", with the statement that no attestation is given | No watermark | | Certificates | Free on every plan; not anchored publicly | Paid plans only, charged per plan | | Verification | A test receipt verifies only against the test key and is reported as a test record | Live result | | Conformance findings | Reported, never block | A failed blocking rule refuses the record | | Rules evaluated | The latest guidance release, with every record condition enforced | The profile's adopted baseline; newer conditions run in advise | | State packs awaiting counsel review | Applied, labelled research draft | Not applied | | Receipts and email codes | Delivered only to verified email addresses of your team | Delivered to the signer | | Signature events | Not counted against plan quota | Counted | | Retention | Deleted after 30 days | Per plan and retention schedule | Test records are never copied to live. Test documents, profiles and webhook endpoints can be copied to live from the dashboard when you go live. ## Findings never block In live mode a failed blocking rule stops the record from being sealed. In test mode it does not. The API still evaluates every rule and reports every finding in three places, so that you or your AI coding tool can read the finding and repair the page: - In the API response to each ceremony event, under `conformance.findings`. - In the browser console, with the rule ID, a fix and a documentation link. - In the dashboard, on the test record. ```json { "object": "event", "id": "evt_91xA", "type": "document.presented", "tag": "observed", "server_time": "2026-11-21T15:03:01.377Z", "sequence": 3, "conformance": { "status": "warn", "rules_version": "2026.11.2", "findings": [ { "rule": "CR-05", "status": "warn", "state": "enforce", "message": "Document link contrast against surrounding text is 1.5 to 1; at least 3 to 1 is expected, in addition to any underline.", "fix": "Give document links a colour that differs from the surrounding text by a contrast ratio of at least 3 to 1, and keep them underlined.", "measurement": { "contrast_ratio": 1.5, "underlined": true, "font_px": 14, "link_visible": true }, "maps_to": ["US-11"], "event_type": "document.presented", "version_id": "dv_3kT9" } ] }, "remaining_steps": ["document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied"], "session_status": "in_progress" } ``` In test mode the response lists passing findings as well. In live mode it lists only those that did not pass. Required steps are a different matter. A missing step returns [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) in both environments, and a step sent too early returns [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order). Findings are advisory statements about measurable design facts. They are not a statement that a flow is lawful or enforceable. The rules are listed under [Conformance](https://esigncomply.com/docs/conformance.md). ## Test mode runs the latest rules A live profile enforces only the record conditions it has adopted. Conditions that arrive later run in advise until you adopt them, so a guidance release cannot stop a working integration. Test mode does the opposite on purpose: it evaluates the latest release with every condition enforced, including state-specific required steps. You see what adoption would require before it reaches live traffic. See [Guidance](https://esigncomply.com/docs/guides/guidance.md) and [Compatibility](https://esigncomply.com/docs/concepts/compatibility.md). State packs that have not yet been reviewed by counsel admitted in that state are research drafts. They apply in test mode only. ## Reserved test signer addresses Five signer addresses force an outcome so that you can test each path without waiting for a real person. They work only with a test key. Pass one as `signer.email` when you create the session. | `signer.email` | What it forces | Webhook | |---|---|---| | `signer+ok@test.esigncomply.com` | Email verification accepts the code `000000`. | None beyond the normal ones | | `signer+wrongcode@test.esigncomply.com` | Email verification never succeeds, whatever code is entered. After 5 attempts the session ends. | `session.cancelled` | | `signer+bounce@test.esigncomply.com` | The signer receipt bounces. | `record.copy_bounced` | | `signer+dispute@test.esigncomply.com` | A dispute is filed 10 seconds after sealing. The record status becomes `disputed`. | `record.disputed` | | `signer+withdraw@test.esigncomply.com` | Consent to electronic records is withdrawn 10 seconds after sealing. | `consent.withdrawn` | No message is sent to a reserved address. ```bash curl https://esigncomply.com/v1/sessions \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: nda-test-ok-1" \ -d '{ "profile": "prof_nda_9c2e", "signer": { "external_id": "user_7c1d", "email": "signer+ok@test.esigncomply.com", "name": "Dana Whitfield", "class": "business", "country": "US" }, "documents": [{ "document": "doc_Nd55", "version": "current" }], "context": { "url": "http://localhost:3000/nda/test", "locale": "en-US", "purpose": "nda" } }' ``` ## Codes and receipts in test mode Test receipts and one-time codes are delivered only to verified email addresses of members of your organization. Any other address receives nothing. So that automation can still finish an L2 ceremony, the API returns the code in the verification response when the message was not delivered: ```json { "object": "verification", "id": "ver_2bQd", "method": "email_otp", "destination": "d***@example.org", "status": "pending", "expires_at": "2026-11-21T15:13:01.000Z", "attempts_remaining": 5, "sends_remaining": 2, "delivered": false, "code": "418205", "test_note": "Test mode: the message was not delivered because the address is not a verified team address. The code is returned here for automation." } ``` In the browser SDK the same value is `verification.code` on the result of `ceremony.verify.start()`. The field never appears in live mode. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). ## Test quotas and rate limits Test records are not signature events and never count against the live quota. Each plan has a monthly allowance of test-mode events: | Plan | Test-mode events per month | API rate limit per key | |---|---|---| | Free | 500 | 2 requests per second | | Starter | 5,000 | 10 requests per second | | Unlimited | 20,000 | 50 requests per second | | Enterprise | Contracted | Contracted (100 requests per second by default) | When the month's allowance is used, `POST /v1/sessions` returns [`test_quota_exceeded`](https://esigncomply.com/docs/api/errors.md#test_quota_exceeded) with a `Retry-After` header. The Free plan includes assurance levels L1 and L2. A profile at L3 needs the Unlimited plan in both environments. Space out calls in scripts on the Free plan: more than 2 requests per second per key returns [`rate_limit_exceeded`](https://esigncomply.com/docs/api/errors.md#rate_limit_exceeded). Ceremony calls from the browser are limited per session, not per key. ## Deletion after 30 days Test records, their events and their supplements are deleted 30 days after they are created. A deleted test record returns `not_found`. Do not store anything in test mode that you need to keep. ## Going live A test record never becomes live evidence. To record live, take three steps. There is no plan to choose and no checkout. 1. [Register and verify your domain](https://esigncomply.com/docs/guides/domains.md). 2. Add the organization's legal name, country and address under **Go live** in the dashboard. 3. Create a live key and set it only in your production environment. The customer terms and the data-processing agreement were accepted once, at sign-up, so there is no acceptance step here. An organization created before sign-up recorded the data-processing agreement is asked to accept it once on the Go live page, and that step needs the account owner in person. A paid plan is optional. The account owner chooses Starter or Unlimited on the Go live page or under Settings, Billing. Before you switch keys: - Create your documents and profiles in live mode, or copy them from test in the dashboard. - Make sure your [server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md) checks `livemode`, so a test record can never unlock production access. ## Free plan limits The Free plan records live. Its plan id in the API is `sandbox`. It needs no card. | | Free plan | |---|---| | Live signature events | 10 per calendar month (UTC) | | Verified domains | 1 per organization. A second live domain needs a paid plan. | | Test mode | Full: 500 test events per month, 2 requests per second per key | | Assurance levels | L1 and L2, with email codes | | Seats | 1 | | Webhook endpoints | 1 per environment | | Region | US | Free covers 10 live signatures a month. If you use all 10 in a month, the account locks until you upgrade to a paid plan. It does not unlock at the start of the next month. Past the limit, new live signatures can be refused, so upgrade before you get there. - **What counts.** Live signature events completed in the UTC calendar month. Test records never count. - **Under the limit.** An organization that stays under 10 in a month is never locked. Its count starts again at 00:00 UTC on the first of the next month, with 10 again. [`GET /v1/usage`](https://esigncomply.com/docs/api/account.md#get-usage) gives that time as `events.resets_at`. - **Emails.** Owners and admins get an email at 5, 8, 9 and 10 live signatures: 50%, 80%, 90% and 100% of the limit, once per allowance period. The [`usage.threshold_reached`](https://esigncomply.com/docs/api/webhooks.md#usage-and-conformance) webhook is sent at the same four points. One more email is sent if new live signatures start being refused. - **The lock.** At 10 the account locks. The dashboard then shows only the lock screen, the billing page and sign-out, in test mode too. The lock does not lift on its own, and a locked account gets no new allowance on the first of the month. Upgrading to a paid plan is the only thing that removes it. The lock is on the dashboard. It does not disable API keys. - **Refusal.** Past the limit, `POST /v1/sessions` in live mode can be refused with `402` [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted). A live deferred submission gets the same check. Sessions already created still complete. - **What to do.** Upgrade before you reach 10. Starter covers 2,000 live signature events a year. Unlimited has no limit. Read `events.used`, `events.remaining` and `events.locked` from `GET /v1/usage` to see where you stand. Records sealed now are never locked: the evidence report and the evidence package of a sealed record stay available through the API. Live records on Free are real records: an outside RFC 3161 timestamp, signed checkpoints, a public anchor, the public verification page, the signer copy by email, the evidence report and the evidence package. They are retained as on Starter. Test records on Free have a simulated timestamp, with no outside authority contacted, and the "TEST" watermark. They are deleted after 30 days. These need a paid plan: certificates for live records, L3 (Unlimited and above), SMS codes, more than 1 seat, more than 1 webhook endpoint, the EU region, bulk export and custodian-signed certifications. On Free, a certificate request or quote for a live record returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable), and so does a live session for a domain in the EU region. Test certificates stay free and watermarked on every plan. ## Starter limits Starter covers 2,000 live signature events a year. At 2,000 the account locks until you pay: upgrade to Unlimited, add an event pack, or renew. Past the limit, new live signatures can be refused, so upgrade before you get there. - **What counts.** Live signature events completed in the subscription year. A paid renewal starts a new year and a new count. - **Event packs.** A pack costs $100 and adds 1,000 events to the limit for the rest of the subscription year. The limit is 2,000 plus 1,000 for each pack bought that year. Add a pack under Settings, Billing in the dashboard. With automatic event packs switched on, a pack is bought when the limit is reached, so the account does not lock, and the emails then apply to the new limit. At 10 packs in a year the subscription converts to Unlimited for the rest of that year at no further charge. - **Emails.** Owners and admins get an email at 50%, 80%, 90% and 100% of the limit, once per allowance period: 1,000, 1,600, 1,800 and 2,000 events when no pack has been bought. The `usage.threshold_reached` webhook is sent at the same four points. One more email is sent if new live signatures start being refused. - **The lock.** At 100% the account locks. The dashboard then shows only the lock screen, the billing page and sign-out, in test mode too. The lock does not lift on its own. Paying removes it: upgrade to Unlimited, add an event pack, or pay for renewal. The lock is on the dashboard. It does not disable API keys. - **Refusal.** Past the limit, `POST /v1/sessions` in live mode can be refused with `402` [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted). A live deferred submission gets the same check. Sessions already created still complete. Unlimited and Enterprise have no limit and never lock. --- # Register a domain Source: https://esigncomply.com/docs/guides/domains Markdown: https://esigncomply.com/docs/guides/domains.md Section: Guides > How the registered domain is computed, how to verify it by DNS or by file, what each status means, and what happens when verification lapses. Live recording is tied to one verified domain. The record names your organization and the domain where the signing happened, and the API accepts live browser calls only from that domain. Test mode needs none of this: test keys work on `localhost` before you register anything. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). Going live takes three steps: 1. Register and verify the domain. 2. Add your organization's legal name, country and address under **Go live** in the dashboard. 3. Create a live key. There is no plan to choose and no checkout. The Free plan includes 10 live signature events per calendar month on one verified domain. See [Free plan limits](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits). A paid plan is optional: the account owner chooses Starter or Unlimited on the Go live page or under Settings, Billing. You accepted the customer terms and the data-processing agreement once, at sign-up. An organization created before sign-up recorded the data-processing agreement is asked to accept it once on the Go live page, and that step needs the account owner in person. ## One subscription, one domain | Rule | What it means | |---|---| | One organization, one domain | A subscription belongs to exactly one organization and one registered domain. The organization's legal name is printed on evidence reports and certificates. | | Registrable domain | "Domain" means the registrable domain under the Public Suffix List, for example `example.com` or `example.co.uk`. | | Subdomains included | `app.example.com`, `www.example.com` and every other subdomain are covered. | | One active subscription per domain | A second registration of the same domain returns [`domain_already_registered`](https://esigncomply.com/docs/api/errors.md#domain_already_registered). | | Several sites | Websites on different registrable domains need one subscription each. An organization can hold several subscriptions. Each has its own keys, quota, ledger, region and invoice. | | Platform hosts | A host on a shared platform suffix, such as `myapp.vercel.app`, registers as its own domain and verifies by file. | | Agencies | An agency building for clients needs one subscription per client domain, owned by the client's organization. | | Enterprise | A contract may cover several domains of one legal entity and named affiliates, priced per domain. | Once the domain is verified: - Live keys work. Before that, a live key returns [`domain_not_verified`](https://esigncomply.com/docs/api/errors.md#domain_not_verified). - Live browser calls are accepted only from origins within the registered domain. - Live session creation must declare a `context.url` within the registered domain. Anything else returns [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch). ## What you enter and what is registered Type a host or a URL. Esign Comply computes the registrable domain and shows it before you confirm. | You enter | Registered | Method | |---|---|---| | `app.example.com` | `example.com` and every subdomain | DNS | | `https://www.example.co.uk/signup` | `example.co.uk` and every subdomain | DNS | | `myapp.vercel.app` | `myapp.vercel.app` on its own | File | | `localhost`, `127.0.0.1` | Cannot be registered. Test keys already work there. | None | A platform host is registered on its own because you do not control DNS for the suffix. If you later move to a custom domain, that is a domain change. ## Choose the region Choose the data region when you register the domain. It is fixed for that domain. | Region | API base URL | Key prefixes | |---|---|---| | US (`us-east-1`) | `https://esigncomply.com/v1` | `esc_test_us_`, `esc_live_us_` | | EU (`eu-central-1`) | `https://api.eu.esigncomply.com/v1` | `esc_test_eu_`, `esc_live_eu_` | The region sets where evidence is stored and which API host the keys use. A key sent to the other region's host returns [`region_mismatch`](https://esigncomply.com/docs/api/errors.md#region_mismatch) with the correct host. An EU region does not mean that all processing stays in the EU. See [Compliance: Europe](https://esigncomply.com/compliance/europe). The Free plan records live in the US region only. A live session on Free for a domain in the EU region returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). Live recording in the EU region needs a paid plan. ## Verify by DNS Add one TXT record at your DNS provider. The record goes on the registrable domain, whichever subdomain you entered. An AI agent that has no access to your DNS provider asks you to add this one record. ```text Type: TXT Name: _esigncomply Value: esc-verify= ``` The full record name is `_esigncomply.example.com`. Some providers want the short name `_esigncomply`, others the full name. The token is shown in the dashboard and returned by the API as `verification.value`. Check it from a terminal: ```bash dig +short TXT _esigncomply.example.com ``` ```text "esc-verify=" ``` Esign Comply queries two independent public resolvers and both must return the exact value. A record that one resolver has not picked up yet keeps the domain `pending`, so allow for propagation. Keep the record in place after verification. It is re-checked every day. ## Verify by file Platform hosts verify with a file, because you cannot add DNS records under a shared suffix. This method is offered automatically for hosts under: `vercel.app`, `lovable.app`, `netlify.app`, `replit.app`, `repl.co`, `bolt.host`, `pages.dev`, `workers.dev`, `web.app`, `firebaseapp.com`, `onrender.com`, `fly.dev`, `herokuapp.com`, `github.io`, `railway.app`, `v0.app`, `webcontainer.io` and `stackblitz.io`. Serve the token as plain text at: ```text https://myapp.vercel.app/.well-known/esigncomply.txt ``` The file contains the token shown in the dashboard and returned by the API as `verification.content`. The check fetches the URL over HTTPS, does not follow redirects, expects status `200`, and looks for the token in the body. In a Next.js application, add a static file: ```text public/.well-known/esigncomply.txt ``` or a route handler at `app/.well-known/esigncomply.txt/route.ts`, which keeps the token out of the repository: ```ts export function GET() { return new Response(process.env.ESIGNCOMPLY_DOMAIN_TOKEN ?? "", { headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" }, }); } ``` Make sure the path is not behind authentication and is not redirected, for example from the bare host to `www`. ## Statuses | Status | Meaning | What to do | |---|---|---| | `not_started` | No domain has been entered. | Register a domain. Test mode works without one. | | `pending` | The record or file has not been found yet. Checks are running. | Add the TXT record or the file, then wait or trigger a check. | | `verified` | The record or file was found. | Add your organization's details under Go live and create a live key. Keep the record in place. | | `failed` | Nothing was found within 72 hours. | Fix the record or file and trigger a check. | | `lapsed` | The domain was verified and the daily check has now failed three times in a row. | Restore the record or file within 14 days. | ## When checks run - Every minute for the first hour after registration. - Every 15 minutes after that, up to 72 hours. - Once a day from then on, including after verification. You do not have to wait for the schedule. Use "Check now" in the dashboard, or call `POST /v1/domains/{id}/verify`, to run a check at once. When the status changes to `verified`, the organization's owners get an email and the `domain.verified` webhook is sent. ## When verification lapses A verified domain is re-checked every 24 hours. Three consecutive failures set the status to `lapsed`. From that moment: 1. Owners are warned in the dashboard and by email, and the `domain.verification_lapsed` webhook is sent with `live_recording_until`. 2. Live recording continues for 14 days. Sessions are created and records are sealed as before. 3. After 14 days, `POST /v1/sessions` with a live key returns [`domain_not_verified`](https://esigncomply.com/docs/api/errors.md#domain_not_verified) until verification is restored. Existing records are not affected at any point. To restore verification, put the TXT record or the file back. The next check sets the status to `verified` again. ```json { "object": "event", "id": "whe_8Rt4", "type": "domain.verification_lapsed", "api_version": "2026-11-21", "livemode": true, "created_at": "2027-02-03T04:17:09.220Z", "data": { "domain_id": "dom_4Kx9", "domain": "example.com", "live_recording_until": "2027-02-17T04:17:09.101Z" } } ``` Domain events are live-mode events. Subscribe a live webhook endpoint to receive them. See [Webhooks](https://esigncomply.com/docs/api/webhooks.md). ## Change the domain A subscription can change its registered domain once per 12 months without contacting support. Moving from a platform host to a custom domain counts as a change. - Registering the new domain issues a new token and sets the status to `pending`. - Live keys return `domain_not_verified` until the new domain is verified. Publish the new record first and trigger a check right after registering, so the gap is short. - Records already sealed stay bound to the domain that was registered when they were sealed. ## If the domain is already registered If another organization has registered the domain, registration returns [`domain_already_registered`](https://esigncomply.com/docs/api/errors.md#domain_already_registered). If you own the domain, start a claim from the dashboard and publish the verification record shown there. A successful DNS challenge notifies the current owner, and the registration transfers after 7 days unless the current owner verifies again. ## Use the API Everything on the domain screen has an API call. All of them need a secret key with `full_access`. A key is bound to one domain, so these calls act on the key's own domain. Field details are in the [Account API](https://esigncomply.com/docs/api/account.md). | Method and path | Purpose | |---|---| | `GET /v1/domains` | Find the domain ID for this key | | `POST /v1/domains` | Register a domain and choose the region | | `GET /v1/domains/{id}` | Read the status and the verification instructions | | `POST /v1/domains/{id}/verify` | Run a verification check now | | `PATCH /v1/domains/{id}` | Set `test_origins`, the preview hosts on which test keys work | **Example request** ```bash curl https://esigncomply.com/v1/domains \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "app.example.com", "region": "us" }' ``` **Example response** `201 Created` ```json { "object": "domain", "id": "dom_4Kx9", "domain": "example.com", "entered_host": "app.example.com", "region": "us", "status": "pending", "verification": { "method": "dns", "type": "TXT", "name": "_esigncomply.example.com", "host": "_esigncomply", "value": "esc-verify=" }, "registered_at": "2026-11-21T15:10:02.118Z", "verified_at": null, "last_checked_at": null, "lapsed_at": null, "test_origins": [], "api_url": "https://esigncomply.com/v1", "created_at": "2026-11-21T14:58:40.006Z" } ``` For a platform host the `verification` object describes the file instead: ```json { "method": "file", "url": "https://myapp.vercel.app/.well-known/esigncomply.txt", "content": "" } ``` Then wait for the schedule, or trigger a check. The response is the domain object plus the outcome of that check: ```bash curl -X POST https://esigncomply.com/v1/domains/dom_4Kx9/verify \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" ``` ```json { "object": "domain", "id": "dom_4Kx9", "domain": "example.com", "status": "pending", "check": { "ok": false, "method": "dns", "detail": { "name": "_esigncomply.example.com", "expected": "esc-verify=", "cloudflare": ["esc-verify="], "google": [], "cloudflare_ok": true, "google_ok": false } } } ``` The response is shortened here. In this example one resolver has the record and the other does not yet, so the domain stays `pending`. To let test keys work on preview hosts in addition to `localhost`, list the hosts (25 at most). See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). ```bash curl -X PATCH https://esigncomply.com/v1/domains/dom_4Kx9 \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "test_origins": ["preview.example.dev", "myapp-git-main.vercel.app"] }' ``` ## One-click DNS setup (Planned) > **Planned.** One-click DNS setup through Domain Connect, for DNS hosts that support it, is not available yet. Add the TXT record by hand. ## Mobile applications (Planned) > **Planned.** Native mobile applications will be covered when the registered domain publishes an association file that names the application (`apple-app-site-association` for iOS, `assetlinks.json` for Android). This is not available yet. --- # Consumer e-consent Source: https://esigncomply.com/docs/guides/consumer-econsent Markdown: https://esigncomply.com/docs/guides/consumer-econsent.md Section: Guides > Build the ESIGN consumer consent steps (disclosure, access demonstration, consent) with the browser SDK, and handle withdrawal and paper-copy requests. Where a law requires that information be given to a consumer in writing, the U.S. ESIGN Act lets you give it electronically only after the consumer has received certain disclosures and has consented in a way that shows they can open the electronic format ([15 U.S.C. § 7001(c)](https://www.law.cornell.edu/uscode/text/15/7001)). Esign Comply has three ceremony steps for this. You build the screen. The SDK records what the screen showed and what the consumer did. Whether your flow needs these steps is a question for your counsel. Typical cases are legally required notices, statements or disclosures that you plan to deliver by email or in your application instead of on paper. An ordinary terms acceptance at signup usually does not need them. ## The three steps | Step | Event | SDK call | What Esign Comply records | |---|---|---|---| | S3 Disclosure | `disclosure.presented` | `ceremony.presentDisclosure({ container })` | A hash of the disclosure text as shown, the headings found in it, and how long it was on screen | | S4 Access demonstration | `access.demonstrated` | `ceremony.accessSample()`, then `ceremony.demonstrateAccess({ code })` | That the code the consumer typed matched the code inside the sample document | | S5 Consent | `econsent.given` | `ceremony.giveEConsent({ checkbox })` | The control type, its label text, its initial state, and whether a real user action changed it | The steps run in this order, before the documents and the assent control. The API refuses a step that arrives early with [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order), and refuses to complete a session that lacks one with [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete). The matching conformance rule is [CR-16](https://esigncomply.com/docs/conformance.md#cr-16). Esign Comply records measured events. It does not record that a person read or understood the disclosure. ## When the steps are required Two things switch them on: 1. The profile has `consumer_econsent: true`. 2. The session's signer is a consumer: `signer.class` is `"consumer"`, or is not sent. The Federal pack (`US-FED`) carries the rules behind them (US-21 to US-24). Do not hard-code the steps. Read `required_steps` from the session and build the consent screen only when it lists them. Create the profile on your server: ```bash curl https://esigncomply.com/v1/profiles \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Electronic delivery of notices", "jurisdictions": ["US-FED"], "method": "checkbox", "assurance_level": "L1", "consumer_econsent": true }' ``` A session created with that profile for a consumer returns: ```json { "object": "session", "id": "ses_5nWq", "status": "created", "required_steps": [ "client.attached", "disclosure.presented", "access.demonstrated", "econsent.given", "document.presented:dv_3kT9", "notice.captured", "intent.captured", "signature.applied" ], "required_strings": [ { "slot": "econsent_heading", "block": "us.consumer_econsent", "rule": "US-21", "kind": "verbatim", "text": "Consent to receive records electronically", "label": "us.consumer_econsent heading", "check": false }, { "slot": "econsent_subheadings", "block": "us.consumer_econsent", "rule": "US-21", "kind": "elements", "elements": ["What you are agreeing to", "..."], "label": "us.consumer_econsent heading: fixed sub-headings", "check": false }, { "slot": "econsent_access_demonstration", "block": "us.consumer_econsent", "rule": "US-23", "kind": "verbatim", "text": "To confirm you can open the records we will send, open this sample and enter the code shown inside it.", "label": "us.consumer_econsent access demonstration", "check": false } ] } ``` The response is shortened here. See the [Sessions API](https://esigncomply.com/docs/api/sessions.md) for every field. ## The fixed headings The disclosure uses one fixed heading and seven fixed sub-headings, in this order. Render them verbatim. The session returns them in `required_strings`, so you can read them at run time instead of copying them. Heading: ```text Consent to receive records electronically ``` Sub-headings: ```text What you are agreeing to Whether this consent covers one transaction or all records Your right to receive paper copies How to request a paper copy after consenting, and any fee How to withdraw consent, and any conditions, consequences, or fees How to update your contact details What you need to access and keep the records ``` The text under each sub-heading is yours to write. It states your own practice: which records you will send, how a person asks for paper and what it costs, how they withdraw, and the hardware and software they need to open and keep the records. Esign Comply stores what you showed and does not alter, summarize or review it. The access demonstration uses this sentence, also verbatim: ```text To confirm you can open the records we will send, open this sample and enter the code shown inside it. ``` ## Build the screen Create the session on your server and attach the SDK as in the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). Then render the consent block before the documents and the assent control. This component takes the attached `ceremony`. ```tsx "use client"; import { useEffect, useRef, useState } from "react"; import type { Ceremony, EsignComplyError } from "@esigncomply/browser"; export function ElectronicRecordsConsent({ ceremony, onDone }: { ceremony: Ceremony; onDone: () => void }) { const disclosureRef = useRef(null); const consentRef = useRef(null); const [sampleHtml, setSampleHtml] = useState(null); const [demonstrated, setDemonstrated] = useState(false); const [message, setMessage] = useState(null); useEffect(() => { // S3: record the disclosure as the page shows it. ceremony.presentDisclosure({ container: disclosureRef.current }).catch((err: EsignComplyError) => setMessage(err.message)); // S5: watch the checkbox. The promise resolves once the consumer has ticked it and the step is recorded. ceremony .giveEConsent({ checkbox: consentRef.current }) .then(onDone) .catch((err: EsignComplyError) => setMessage(err.message)); }, [ceremony, onDone]); async function openSample() { try { const sample = await ceremony.accessSample(); // { format, instruction, html } setSampleHtml(sample.html); } catch (err) { setMessage((err as EsignComplyError).message); } } async function submitCode(form: FormData) { try { await ceremony.demonstrateAccess({ code: String(form.get("code") ?? "") }); // S4 setDemonstrated(true); setMessage(null); } catch (err) { const error = err as EsignComplyError; setMessage(error.code === "verification_failed" ? "That code does not match the one in the sample. Open the sample and try again." : error.message); } } return (

Consent to receive records electronically

What you are agreeing to

{/* your text */}

Whether this consent covers one transaction or all records

{/* your text */}

Your right to receive paper copies

{/* your text */}

How to request a paper copy after consenting, and any fee

{/* your text */}

How to withdraw consent, and any conditions, consequences, or fees

{/* your text */}

How to update your contact details

{/* your text */}

What you need to access and keep the records

{/* your text */}

To confirm you can open the records we will send, open this sample and enter the code shown inside it.

{sampleHtml ?
: null}
{message ?

{message}

: null}
); } ``` Rules for this screen: - The consent checkbox starts unchecked and is ticked only by the consumer ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)). It is its own control. Do not reuse the terms checkbox for it. - Call `giveEConsent` once, when the checkbox renders. Do not call it from the checkbox's change handler: the SDK watches the control and records the tick. - The consumer types the code. Never read it out of the sample in code, prefill the field, or submit it for them. - The sample HTML comes from Esign Comply and contains a short notice and the code. If the session includes a PDF document, `format` is `"pdf"`, which tells you the delivery format the consumer is demonstrating access to. - Keep the disclosure on the page while the consumer decides. In standard capture the SDK measures how long it was on screen. After `econsent.given` is recorded, continue with `presentDocument` and `observeAssent`. Disable your final button until `ceremony.remainingSteps()` contains only `"signature.applied"`. ## What each call does **`ceremony.presentDisclosure({ container })`** hashes the visible text of the container, collects the headings inside it and sends `disclosure.presented`. Pass the element that holds the whole disclosure, with real heading elements (`h2`, `h3`). **`ceremony.accessSample()`** fetches the sample for this session: `{ format, instruction, html }`. The code inside is fixed for the session. **`ceremony.demonstrateAccess({ code })`** sends `access.demonstrated`. A code that does not match rejects with [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) and rule `US-23`. The consumer can try again. The record stores that the code matched, not the code. **`ceremony.giveEConsent({ checkbox })`** records `econsent.given` when the consumer ticks the box. If the box is ticked before the first two steps are recorded, the SDK waits for them before it reports the consent. ## Withdrawal A consumer can withdraw consent to electronic records at any time. There are two routes, and both produce the same result: - The consumer uses the withdrawal link in the receipt email that Esign Comply sent. - Your server reports a withdrawal you received yourself, for example from an account settings page or a support call. This call needs a secret key with `full_access`. ```ts const { data, error } = await esc.signers.withdrawConsent("user_7c1d", { note: "Requested in account settings.", }); if (error) throw new Error(error.message); ``` ```http POST /v1/signers/user_7c1d/consents/withdraw Authorization: Bearer esc_test_us_... Content-Type: application/json { "note": "Requested in account settings." } ``` | Field | Type | Required | Description | |---|---|---|---| | `record_id` | string | No | The record to attach the withdrawal to. Default: the signer's latest record in which electronic-records consent was given. | | `note` | string | No | Free text, up to 2,000 characters. Stored with the annotation as supplied by you. | | `scope` | string | No | Default `electronic_records`. | `201 Created` ```json { "object": "consent_withdrawal", "signer": "user_7c1d", "record_id": "rec_Z4m8", "annotation_id": "ann_3Fv7", "recorded_at": "2027-01-04T15:02:13.482Z" } ``` An unknown signer or record returns [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found). A signer with no record returns [`subject_not_found`](https://esigncomply.com/docs/api/errors.md#subject_not_found). Esign Comply timestamps the withdrawal, adds a `consent_withdrawn` annotation to the record with its own ledger entry, and sends the `consent.withdrawn` webhook: ```json { "object": "event", "id": "whe_8Rt4", "type": "consent.withdrawn", "api_version": "2026-11-21", "livemode": false, "created_at": "2027-01-04T15:02:13.611Z", "data": { "record_id": "rec_Z4m8", "signer_external_id": "user_7c1d" } } ``` Withdrawal is prospective only. Records made before it stay as they are. What your company does next is your obligation: Esign Comply does not stop your sending and does not monitor it. Handle the webhook by switching that person to the delivery method your disclosure promised, and by applying any condition or fee the disclosure stated. To test the path, create a test session with `signer.email` set to `signer+withdraw@test.esigncomply.com`. The withdrawal is filed 10 seconds after sealing. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). ## Paper-copy requests A consumer can ask for a paper copy from the signer view that the receipt email links to. Esign Comply seals the request as a `paper_copy_requested` annotation on the record and shows the fee disclosure you configured. Providing the paper copy is your obligation. Esign Comply does not print or mail anything. You can file your own report when a copy goes out, or when a request reaches you through your own channels: ```ts const { error } = await esc.supplements.create( { subject: { record: "rec_Z4m8" }, type: "paper_copy.delivered", occurred_at: "2027-01-06T17:30:00Z", rule_ids: ["US-27"], data: { sent_at: "2027-01-06T17:30:00Z", carrier: "USPS", fee: 0 }, }, { idempotencyKey: "paper-copy-rec_Z4m8-2027-01-06" }, ); if (error) console.error(error.message); // a failed report never blocks your own process ``` A supplement is sealed with Esign Comply's receipt time and labelled customer-supplied. Esign Comply does not verify its contents. See [Supplements](https://esigncomply.com/docs/guides/supplements.md). ## When hardware or software requirements change If the hardware or software needed to access the records changes in a way that creates a material risk that a consumer can no longer open or keep them, the statute asks the provider to give affected consumers the revised requirements and the right to withdraw without a fee, and to obtain consent again with a new access demonstration. That duty is yours. In practice: 1. Update the text under "What you need to access and keep the records". 2. For each affected consumer, run the consent steps again in a new session before the next electronic delivery. The new record carries the hash of the revised disclosure and a fresh access demonstration. 3. Offer withdrawal without a fee on the same screen. 4. Optionally file a `notice.sent` supplement with rule ID `US-26` for the notice you sent. ## Checklist - The profile has `consumer_econsent: true` and the session sends `signer.class: "consumer"`. - `required_steps` lists `disclosure.presented`, `access.demonstrated` and `econsent.given`, and your page builds the consent block only then. - The heading and the seven sub-headings appear verbatim, in order, as real heading elements. - The consent checkbox is separate, starts unchecked, and nothing in your code sets it. - Your server handles `consent.withdrawn`. - `npx esigncomply check --url http://localhost:3000/your-consent-page` reports no finding marked `block` for [CR-16](https://esigncomply.com/docs/conformance.md#cr-16). --- # L2 verification Source: https://esigncomply.com/docs/guides/l2-verification Markdown: https://esigncomply.com/docs/guides/l2-verification.md Section: Guides > Verify control of the signer's email address or phone number inside the ceremony with a one-time code or link. At assurance level L1 your application tells Esign Comply who the signer is, and that identity is recorded as asserted. At L2, Esign Comply itself sends a one-time code or link to the signer's email address or phone number during the ceremony and records whether it came back. The receipt then goes to the verified address. L2 records that a person who controlled that mailbox or phone at that moment took part in the ceremony. It does not establish legal identity, authority to sign, or who was holding the device. L2 is the default for NDAs, order forms and contracts, and it is still a simple electronic signature or recorded acceptance. ## What you need - A profile with `assurance_level: "L2"`. L2 is available on every plan, in test mode and live. The Free plan verifies by email: SMS codes need a paid plan. - A session whose signer has the destination: `signer.email` for the email methods, `signer.phone` for SMS. The destination always comes from the session your server created. The browser cannot change it. ```ts const { data, error } = await esc.sessions.create( { profile: "prof_nda_9c2e", // assurance_level L2, method typed signer: { external_id: "user_7c1d", email: "dana@example.org", name: "Dana Whitfield", class: "business", country: "US" }, documents: [{ document: "doc_Nd55", version: "current" }], context: { url: "https://app.example.com/nda/42", locale: "en-US", purpose: "nda" }, }, { idempotencyKey: "nda-42-user_7c1d-1" }, ); ``` The session's `required_steps` then include `identity.verified`: ```json ["client.attached", "document.presented:dv_3kT9", "notice.captured", "identity.verified", "intent.captured", "signature.applied"] ``` Read the list from the session. Do not hard-code it. ## Methods | Method | Sent to | The signer | |---|---|---| | `email_otp` | `signer.email` | Types a 6-digit code on your page | | `email_link` | `signer.email` | Opens a link in the message, which confirms on an Esign Comply page | | `sms_otp` | `signer.phone` | Types a 6-digit code on your page | Esign Comply sends the message from its own domain. The message names your organization and the document titles, and says that Esign Comply is an independent record keeper. You do not send or see the code. `email_otp` is the simplest to build because the signer stays on your page. The examples below use it. ## Limits | Limit | Value | |---|---| | Code length | 6 digits | | Code lifetime | 10 minutes | | Wrong attempts per code | 5. The fifth wrong attempt ends the session. | | Messages per session | 3 | | SMS per subscription year | Free none, Starter 500, Unlimited 5,000, Enterprise as contracted. Email verification is not limited. | When the SMS allowance is used up, or the plan has none, `sms_otp` returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). Offer `email_otp` instead. ## With the browser SDK Two calls. `verify.start` sends the message and returns the masked destination. `verify.confirm` checks the code the signer typed against the most recent verification. ```ts const verification = await ceremony.verify.start({ method: "email_otp" }); // { id: "ver_2bQd", method: "email_otp", destination: "d***@example.org", // status: "pending", expiresAt: "2026-11-21T15:13:01.000Z", attemptsRemaining: 5 } const result = await ceremony.verify.confirm({ code: "418205" }); // { id: "ver_2bQd", status: "confirmed", attemptsRemaining: 5 } ``` A wrong code does not reject. It resolves with `status: "failed"` and the attempts left, so you can ask the signer to try again. The call rejects with an `EsignComplyError` whose `code` is [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) in three cases: the code has expired, the session has used its 3 messages, or the fifth wrong attempt has ended the session. When a verification is confirmed, Esign Comply records the `identity.verified` step itself. `ceremony.remainingSteps()` no longer lists it, and the `change` and `stepRecorded` events fire. The event name is historical. It records verified control of a channel, not identity. ### A complete verification block ```tsx "use client"; import { useState } from "react"; import type { Ceremony, EsignComplyError } from "@esigncomply/browser"; export function EmailVerification({ ceremony, onVerified }: { ceremony: Ceremony; onVerified: () => void }) { const [destination, setDestination] = useState(null); const [canSend, setCanSend] = useState(true); const [verified, setVerified] = useState(false); const [ended, setEnded] = useState(false); const [message, setMessage] = useState(null); async function send() { setMessage(null); try { const v = await ceremony.verify.start({ method: "email_otp" }); setDestination(v.destination); // masked, for example d***@example.org setCanSend(false); setTimeout(() => setCanSend(true), 30_000); // allow a resend after 30 seconds } catch (err) { const error = err as EsignComplyError; setMessage(error.message); // for example: the limit of 3 messages was reached if (error.code === "session_not_active" || error.code === "client_token_expired") setEnded(true); } } async function confirm(form: FormData) { setMessage(null); try { const result = await ceremony.verify.confirm({ code: String(form.get("code") ?? "") }); if (result.status === "confirmed") { setVerified(true); onVerified(); } else { setMessage(`That code did not match. Attempts left: ${result.attemptsRemaining}.`); } } catch (err) { const error = err as EsignComplyError; setMessage(error.message); // expired code, or too many wrong attempts if (error.code === "verification_failed") setDestination(null); // this code is finished: ask for a new one else setEnded(true); } } if (verified) return

Email verified: {destination}

; if (ended) return

{message} Reload the page to start a new session.

; return (
{destination ? (
) : null} {message ?

{message}

: null}
); } ``` Guidelines for the screen: - Show the masked destination the API returns. Do not print the full address from your own data next to it. - Let the signer ask for a new code after 30 seconds, and tell them when no more can be sent. - After too many wrong attempts the session has ended. The next call rejects with [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active): create a new session on your server and attach again. - Keep the signing button disabled until `ceremony.remainingSteps()` contains only `"signature.applied"`. - Do not ask for the code in your own form and forward it through your server. The SDK sends it straight to Esign Comply. ## The API calls underneath The SDK calls two browser endpoints with the session client token. Use them directly only if you cannot use the SDK. See the [Sessions API](https://esigncomply.com/docs/api/sessions.md). ```http POST /v1/sessions/ses_5nWq/verifications Authorization: Bearer esc_ct_... Content-Type: application/json { "method": "email_otp" } ``` `201 Created` ```json { "object": "verification", "id": "ver_2bQd", "method": "email_otp", "destination": "d***@example.org", "status": "pending", "expires_at": "2026-11-21T15:13:01.000Z", "attempts_remaining": 5, "sends_remaining": 2, "delivered": true } ``` ```http POST /v1/sessions/ses_5nWq/verifications/ver_2bQd/confirm Authorization: Bearer esc_ct_... Content-Type: application/json { "code": "418205" } ``` `200 OK` ```json { "object": "verification", "id": "ver_2bQd", "status": "confirmed", "attempts_remaining": 5, "remaining_steps": ["intent.captured", "signature.applied"] } ``` A wrong code returns `200` with `"status": "failed"` and a lower `attempts_remaining`. | Situation | Response | |---|---| | Wrong code, attempts left | `200`, `status: "failed"` | | Fifth wrong attempt | `422` [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). The session is cancelled. | | Code older than 10 minutes | `422` `verification_failed`. Send a new code. | | Fourth message in one session | `422` `verification_failed`. Create a new session. | | The session has no `signer.email` or `signer.phone` | `400` [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | | The session has expired | `401` [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired) | ## Session status Sending a code moves the session to `awaiting_verification`. A confirmed verification moves it back to `in_progress`, or to `ready` when every step before the final act is recorded. `GET /v1/sessions/{id}` with your secret key shows the status and lists `identity.verified` under `completed_steps`. A lockout cancels the session. Your server receives `session.cancelled`: ```json { "object": "event", "id": "whe_8Rt4", "type": "session.cancelled", "api_version": "2026-11-21", "livemode": false, "created_at": "2026-11-21T15:09:44.120Z", "data": { "session_id": "ses_5nWq", "cancelled_by": "system", "reason": "verification_failed" } } ``` To let the signer try again, create a new session on your server and attach again. ## Email links `email_link` sends a link instead of a code. Opening the link confirms the verification on a page served by Esign Comply, which tells the signer to return to the page where they were signing. The link is valid for 10 minutes and counts toward the 3 messages per session. ```ts const verification = await ceremony.verify.start({ method: "email_link" }); // Show: "We sent a link to d***@example.org. Open it, then come back to this page." ceremony.on("stepRecorded", (step) => { if (step.type === "identity.verified") showVerified(); }); ``` There is nothing to confirm from your page. After `verify.start`, the SDK checks the session every few seconds for up to 10 minutes. When the link has been used it fires `stepRecorded` and `change`, and `ceremony.remainingSteps()` no longer lists `identity.verified`. Keep the page open while the signer goes to their mailbox. ## SMS `sms_otp` needs `signer.phone` on the session, in international format. The destination is masked to its last two digits, for example `***42`. SMS verifications count against the plan's yearly allowance. If SMS cannot be sent, the call returns [`service_unavailable`](https://esigncomply.com/docs/api/errors.md#service_unavailable): offer `email_otp`. ## What ends up in the record The record keeps what Esign Comply observed, tagged `observed`: ```json { "signer": { "external_id": "user_7c1d", "name": "Dana Whitfield", "email": "dana@example.org", "verified_email": "dana@example.org", "verification": [ { "method": "email_otp", "destination": "d***@example.org", "at": "2026-11-21T15:04:11.902Z", "attempts": 1 } ] }, "assurance_level": "L2" } ``` `signer.email` and `signer.name` remain asserted by you. `signer.verified_email` is present only because Esign Comply verified control of it. The evidence report masks the address and shows the method, the time and the number of attempts. The conformance rule is [CR-17](https://esigncomply.com/docs/conformance.md#cr-17): verification complete for L2 and L3. A session that reaches the final act without it returns [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) with `identity.verified` in `missing_steps`. ## Test mode - `signer+ok@test.esigncomply.com` accepts the code `000000`. - `signer+wrongcode@test.esigncomply.com` never verifies. Use it to build the failure and lockout screens. - Codes for other addresses are emailed only to verified addresses of your own team. For any other address nothing is sent, and the code comes back as `code` in the response (`verification.code` in the SDK), with `delivered: false`, so automated tests can finish the ceremony. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). For a credential bound to the signing act on top of L2, see [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md). --- # L3 passkeys Source: https://esigncomply.com/docs/guides/l3-passkeys Markdown: https://esigncomply.com/docs/guides/l3-passkeys.md Section: Guides > Add a passkey step on top of L2 so that a WebAuthn credential signs a challenge bound to the documents and the session before the final act. L3 is L2 plus a passkey. After Esign Comply has verified control of the signer's email address or phone number, the signer's device signs a one-use challenge with a WebAuthn credential. The challenge is derived from the session, the signer and the exact document versions, so the credential's response is tied to this signing act and no other. L3 is available on the Unlimited plan and above, in test mode as well as live. A session for an L3 profile on another plan returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). ## What L3 records, and what it does not Esign Comply records that a registered credential, protected by the device's own user verification (a fingerprint, a face, or a PIN), answered a challenge bound to the frozen pre-signature payload. It stores the credential ID, a hash of the payload the challenge was bound to, whether the credential is single-device or multi-device, and whether it is backed up. L3 does not establish legal identity, authority to sign, or sole control of the credential. Passkeys can sync across a person's devices and can be recovered through the platform account. The record says so. An L3 record is still a simple electronic signature: the passkey raises the assurance level, and `signature_level` stays `simple`. ## Set up Create a profile with `assurance_level: "L3"`. Use `method: "passkey"` to record the final act as a passkey signature combined with a typed name, or `method: "typed"` to keep the typed name as the method and add the passkey as verification. ```bash curl https://esigncomply.com/v1/profiles \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Master services agreement", "jurisdictions": ["US-FED"], "document_type": "contract", "method": "passkey", "assurance_level": "L3" }' ``` `method: "passkey"` is accepted only with `assurance_level: "L3"`. A session for this profile lists both verification steps: ```json [ "client.attached", "document.presented:dv_3kT9", "notice.captured", "identity.verified", "identity.verified:passkey", "intent.captured", "signature.applied" ] ``` `identity.verified` is the L2 channel verification. `identity.verified:passkey` is the passkey step. Both must be recorded before the final act, in that order. ## With the browser SDK Run the L2 step first, as in [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). Then call `ceremony.verify.passkey()` from a button the signer presses. Browsers show the passkey prompt only in response to a user action. The method takes no arguments and resolves with `{ id, status, attemptsRemaining }`, where `status` is `"confirmed"`, `"failed"` or `"registered"`. ```tsx "use client"; import { useState } from "react"; import type { Ceremony, EsignComplyError } from "@esigncomply/browser"; export function PasskeyStep({ ceremony, onVerified }: { ceremony: Ceremony; onVerified: () => void }) { const [busy, setBusy] = useState(false); const [message, setMessage] = useState(null); async function usePasskey() { setBusy(true); setMessage(null); try { const result = await ceremony.verify.passkey(); if (result.status === "confirmed") onVerified(); // "failed": the API could not verify the response. "registered": a passkey was created but not used yet. else setMessage("The passkey could not be checked. Please try again."); } catch (err) { const error = err as EsignComplyError; // verification_failed: no passkey support in this browser, or the prompt was dismissed. // step_out_of_order: the email or phone verification has not been confirmed yet. // plan_feature_unavailable: the plan does not include L3. setMessage(error.message); } finally { setBusy(false); } } return (

Confirm this signing with a passkey on this device. If you do not have one for this site yet, your device will offer to create it.

{message ?

{message}

: null}
); } ``` One call covers both cases: - **The signer already has a passkey for your domain.** The browser asks them to use it. The call resolves with `status: "confirmed"`. - **The signer has none.** The browser first asks them to create a passkey. The SDK then starts a second verification at once and the browser asks them to use the new passkey. The signer sees two prompts. The call resolves with `status: "confirmed"` after the second. The call resolves with `status: "failed"` when the API could not verify what the browser returned. Each call starts a new verification, so call `ceremony.verify.passkey()` again to retry. The SDK registers at most once per call: if the API asks for a registration twice in a row, the call resolves with `status: "registered"` and the step is still outstanding. When the step is recorded, the SDK emits `stepRecorded` for `identity.verified` and `ceremony.remainingSteps()` no longer lists `identity.verified:passkey`. Keep the signing button disabled until only `"signature.applied"` is left, then let the signer type their name and press the button. See the NDA example in the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md) for the assent container. If the browser has no passkey support, or the signer dismisses the prompt, the call rejects with an `EsignComplyError` whose `code` is `verification_failed`, with `status` 0 and rule `CR-17`. The verification that was started is left unconfirmed and no attempt is counted. Let the signer try again. An L3 session cannot be completed without the passkey step. If some of your signers cannot use passkeys, offer them a flow on an L2 profile instead, as a product decision you make and document. With a profile whose `method` is `passkey`, `ceremony.complete()` sends `passkey` as the signature method when `verify.passkey()` resolved with `confirmed` on the same ceremony object. After a page reload the passkey step stays recorded, and the new ceremony object sends the method the assent controls give, for example `typed`. ## How the two phases work The SDK drives two API calls per phase with the session client token: it starts a verification, runs the browser prompt, and confirms the verification with the browser's response. You need this section only to understand the record or to debug. Between the two calls the SDK converts the options for the browser. It decodes the base64url values (`challenge`, `user.id` and the `id` of each entry in `allowCredentials` and `excludeCredentials`) to bytes. It calls `navigator.credentials.create()` when the options carry a `user`, and `navigator.credentials.get()` otherwise. It sends the result back as JSON with `id`, `rawId`, `type`, `authenticatorAttachment`, `clientExtensionResults` and `response`, with every binary field encoded as base64url. ### Register When the signer has no stored credential for this relying party, `POST /v1/sessions/{id}/verifications` answers with `phase: "register"` and WebAuthn creation options. ```http POST /v1/sessions/ses_5nWq/verifications Authorization: Bearer esc_ct_... Content-Type: application/json { "method": "passkey" } ``` `201 Created` ```json { "object": "verification", "id": "ver_2bQd", "method": "passkey", "status": "pending", "phase": "register", "options": { "challenge": "c29tZS1yYW5k...", "rp": { "name": "Example, Inc.", "id": "example.com" }, "user": { "id": "c2duXzdLcDI", "name": "dana@example.org", "displayName": "" }, "pubKeyCredParams": [{ "alg": -8, "type": "public-key" }, { "alg": -7, "type": "public-key" }, { "alg": -257, "type": "public-key" }], "timeout": 60000, "attestation": "none", "excludeCredentials": [], "authenticatorSelection": { "residentKey": "preferred", "userVerification": "required" } }, "expires_at": "2026-11-21T15:13:01.000Z", "attempts_remaining": 5 } ``` The options are WebAuthn creation options and can carry further standard members. The browser creates the credential and the SDK sends the result as `attestation`: ```http POST /v1/sessions/ses_5nWq/verifications/ver_2bQd/confirm Authorization: Bearer esc_ct_... Content-Type: application/json { "attestation": { "id": "...", "rawId": "...", "type": "public-key", "authenticatorAttachment": "platform", "clientExtensionResults": {}, "response": { "clientDataJSON": "...", "attestationObject": "...", "transports": ["internal"] } } } ``` ```json { "object": "verification", "id": "ver_2bQd", "method": "passkey", "status": "registered", "next": "start_passkey_authentication", "attempts_remaining": 5 } ``` `200 OK`. `registered` means the public key is on file for this signer. It does not record the passkey step. The caller starts a passkey verification again to sign in with the new credential. `ceremony.verify.passkey()` does this for you. ### Authenticate With a credential on file, the same start call answers with `phase: "authenticate"` and WebAuthn request options. The `challenge` is not random alone: it is the SHA-256 hash of a canonical object that names the session, the signer's external ID, each document version with its content hash, the profile and its version, the purpose, and a one-use nonce. ```json { "object": "verification", "id": "ver_9Lm3", "method": "passkey", "status": "pending", "phase": "authenticate", "options": { "challenge": "0u5S1fVQ3m0v...", "rpId": "example.com", "allowCredentials": [{ "id": "Zm9vYmFyY3JlZGVudGlhbA", "type": "public-key" }], "timeout": 60000, "userVerification": "required" }, "expires_at": "2026-11-21T15:14:10.000Z", "attempts_remaining": 5 } ``` The SDK sends the signed response as `assertion`: ```http POST /v1/sessions/ses_5nWq/verifications/ver_9Lm3/confirm Authorization: Bearer esc_ct_... Content-Type: application/json { "assertion": { "id": "Zm9vYmFyY3JlZGVudGlhbA", "rawId": "...", "type": "public-key", "authenticatorAttachment": "platform", "clientExtensionResults": {}, "response": { "clientDataJSON": "...", "authenticatorData": "...", "signature": "...", "userHandle": "..." } } } ``` ```json { "object": "verification", "id": "ver_9Lm3", "status": "confirmed", "attempts_remaining": 5, "remaining_steps": ["intent.captured", "signature.applied"] } ``` `200 OK`. Esign Comply looks up the stored credential by the `id` of the assertion, verifies the signature against its public key, with the challenge, origin and relying party it expects, and requires user verification. It then records an `identity.verified` event for the step `identity.verified:passkey` and returns the steps still outstanding. A `register` confirmation without `attestation`, or an `authenticate` confirmation without `assertion`, returns `400` [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request). ## What the challenge is bound to The challenge covers the pre-signature payload, fixed before the signer acts: | Bound | Not bound | |---|---| | Session ID | The typed name | | Signer external ID | The final record, which contains the assertion itself | | Each document `version_id` and `content_hash` | Later annotations | | Profile ID and version | | | `context.purpose` | | | A one-use nonce | | The event data keeps a hash of that object as `challenge_binding`, with `bound_to: "pre_signature_payload"`. A response made for one session cannot be replayed for another session, another signer or another document version. ## Relying party and origin The ceremony runs on your own page, so the passkey belongs to your domain, not to Esign Comply. - In live mode the relying party ID is your registered domain, for example `example.com`. A passkey created on `app.example.com` works on every subdomain. - In test mode it is the host of the page, for example `localhost`. - The origin of the request must be the page that ran the prompt. The API checks it against the browser's `Origin` header. A credential registered for one relying party is not offered for another. A signer who registered on `localhost` in test mode registers again on your live domain. On a later L3 ceremony for the same `signer.external_id` on the same domain, the stored credential is reused and only the authenticate phase runs. ## Order and errors | Situation | Response | |---|---| | Passkey step started before the email or phone verification is confirmed | `409` [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) with `missing_steps: ["identity.verified"]` | | Plan below Unlimited | `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) | | Response does not verify (unknown credential, wrong origin, no user verification) | `200` with `status: "failed"` and a lower `attempts_remaining` | | Fifth failed attempt on one verification | `422` [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). The session is cancelled. | | Options older than 10 minutes | `422` `verification_failed`. Start again. | | No passkey support in the browser, or the prompt was dismissed | The browser SDK rejects with `verification_failed` and `status` 0. No request is sent to confirm. | | Final act without the passkey step | `422` [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) with `identity.verified:passkey` in `missing_steps` | The conformance rule is [CR-17](https://esigncomply.com/docs/conformance.md#cr-17). ## What ends up in the record ```json { "assurance_level": "L3", "signature_level": "simple", "signer": { "external_id": "user_7c1d", "verified_email": "dana@example.org", "typed_name": "Dana Whitfield", "verification": [ { "method": "email_otp", "destination": "d***@example.org", "at": "2026-11-21T15:04:11.902Z", "attempts": 1 }, { "method": "passkey", "destination": "passkey", "at": "2026-11-21T15:04:39.417Z", "attempts": 1 } ] } } ``` The `identity.verified` event for the passkey is tagged `observed` and carries these fields, among others: ```json { "method": "passkey", "credential_id": "Zm9vYmFyY3JlZGVudGlhbA", "challenge_binding": "sha256:7ac1...", "bound_to": "pre_signature_payload", "device_type": "multiDevice", "backed_up": true, "note": "A synced or recovered credential does not establish sole control." } ``` The evidence report states the method and the assurance level. It does not describe the signer as identified. ## Checklist - The profile is `L3` and the domain's plan is Unlimited or above. - The page runs the L2 verification first, then the passkey step, then the assent container. - `ceremony.verify.passkey()` is called from a click handler. - The typed-name field starts empty and the signing button stays disabled until only `"signature.applied"` remains. - Your [server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md) does not change: it checks status, `livemode`, signer and versions. You may also require `assurance_level === "L3"` for the flows that need it. --- # Re-acceptance Source: https://esigncomply.com/docs/guides/reacceptance Markdown: https://esigncomply.com/docs/guides/reacceptance.md Section: Guides > Publish a material change, find the signers whose acceptance is outstanding, and block signed-in users until they accept the updated documents. Document versions are immutable. When your terms change, you publish a new version. If the change is material, people who accepted an earlier version have not accepted the new one, and you will usually want them to before they continue. Esign Comply tells you who is outstanding. Your application builds the screen that asks them. The flow has four parts: 1. Publish the new version with `material_change: true`. 2. Ask `GET /v1/signers/{external_id}/status` whether a signed-in user has anything outstanding. 3. Show a blocking screen and run a ceremony with `purpose: "policy_update"`. 4. Confirm the new record on your server and let the user through. ## Publish a material change ```bash curl https://esigncomply.com/v1/documents/doc_8Hq2/versions \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: tos-2027-02-01" \ -d '{ "version_label": "2027-02-01", "language": "en", "effective_at": "2027-02-01T00:00:00Z", "content": { "format": "markdown", "text": "# Terms of Service\n..." }, "material_change": true, "summary_of_changes": "Added arbitration clause in section 14." }' ``` - `material_change: true` is your statement that the change matters. Esign Comply does not read the text or judge the change. A version published without it does not make earlier acceptances outstanding: new signers simply get the current version. - `summary_of_changes` (up to 2,000 characters) is returned later by the status call, so the blocking screen can show it. - `effective_at` may be in the future. The new version becomes `current` at that time, and earlier acceptances become outstanding at that time. When the version is published, Esign Comply sends `document.version_published`, and one `signer.reacceptance_required` for each signer who has a record on the document and none on the new version: ```json { "object": "event", "id": "whe_8Rt4", "type": "signer.reacceptance_required", "api_version": "2026-11-21", "livemode": true, "created_at": "2027-01-15T10:00:03.918Z", "data": { "signer_external_id": "user_7c1d", "document_id": "doc_8Hq2", "version_id": "dv_9Wc4" } } ``` The webhook is sent at publication, even when `effective_at` is later. That gap is the window in which you can tell people about the change. Esign Comply recommends notifying users in advance of a material terms update. Sending that notice is your decision and your job. Esign Comply does not send it. ## Ask who is outstanding ```http GET /v1/signers/user_7c1d/status Authorization: Bearer esc_test_us_... ``` Any secret key can call it, including a `recording_access` key. ```json { "object": "signer_status", "signer": { "external_id": "user_7c1d", "known": true, "erased": false }, "documents": [ { "document_id": "doc_8Hq2", "name": "Terms of Service", "type": "terms", "current_version": { "id": "dv_9Wc4", "version_label": "2027-02-01", "effective_at": "2027-02-01T00:00:00.000Z", "material_change": true }, "accepted_version": { "id": "dv_3kT9", "version_label": "2026-11-21", "record_id": "rec_Z4m8", "signed_at": "2026-11-21T15:03:20.291Z" }, "outstanding": true, "reason": "material_change", "summary_of_changes": "Added arbitration clause in section 14." }, { "document_id": "doc_Pv71", "name": "Privacy Notice", "type": "privacy_notice", "current_version": { "id": "dv_Lm02", "version_label": "2026-11-21", "effective_at": "2026-11-21T00:00:00.000Z", "material_change": false }, "accepted_version": { "id": "dv_Lm02", "version_label": "2026-11-21", "record_id": "rec_Z4m8", "signed_at": "2026-11-21T15:03:20.291Z" }, "outstanding": false, "reason": null, "summary_of_changes": null } ], "outstanding": ["doc_8Hq2"] } ``` How the answer is computed: | Case | `outstanding` | `reason` | |---|---|---| | The signer accepted the current version | `false` | `null` | | A newer version is in effect and none of the versions after the accepted one is marked material | `false` | `null` | | A version marked material took effect after the one the signer accepted | `true` | `material_change` | | The document was named in `documents` and the signer never accepted any version | `true` | `never_accepted` | Query parameters: | Parameter | Description | |---|---| | `documents` | Comma-separated document IDs to report on. Without it, the response covers every document the signer has accepted at least once. Use it to require a document the signer has never seen. | | `locale` | Picks the language version when translations exist, as session creation does. | Archived documents are left out. A signer Esign Comply has never seen returns `"known": false` and an empty list, unless you name documents. ## Gate signed-in users Check once per user every 5 minutes. `lib/esign-gate.ts`: ```ts import "server-only"; import { esc } from "@/lib/esigncomply"; export interface OutstandingDocument { documentId: string; name: string; summaryOfChanges: string | null; } const TTL_MS = 5 * 60_000; const cache = new Map(); export async function outstandingDocuments(signerId: string): Promise { const hit = cache.get(signerId); if (hit && Date.now() - hit.at < TTL_MS) return hit.value; const { data, error } = await esc.signers.status(signerId); if (error) return hit?.value ?? []; // see "If the check fails" below const value = data.documents .filter((d) => d.outstanding) .map((d) => ({ documentId: d.document_id, name: d.name, summaryOfChanges: d.summary_of_changes })); cache.set(signerId, { at: Date.now(), value }); return value; } export function clearOutstanding(signerId: string) { cache.delete(signerId); } ``` Call it from the authenticated layout, `app/(app)/layout.tsx`: ```tsx import { redirect } from "next/navigation"; import { getSignedInUser } from "@/lib/auth"; // your Supabase Auth helper import { outstandingDocuments } from "@/lib/esign-gate"; export default async function AppLayout({ children }: { children: React.ReactNode }) { const user = await getSignedInUser(); if (!user) redirect("/login"); const outstanding = await outstandingDocuments(user.signerId); if (outstanding.length > 0) redirect("/accept-updates"); return <>{children}; } ``` Put `/accept-updates` outside this layout, or the redirect loops. A layout runs on the first load and on full navigations. For actions that must not happen before re-acceptance, call `outstandingDocuments` in the server action or route handler as well. The map above lives in one server instance. Any per-user cache with a 5-minute lifetime works. ### If the check fails If the status call returns an error, the code above keeps the last known answer and otherwise lets the user in. The earlier acceptance is still on record, and the next request checks again. Blocking every signed-in user while a check is unavailable is the other option. Choose deliberately, and write the choice down. ## Build the blocking screen `/accept-updates` shows: - The list of updated documents, each linked to its page. - The summary of changes returned by the API. - An unchecked checkbox labelled "I agree to the updated [document titles]". - A button labelled "Accept and continue". - "Log out" as the alternative. Do not offer "Remind me later", and do not treat continued use, scrolling or signing in as acceptance. ### Update server actions `app/accept-updates/actions.ts` creates a session for the outstanding documents with `purpose: "policy_update"`, then confirms the record. It reuses `confirmRecord` and `saveAcceptances` from the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). ```ts "use server"; import { headers } from "next/headers"; import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; import { confirmRecord, saveAcceptances } from "@/lib/esign-confirm"; import { clearOutstanding, outstandingDocuments } from "@/lib/esign-gate"; import { getSignedInUser } from "@/lib/auth"; export async function startUpdateCeremony(attempt: number) { const user = await getSignedInUser(); // { id, email, signerId, accountType, country, region } const outstanding = await outstandingDocuments(user.signerId); if (outstanding.length === 0) return { ok: false as const, message: "Nothing to accept." }; const h = await headers(); const origin = h.get("origin") ?? `https://${h.get("host")}`; const { data, error } = await esc.sessions.create( { profile: "prof_signup_4f1a", signer: { external_id: user.signerId, email: user.email, class: user.accountType, country: user.country, region: user.region }, documents: outstanding.map((d) => ({ document: d.documentId, version: "current" })), context: { url: `${origin}/accept-updates`, locale: "en-US", purpose: "policy_update" }, }, { idempotencyKey: `update-${user.signerId}-${outstanding.map((d) => d.documentId).join("-")}-${attempt}` }, ); if (error) return { ok: false as const, message: error.message }; await supabaseAdmin.from("esign_ceremonies").upsert({ session_id: data.id, signer_id: user.signerId, purpose: "policy_update", version_ids: data.documents.map((d) => d.version_id), }); return { ok: true as const, clientToken: data.client_token, apiUrl: data.api_url, documents: data.documents.map((d) => ({ documentId: d.document_id, versionId: d.version_id, title: d.title })), }; } export async function finishUpdate(recordId: string) { const user = await getSignedInUser(); const confirmed = await confirmRecord({ recordId, signerId: user.signerId, purpose: "policy_update" }); if (!confirmed.ok) { return { ok: false as const, message: "We could not confirm whether your acceptance was recorded. Please wait while we check." }; } await saveAcceptances(confirmed.record, { signerId: user.signerId, userId: user.id, purpose: "policy_update" }); clearOutstanding(user.signerId); // the next request asks Esign Comply again return { ok: true as const }; } ``` ### Update form `app/accept-updates/accept-updates-form.tsx`. The server page passes the outstanding documents with their summaries, and a map from document ID to your document page. ```tsx "use client"; import { useEffect, useRef, useState } from "react"; import { EsignComply, type Ceremony, type EsignComplyError } from "@esigncomply/browser"; import { finishUpdate, startUpdateCeremony } from "./actions"; type Started = Extract>, { ok: true }>; const PAGES: Record = { doc_8Hq2: "/legal/terms", doc_Pv71: "/legal/privacy" }; export function AcceptUpdatesForm({ summaries }: { summaries: Array<{ documentId: string; name: string; summaryOfChanges: string | null }> }) { const assentRef = useRef(null); const checkboxRef = useRef(null); const submitRef = useRef(null); const ceremonyRef = useRef(null); const requestedRef = useRef(false); const [started, setStarted] = useState(null); const [ready, setReady] = useState(false); const [message, setMessage] = useState(null); useEffect(() => { if (requestedRef.current) return; requestedRef.current = true; startUpdateCeremony(1).then((res) => (res.ok ? setStarted(res) : setMessage(res.message))); }, []); useEffect(() => { if (!started) return; let cancelled = false; let ceremony: Ceremony | undefined; (async () => { try { ceremony = await EsignComply.attach({ clientToken: started.clientToken, apiUrl: started.apiUrl }); if (cancelled) return ceremony.destroy(); ceremonyRef.current = ceremony; ceremony.on("change", ({ remainingSteps }) => { setReady(remainingSteps.length === 1 && remainingSteps[0] === "signature.applied"); }); const links = assentRef.current!.querySelectorAll("a[data-version]"); for (const link of links) { await ceremony.presentDocument({ versionId: link.dataset.version!, mode: "hyperlink", link }); } await ceremony.observeAssent({ region: assentRef.current, checkbox: checkboxRef.current, submit: submitRef.current }); } catch (err) { if (!cancelled) setMessage((err as EsignComplyError).message); } })(); return () => { cancelled = true; ceremony?.destroy(); ceremonyRef.current = null; }; }, [started]); async function onSubmit(event: React.FormEvent) { event.preventDefault(); if (!ceremonyRef.current || !ready) return; try { const result = await ceremonyRef.current.complete(); const outcome = await finishUpdate(result.recordId); if (outcome.ok) window.location.assign("/app"); else setMessage(outcome.message); } catch (err) { setMessage((err as EsignComplyError).message); } } if (!started) return

{message ?? "Loading the updated documents."}

; return (

We have updated our terms

    {summaries.map((s) => (
  • {s.name} {s.summaryOfChanges ?

    {s.summaryOfChanges}

    : null}
  • ))}

Log out

{message ?

{message}

: null}
); } ``` The same interface rules apply as at signup: the checkbox starts unchecked, the label names every document by its title, links are underlined and distinct in color, and one primary button sits in the assent container. See [Conformance](https://esigncomply.com/docs/conformance.md). ## What is recorded - Each re-acceptance is a new record and, in live mode, a new signature event. One ceremony may cover up to 10 updated documents and still counts as one event. - Earlier acceptances stay on record unchanged. A record is never edited to point at a newer version. - The new record names the exact versions presented, with `context.purpose` set to `policy_update`. - After the record exists, the status call reports `outstanding: false` for those documents. ## Advance notice and reports Telling users about a material change before it takes effect is a recommendation in the Federal pack (US-18). Your profile's packs may list related duties of your own. Esign Comply lists these items and does not perform, monitor or verify them. Read them with the [Guidance API](https://esigncomply.com/docs/api/guidance.md). If you want your own evidence of the notice on file, send it as a supplement when the email goes out: ```ts const { error } = await esc.supplements.create( { subject: { signer: "user_7c1d" }, type: "notice.sent", occurred_at: "2027-01-15T10:05:00Z", rule_ids: ["US-18"], text: "Terms update notice emailed to the address on the account.", data: { channel: "email", template: "terms-update-2027-02" }, }, { idempotencyKey: "terms-update-user_7c1d-2027-02" }, ); if (error) console.error(error.message); // never block the email on a failed report ``` Esign Comply seals the report with its own receipt time and labels it customer-supplied. It does not verify that the notice was sent or received. See [Supplements](https://esigncomply.com/docs/guides/supplements.md). ## Test it 1. With a test key, publish a second version of a test document with `material_change: true`. 2. Call the status endpoint for a signer who accepted the first version. `outstanding` lists the document. 3. Load a page inside the gated layout. You are redirected to `/accept-updates`. 4. Accept. The record appears in the dashboard, and the status call returns `outstanding: []`. 5. Confirm that the button does nothing while the box is unchecked, and that `finishUpdate` with a made-up record ID does not clear the gate. --- # Supplements Source: https://esigncomply.com/docs/guides/supplements Markdown: https://esigncomply.com/docs/guides/supplements.md Section: Guides > Send free text, JSON and files about a record, session, signer, document version or your domain, sealed on receipt and labeled customer-supplied. You hold evidence that Esign Comply never sees: the renewal reminder you emailed, the cancellation request that arrived by phone, a screenshot, an export from your billing system, a note from counsel. A supplement lets you file that material with Esign Comply in the shape you already have it. The API hashes it as received, signs a receipt with the receipt time, adds a ledger entry, and keeps it apart from Esign Comply's own record. Supplements come from your server only. The browser SDK has no supplement methods. ## What a supplement is - Any content you send that Esign Comply did not observe: free text, arbitrary JSON, and files. - Attached to exactly one subject: a record, a session, a signer, a document version, or your domain as a whole. - Sealed on receipt. The seal shows that you sent these exact bytes to Esign Comply no later than the receipt time. - Always labeled `provenance: "customer_supplied"`. Every response carries the sentence "Esign Comply received and sealed this material at the time shown and did not verify it." - Immutable. You can supersede or withdraw a supplement, never edit it. ## What a supplement is not - It is not verified. The seal says nothing about whether the content is true. - It is never part of a record's sealed hash, and it never changes a record, a conformance result, a required step or a rule outcome. - It is not evidence that you performed a duty. Esign Comply lists the obligations its rule packs identify for you and stores the reports you choose to send. It does not perform, monitor or verify those obligations. - It is not a signature event and is never metered. Stored file bytes count toward your plan's storage allowance. - It is not required. A failed report must never block your user's action. ## Send a supplement At least one of `text`, `data` or `files` is required. Nothing else is. A call that omits `type`, `subject`, `occurred_at` and `rule_ids` succeeds. ```bash curl https://esigncomply.com/v1/supplements \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: renewal-notice-user_7c1d-2027-01" \ -d '{ "subject": { "record": "rec_Z4m8" }, "type": "notice.sent", "occurred_at": "2027-01-04T15:02:11Z", "rule_ids": ["NY-05"], "text": "Annual renewal reminder emailed to the address on the account. Template v7.", "data": { "notice_kind": "renewal_reminder", "channel": "email", "recipient_ref": "user_7c1d", "template": "renewal-v7" }, "labels": ["renewal", "2027"] }' ``` The response is `201 Created`: ```json { "object": "supplement", "id": "sup_5Hc1", "livemode": false, "subject": { "record": "rec_Z4m8" }, "type": "notice.sent", "type_recognized": true, "provenance": "customer_supplied", "occurred_at": "2027-01-04T15:02:11.000Z", "received_at": "2027-01-04T15:02:13.482Z", "gap_seconds": 2, "rule_ids": ["NY-05"], "labels": ["renewal", "2027"], "content_hash": "sha256:41be...", "size": 0, "has_text": true, "has_data": true, "files": [], "supersedes": null, "withdrawn": false, "withdrawn_at": null, "submitted_by": "key:key_2bQ1", "seal": { "receipt": "eyJhbGciOiJFUzI1NiIs...", "ledger_seq": 48122, "status": "recorded" }, "note": "Esign Comply received and sealed this material at the time shown and did not verify it.", "warnings": ["suggested_field_absent:content_sha256"] } ``` With the server SDK: ```ts import { esc } from "@/lib/esigncomply"; const { data, error } = await esc.supplements.create( { subject: { record: "rec_Z4m8" }, type: "notice.sent", occurred_at: sentAt.toISOString(), rule_ids: ["NY-05"], text: "Annual renewal reminder emailed to the address on the account. Template v7.", data: { notice_kind: "renewal_reminder", channel: "email", recipient_ref: userId }, }, { idempotencyKey: `renewal-notice-${userId}-2027-01` }, ); if (error) { // Log it and move on. A failed report must not block the reminder itself. console.error("Esign Comply supplement failed", error.code, error.message); } ``` Keys with `full_access` or `recording_access` can create supplements. Keys with `full_access` or `read_only` can list and read them. Only `full_access` keys can withdraw. `seal.status` moves from `recorded` to `timestamped` to `anchored` in the same pipeline as records. The content hash covers the canonical form of the text, the data, the file hashes, the subject, the type and `occurred_at`. ## The two times | Field | Who states it | Meaning | |---|---|---| | `occurred_at` | You (asserted) | When you say the thing happened. Optional. | | `received_at` | Esign Comply (observed) | Server time when the supplement arrived. | | `gap_seconds` | Computed | `received_at` minus `occurred_at`, in seconds. `null` without `occurred_at`. | Reports print both times and the gap as a number. Send supplements close to the event: a short gap is a fact a reader can see for themselves. ## Subjects `subject` holds exactly one key. Sending more than one returns `400 invalid_request`. | Subject | Value | Notes | |---|---|---| | `record` | Record ID, `rec_Z4m8` | Listed on the record under `supplements[]` and in Part C of its evidence report. | | `session` | Session ID, `ses_5nWq` | If the session already completed, the supplement is attached to its record. | | `signer` | Your external ID, `user_7c1d` | For material about a person across records, such as a phone cancellation. | | `document_version` | Version ID, `dv_3kT9` | For example counsel's review of that version. | | `domain` | `true` | Material about your business as a whole, such as your cancellation policy. This is the default when `subject` is omitted. | A subject that does not exist in this domain and environment returns [`subject_not_found`](https://esigncomply.com/docs/api/errors.md#subject_not_found). ## More examples Free-form material with no type and no structure is equally valid: ```json { "subject": { "signer": "user_7c1d" }, "text": "Customer called support on March 3 to cancel. Agent: J. Ortiz. Ticket 55120." } ``` A cancellation request with a little structure: ```json { "subject": { "record": "rec_Z4m8" }, "type": "cancellation.requested", "occurred_at": "2027-03-03T17:41:00Z", "rule_ids": ["CA-10"], "data": { "channel": "phone", "requested_at": "2027-03-03T17:41:00Z", "reference": "ticket-55120" } } ``` ## Types `type` is a name from the public catalogue, or any name under `custom.` that you define. An unknown type is accepted and stored with `type_recognized: false`. It is never an error. Read the catalogue at run time with `GET /v1/supplement-types` (no key needed) and do not hard-code it. Each entry has a `type`, a `use` sentence and `suggested_fields` for `data`. Every field is optional: the list tells you what is useful, not what is required. A suggested field you leave out adds the warning `suggested_field_absent:` and nothing else. | Type | Use | |---|---| | `notice.sent` | A notice you sent after or outside the ceremony: renewal reminder, price change, material change, trial ending | | `cancellation.requested`, `cancellation.completed` | The signer asked to cancel; you completed the cancellation | | `copy.delivered`, `paper_copy.delivered` | A copy reached the signer outside Esign Comply's receipt; a paper copy was sent on request | | `disclosure.delivered`, `translation.delivered` | A disclosure or translation given by your own means | | `order.acknowledged`, `withdrawal.acknowledged` | Order confirmation or withdrawal acknowledgment sent on a durable medium | | `consent.obtained`, `identity.checked` | A consent or identity check you ran yourself | | `counsel.reviewed`, `policy.snapshot` | Counsel's review; your own policy in force | | `screenshot`, `correspondence`, `note` | An image of your interface; email, chat or call notes; anything else in plain words | The full list is on the [Supplements API page](https://esigncomply.com/docs/api/supplements.md). ## Link a supplement to rules `rule_ids` names the rules the supplement relates to, for example `NY-05`. Up to 20 IDs. The dashboard obligations list then shows a count of reports per item. The count is information for you. It is not a finding that the obligation was met. An ID that is not in the catalogue is kept and returns the warning `rule_unknown:`. ## Correct or withdraw Supplements are immutable. To correct one, send another with `supersedes`: ```json { "subject": { "record": "rec_Z4m8" }, "type": "notice.sent", "supersedes": "sup_5Hc1", "text": "Correction: the reminder used template v8, not v7." } ``` Both stay visible. To withdraw one, call `DELETE /v1/supplements/sup_5Hc1` with a `full_access` key. The content is deleted, the ledger keeps the hash and the receipt time, and the supplement is returned with `withdrawn: true`. A supplement under legal hold, or listed on an issued certificate, cannot be withdrawn. ## Upload a file in three steps Text and JSON travel in the API call. Files go straight from your server to storage, so they are not limited by the request body size. **1. Declare the file.** Send its name, size and SHA-256. ```bash FILE=renewal-notice.eml SHA=$(sha256sum "$FILE" | cut -d' ' -f1) SIZE=$(wc -c < "$FILE" | tr -d ' ') curl https://esigncomply.com/v1/files \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"name\": \"$FILE\", \"size\": $SIZE, \"content_type\": \"message/rfc822\", \"sha256\": \"$SHA\" }" ``` ```json { "object": "file", "id": "fil_9Qe2", "livemode": false, "name": "renewal-notice.eml", "content_type": "message/rfc822", "size": 48213, "sha256": "sha256:9d07...", "status": "pending", "supplement": null, "created_at": "2027-01-04T15:01:58.120Z", "upload_url": "https:///...signed...", "upload_method": "PUT", "upload_expires_in": 7200 } ``` **2. Send the bytes** to `upload_url` with `PUT`. The URL is valid for 2 hours and works for that file only. Files above 6 MB also get a `resumable_url` and upload in chunks of `resumable_chunk_bytes`. ```bash curl -X PUT "$UPLOAD_URL" -H "Content-Type: message/rfc822" --data-binary @renewal-notice.eml ``` **3. Reference the file ID** in a supplement. ```json { "subject": { "record": "rec_Z4m8" }, "type": "notice.sent", "files": ["fil_9Qe2"] } ``` When the supplement is created, Esign Comply reads the stored object, recomputes its hash and copies it to the write-once vault. The file is sealed as part of that supplement. | Situation | Result | |---|---| | The bytes do not match the declared hash or size | File `status: "rejected"`, [`file_hash_mismatch`](https://esigncomply.com/docs/api/errors.md#file_hash_mismatch) | | The file is an executable, or an archive that contains one | [`file_type_refused`](https://esigncomply.com/docs/api/errors.md#file_type_refused) | | The file is larger than your plan allows | [`file_too_large`](https://esigncomply.com/docs/api/errors.md#file_too_large) | | The storage allowance is used up | [`storage_limit_reached`](https://esigncomply.com/docs/api/errors.md#storage_limit_reached). Text and JSON supplements are still accepted. | | The file was declared but not uploaded yet | `400 invalid_request` | | The file already belongs to another supplement | `400 invalid_request` | `GET /v1/files/fil_9Qe2` returns the file's status (`pending`, `stored`, `rejected`) and runs the hash check if the bytes have arrived. A file that no supplement references within 7 days is deleted. The server SDK performs the three steps for you: ```ts const { data: file, error } = await esc.files.upload("./renewal-notice.eml", { name: "renewal-notice.eml", contentType: "message/rfc822", }); if (error) throw new Error(error.message); await esc.supplements.create({ subject: { record: "rec_Z4m8" }, type: "notice.sent", files: [file.id] }); ``` Files are stored as opaque bytes. They are never rendered as HTML or executed, and downloads are served as attachments through short-lived URLs from `GET /v1/supplements/{id}/content`. ## Limits | Limit | Value | |---|---| | `text` | 20,000 characters | | `data` | Any JSON value up to 256 KB | | `files` | Up to 10 file IDs per supplement | | `labels` | Up to 20 strings | | `rule_ids` | Up to 20 rule IDs | | File size | Starter 10 MB, Unlimited 25 MB, Enterprise by contract | | File storage | Starter 2 GB, Unlimited 20 GB under fair use, Enterprise by contract | | Supplements per record | 200 | | Domain-level supplements | 10,000 | Unknown top-level fields are ignored with the warning `unknown_field:`. Unknown fields inside `data` are kept as sent. Test-mode supplements use the test ledger and are purged with test records after 30 days. ## Sensitive data Do not send payment card numbers, government identity numbers, passwords or health records. Text and JSON are checked for likely card numbers. A match is masked before storage, the response carries the warning `sensitive_data_masked`, and the stored hash covers the masked content. Files are not inspected for content. A supplement attached to a record or a signer is encrypted under that signer's key. Erasing the signer removes the content and leaves only the hash in the ledger. ## Context sent with the session Two fields on `POST /v1/sessions` carry your own context at signing time. They are not supplements: they are sealed inside the record and labeled asserted. | Field | Limit | Use | |---|---|---| | `context.notes` | 2,000 characters | Free text, for example "Signup A/B variant 7." | | `context.extra` | 16 KB of JSON | Any structure, for example `{ "experiment": "signup-v7" }` | No rule reads either field. Use a supplement for anything that happens after signing. ## Where supplements appear - **Record object.** `GET /v1/records/{id}` lists the first 20 under `supplements[]` (ID, type, `received_at`, `occurred_at`, hash). Page through the rest with `GET /v1/supplements?subject=rec_Z4m8`. - **Evidence report.** Part C, "Supplied by {customer} after signing": a list with type, both times and hash, under the sentence that Esign Comply received the material at the times shown and did not verify its contents. Parts A and B do not change. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md). - **Evidence package.** A `customer_supplied/` folder with `manifest.json` and the content as received, separate from `record.json`. Leave it out with `?supplements=false`. The offline verifier checks each item separately. - **Certificates.** Only when the request sets `include: ["supplements"]`, and then as a list. Content is never reproduced on a certificate. - **Signer view.** Never. ## Webhooks | Event | Sent when | |---|---| | `supplement.received` | The supplement was accepted. Payload: `supplement_id`, `subject`, `type`, `content_hash`. | | `supplement.sealed` | Its external timestamp was attached. Payload: `supplement_id`, `content_hash`, `timestamp_time`. | | `supplement.withdrawn` | It was withdrawn. | See [Webhooks](https://esigncomply.com/docs/api/webhooks.md) for signature verification. ## Earlier annotation types Reports sent through `POST /v1/records/{id}/annotations` with the earlier types `notice.sent` and `cancellation.requested` are stored as supplements, so code built from earlier prompts keeps working. The response is the supplement object, with the warning `stored_as_supplement`. New integrations send customer reports to `POST /v1/supplements`. Annotations remain for state changes Esign Comply observes or enforces, such as a dispute or a consent withdrawal. --- # Certificates Source: https://esigncomply.com/docs/guides/certificates Markdown: https://esigncomply.com/docs/guides/certificates.md Section: Guides > Request a Contemporaneous Record Statement for a timestamped record or a set of records, with a quote before any charge. A certificate is a dated statement about one or more sealed records, issued on request. Its printed title is "Contemporaneous Record Statement". It says when and how Esign Comply made its record, shows the time evidence that rests on parties other than Esign Comply and you, and reports a fresh integrity check run at the moment of issue. It is not the per-record PDF. That document is the evidence report: it is generated for every record, included in every plan and never charged per download. Request a certificate only when a dispute turns on when a record was made. In the API the object is `certificate`, with IDs prefixed `crt_`. Requests need a `full_access` key. `read_only` keys can list and download certificates. `recording_access` keys have no certificate access and can never incur a charge. ## What the statement says | Section | Content | |---|---| | Header | Printed title, certificate ID, issue time in UTC, record ID or set description, requester class, your `reference` marked asserted, live or test mark, verification URL and QR code | | What is stated | A fixed paragraph (below) | | Chronology | For each ceremony event: browser-reported time (reported, not verified) and Esign Comply server receipt time (observed), with the difference. Then record committed, receipt signed with key ID, external timestamp, checkpoint and public anchor. Every time is labeled with its source. | | Intervals | Measured durations from the final ceremony event to commit, receipt signature, external timestamp, checkpoint and public anchor. Printed as numbers. No adjective such as "immediately". | | Independent time bound | "The timestamp token issued by {authority} shows that this record hash existed no later than {time}. The public anchor {reference} shows that the checkpoint containing it existed no later than {time}." | | Integrity check at issue | Record hash recomputed from stored content, receipt signature, timestamp token, inclusion proof, consistency proof to the current checkpoint, and write-once storage status. Each with its result and check time. | | Capture mode | `direct`, `server_only`, `deferred` or `imported`, with one sentence on what that means for when the record was made | | Later history | Annotations with times (dispute, consent withdrawal, supersession, legal hold) and earlier certificates for the record | | Process in force | System description version, jurisdiction packs and versions applied, the time source used | | Limits | A fixed text (below) | | Seal | Certificate hash, signed receipt, external timestamp and ledger sequence for the certificate itself | The fixed statement for a record captured directly from the signer's browser reads: > Esign Comply's systems created record {record ID} by an automated process. Each event in it was recorded when Esign Comply's server received it from the signer's browser session, at the server receipt time shown. Esign Comply makes and keeps records of this kind in the regular course of providing its recording service to {customer}, and making them is its regular practice. The record was sealed at {time}. On {issue time} Esign Comply recomputed the hash of the stored record and found that it matches the hash committed to the seal, the external timestamp token and the ledger checkpoint, with the results shown below. This statement was issued on {issue time}; the record it describes was made at the times shown in the chronology. For `deferred` and `imported` records the statement does not say the record was made at or near the time of the act. It says that you reported the signing act at the receipt time, that you assert when it occurred, and that Esign Comply did not observe it. For `server_only` records it says the events were received from your server and not from the signer's browser. ## What the statement does not say Every certificate prints this limits text: > This statement describes when and how Esign Comply's record was made and whether it has changed since. It does not establish who the signer was, the signer's capacity or authority, that the signer read the documents, or that any agreement is valid or enforceable. Times reported by the signer's browser are reported, not verified. A court decides admissibility and weight. The automated statement is not a custodian declaration. A custodian-signed unsworn declaration is available on request where the forum permits it. This document is not a qualified certificate, a qualified electronic time stamp, or a qualified electronic seal. The external timestamp bounds when the record hash existed. It does not show when the person acted. No free text from you appears on the statement except `reference` (120 characters at most), printed as "Requester reference (asserted)". IP addresses, raw device data and drawn-signature images are left out by default. ## Before you request | Record status | Result | |---|---| | `timestamped` or `anchored` | A certificate can be issued. If the public anchor is not available yet, its line reads "pending". | | `recorded` or `pending_seal` | [`record_not_timestamped`](https://esigncomply.com/docs/api/errors.md#record_not_timestamped) (409) with `Retry-After: 30`. The external timestamp normally follows within 60 seconds. | | `disputed` | A certificate can be issued. The dispute appears under Later history. | | `voided` | [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) | | Locked under the earlier Starter quota rule | [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded) (402). Records sealed now are not locked. | If any integrity check fails at issue, nothing is issued. The request returns [`certificate_verification_failed`](https://esigncomply.com/docs/api/errors.md#certificate_verification_failed), an integrity incident is opened, and `certificate.failed` is sent. Do not retry: contact support with the request ID. ## Price One unit is one issued single-record certificate, or each 100 records (or part of 100) covered by a set certificate. Issuing a certificate is not a signature event and uses no event quota. | Plan | Included per subscription year | Price beyond the allowance | Records per set request | |---|---|---|---| | Free | None for live records. Test certificates are unlimited and watermarked "TEST". | Not sold | 10 (test certificates) | | Starter, $200 per year | None | $20 per certificate, charged only when one is issued | Up to 100 | | Unlimited, $1,200 per year | 25 | $20 per certificate | Up to 10,000 | | Enterprise, from $10,000 per year | Unlimited | Included | By contract | Certificates for live records are on paid plans. On the Free plan a certificate request or quote for a live record returns `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). Test certificates are free and watermarked "TEST" on every plan. The Unlimited allowance is counted per domain subscription and per subscription year. It does not roll over and cannot be moved between domains. Included units are used first. Charged certificates are invoiced monthly in arrears to the payment method on file, one line per certificate. The same numbers are in [pricing.md](https://esigncomply.com/pricing.md). | Plan | Activity in a year | Certificate cost | |---|---|---| | Starter | No certificates | $0 | | Starter | 3 single-record certificates for one dispute | $60 | | Starter | One set certificate covering 100 records | $20 | | Unlimited | 18 single-record certificates | $0 (18 of 25 included) | | Unlimited | 40 single-record certificates | $300 (25 included, 15 at $20) | | Unlimited | One set certificate covering 2,500 records | $0 (25 units, all included) | ## Quote, then confirm No charge is created without a recorded confirmation: a confirming click in the dashboard, or `confirm_charge: true` from a `full_access` key. A request covered by an allowance, by an Enterprise contract or by test mode needs no confirmation. **1. Ask for a quote.** `POST /v1/certificates/quote` accepts a certificate request body and returns what it would cost. It never issues and never charges. `full_access` and `read_only` keys can call it. ```bash curl https://esigncomply.com/v1/certificates/quote \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "contemporaneous_record", "record_id": "rec_Z4m8" }' ``` ```json { "object": "certificate_quote", "record_count": 1, "units": 1, "unit_amount": 2000, "amount": 2000, "currency": "usd", "allowance_remaining": 0, "month_to_date": 4000, "spend_limit": 20000, "charge_class": "charged", "units_included": 0, "units_charged": 1, "requires_confirmation": true } ``` Amounts are integers in the smallest currency unit: `2000` is $20.00. `units_included` come from your allowance and `units_charged` are billed. For a set, send the same `filter` you will use for the request: the quote counts the matching records. **2. Show the quote to a person.** An administrator approves the charge. **3. Issue with `confirm_charge: true`.** ```ts const { data: certificate, error } = await esc.records.certify("rec_Z4m8", { type: "contemporaneous_record", wording: "auto", reference: "Matter 2026-0412", share: { expires_in: 2592000 }, confirm_charge: true, // only after an administrator approved the quote }); if (error) throw new Error(`${error.code}: ${error.message}`); console.log(certificate.id, certificate.pdf_url, certificate.billing.charge_class); ``` The same call over HTTP: ```bash curl https://esigncomply.com/v1/records/rec_Z4m8/certificates \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: cert-rec_Z4m8-matter-0412" \ -d '{ "type": "contemporaneous_record", "wording": "auto", "reference": "Matter 2026-0412", "confirm_charge": true }' ``` A single-record certificate is synchronous (`201 Created`), with a target of under 10 seconds. If the request would incur a charge and does not carry `confirm_charge: true`, nothing is issued and the quote comes back in the error: ```json { "error": { "type": "billing_error", "code": "certificate_charge_unconfirmed", "message": "This certificate costs $20.00. Resend the request with confirm_charge set to true to issue it.", "quote": { "units": 1, "unit_amount": 2000, "amount": 2000, "currency": "usd", "allowance_remaining": 0, "month_to_date": 4000, "spend_limit": 20000, "charge_class": "charged", "units_included": 0, "units_charged": 1 }, "doc_url": "https://esigncomply.com/docs/api/errors#certificate_charge_unconfirmed", "request_id": "req_8Wd3" } } ``` The issued certificate carries the full `statement`, the `verification` results, `pdf_url`, `json_url` and a `billing` object: `charge_class` (`included`, `charged`, `enterprise`, `test` or `reissue`), `units`, `unit_amount`, `amount`, `currency`, the `allowance` counters, `month_to_date`, `spend_limit` and `confirmed_by`. Treat `charge_class` as an open list. The full response is on the [Certificates API page](https://esigncomply.com/docs/api/certificates.md). > **Never.** Do not build a certificate request that can run without a person confirming the charge. Do not send `confirm_charge: true` by default. Idempotency matters here. A repeat with the same `Idempotency-Key` and body returns the same certificate and is never charged twice. A call without a key, or with a new key, issues a new certificate with a new issue time. Earlier certificates stay retrievable and verifiable. ## Sets of records One certificate can cover many records: one statement plus a manifest that lists every record with its hash, its times and its check results. In the JSON form the manifest is under `statement.manifest`. ```http POST /v1/certificates Authorization: Bearer esc_test_us_... Content-Type: application/json { "type": "contemporaneous_record_set", "filter": { "version_id": "dv_3kT9", "created_after": "2026-12-01T00:00:00Z", "created_before": "2027-06-01T00:00:00Z" }, "wording": "US-NY", "reference": "Arbitration clause, first half of the term", "confirm_charge": true } ``` The call returns `202 Accepted` with `status: "processing"` and a `billing` object with the unit count. The `certificate.issued` webhook carries the certificate ID when it is ready, or poll `GET /v1/certificates/{id}`. The target is under 10 minutes per 1,000 records. - The filter is one of `record_ids[]`, `signer_external_id`, `document_id` or `version_id`, each optionally bounded by `created_after` and `created_before`. - A set of 250 records is three units. A set that needs more units than your allowance has left uses what remains and charges the rest. The quote shows both numbers. - A request above your plan's set size returns [`certificate_set_too_large`](https://esigncomply.com/docs/api/errors.md#certificate_set_too_large) with the count. - Records that fail a precondition are listed in the manifest as excluded, with the reason. They are never silently dropped. - Set certificates identify signers by external ID only. - A filter that matches no records returns `400 invalid_request`. - At most five set jobs run per domain at a time. A sixth returns [`rate_limit_exceeded`](https://esigncomply.com/docs/api/errors.md#rate_limit_exceeded) with `Retry-After`. - If an integrity check fails during the job, the certificate ends with `status: "failed"` and a `failure` object, `certificate.failed` is sent, and nothing is charged. ## Spend limit Each domain has a monthly certificate spend limit: $200 by default. An owner can set it from $0 to $5,000 in the dashboard, or higher on request. A limit of $0 switches paid certificates off. Through the API, send `certificate_spend_limit` in cents to `PATCH /v1/domains/{id}` with a `full_access` key. - A request that would pass the limit returns [`certificate_spend_limit_reached`](https://esigncomply.com/docs/api/errors.md#certificate_spend_limit_reached) and issues nothing. - A charged certificate on a domain with no valid payment method returns [`payment_method_required`](https://esigncomply.com/docs/api/errors.md#payment_method_required). The same code is returned while an invoice for the domain is unpaid. Certificates already issued stay valid and verifiable, and recording, evidence reports and verification are not affected. - Owners are notified at 80% and 100% of the limit, and the `certificate.spend_threshold_reached` webhook is sent. - `GET /v1/usage` reports `certificates: { included, used, remaining, charged_units, resets_at, charged_month_to_date, spend_limit, unit_amount }`. ## What is not charged - Test-mode certificates. - A request that is refused or fails, including a set job that fails. - Downloads, JSON retrieval, share links and verification of an issued certificate. - An idempotent repeat. - One re-issue for the same record or set within 30 days of a certificate whose public-anchor line read "pending". Send `reissue_of: "crt_7Hd2"`. - A certificate re-issued to correct an Esign Comply error. Only you pay Esign Comply. A signer, the holder of a share link or any other reader is never charged, and opening or verifying an issued certificate is free for everyone. Certificate charges are not refunded on a plan change or a cancellation. ## Share links A share link lets someone outside your account open the certificate and run verification without signing in. - Create one with `share: { "expires_in": 2592000 }` on the request, or later with `POST /v1/certificates/{id}/share`. `expires_in` is in seconds: 60 at least, 90 days at most, 30 days when omitted. Only an issued certificate can be shared. - The response carries `share_url` and `share_expires_at`. The link carries an access secret in the URL fragment, which browsers do not send to servers. The secret is shown once and stored only as a hash, so keep the URL. - Revoke every active link for a certificate with `DELETE /v1/certificates/{id}/share`. Opens are counted and shown on the certificate under `share`. - Without the certificate file or the secret, a certificate ID reveals nothing. ```bash curl https://esigncomply.com/v1/certificates/crt_7Hd2/share \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expires_in": 2592000 }' ``` ```json { "object": "certificate_share", "certificate_id": "crt_7Hd2", "id": "shr_2Lp7", "share_url": "https://esigncomply.com/verify/c/crt_7Hd2#", "share_expires_at": "2026-12-21T18:40:02.117Z" } ``` Third parties do not request certificates. You issue one and share it. ## Wording variants `wording` is `auto` (the packs applied on the record) or a pack code that names the forum's variant, for example a record made under `US-CA` with a dispute before a New York court. A code that is not in the catalogue returns [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown). It changes the statement paragraph only: the timing wording, the declaration form and the notice reminder. The underlying facts do not change, and `wording` never changes ceremony rules. `include` is empty by default. `["supplements"]` adds a list of customer-supplied material for the record under the sentence "The following material was supplied by {customer}. Esign Comply received it at the times shown and did not verify its contents." `["network"]` adds network facts where they were captured and you confirm the need. It is refused with [`certificate_field_unavailable`](https://esigncomply.com/docs/api/errors.md#certificate_field_unavailable) for records that hold no network facts, which includes every record made under EU minimal capture. ## Custodian-signed form `type: "custodian_certification"` requests a separate service: a named Esign Comply records custodian reviews the automated statement and signs a dated, unsworn declaration, printed as "Certification of Custodian of Records", with the automated statement attached as an exhibit. - It is asynchronous. The request returns `202 Accepted` with `status: "requested"` and a `service` object that restates the form, the delivery target and the price. `status` then moves through `in_review` to `issued`. The target is 5 business days. - It is a live-mode service on paid plans. In test mode, and on the Free plan, the request returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). - Price: Starter $250 per request. Unlimited: 5 included per subscription year, then $250 per request. Enterprise: by contract. It does not use the certificate allowance. - It covers facts Esign Comply observed and records it made. It does not cover facts you asserted or who the signer was. - A notarized affidavit is not offered. ## Test mode Certificates for test records are free, carry the "TEST" watermark, are sealed with the test key and are not anchored publicly. `billing.charge_class` is `test`. Use them to build and review the request flow, including the quote step, before go-live. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). ## Signer-requested certificates (Planned) > **Planned.** `POST /v1/receipts/{receipt_token}/certificates` is not part of the current API. A signer would request a certificate for their own record from the signer view. The option is off unless you enable it per profile. When on, each request uses your allowance or is charged to you within the spend limit, never to the signer. Until then such a request is refused with [`signer_certificates_disabled`](https://esigncomply.com/docs/api/errors.md#signer_certificates_disabled). ## Standing issue (Planned) > **Planned.** The Enterprise profile option `certify_on_anchor` is not available yet. It would issue the automated statement when a record reaches `anchored` and add it to the evidence package. On Starter and Unlimited every certificate is requested and confirmed one at a time. ## Related - [Evidence](https://esigncomply.com/docs/concepts/evidence.md) for the seal, the timestamp and the checkpoint the statement reports on. - [Verification](https://esigncomply.com/docs/concepts/verification.md) for checking a certificate offline with `esigncomply-verify`. - [Certificates API](https://esigncomply.com/docs/api/certificates.md) for every endpoint and field. --- # Jurisdiction packs Source: https://esigncomply.com/docs/guides/jurisdictions Markdown: https://esigncomply.com/docs/guides/jurisdictions.md Section: Guides > Select rule packs on a profile, pass the signer's state, and read which packs, rules, steps and strings each session applied. A jurisdiction pack is a versioned set of rules for one body of law, published by Esign Comply as data. A profile enables any set of packs. Each session applies the subset that fits the signer and the documents, and the record pins exactly what was applied. Selecting a pack tells Esign Comply which rules to apply. It is not a determination by Esign Comply of which law governs. Read [What a pack is not](#what-a-pack-is-not) before you describe your flow to anyone. Browse every pack, rule and source in the [pack catalogue](https://esigncomply.com/docs/jurisdictions.md). ## Pack codes | Code | Covers | |---|---| | `US-FED` | U.S. federal baseline. Added automatically when any state pack is selected. | | `US-CA`, `US-NY`, `US-FL`, `US-TX`, `US-DE`, `US-VA`, `US-MA` | State packs. Each holds only its differences from `US-FED` and never relaxes a Federal rule. | | `EU`, `UK`, `CH` | Separate packs for EU and EEA, United Kingdom and Swiss flows | Read the catalogue from `GET /v1/jurisdictions` and do not hard-code it. New packs need no SDK release. An unknown code returns [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown). Every published pack is available on every plan, in test mode and live, in any combination, at no per-pack fee. ## Select packs on a profile ```bash curl https://esigncomply.com/v1/profiles \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Signup", "jurisdictions": ["US-FED", "US-CA", "US-NY"], "jurisdiction_mode": "auto", "on_unknown_region": "strictest", "governing_law": "US-NY", "method": "checkbox", "assurance_level": "L1" }' ``` | Field | Values | Default | Effect | |---|---|---|---| | `jurisdictions` | Pack codes | `["US-FED"]` | The packs this profile enables | | `jurisdiction_mode` | `auto`, `strictest`, `explicit` | `auto` | How enabled packs are applied per session | | `on_unknown_region` | `strictest`, `base_only`, `reject` | `strictest` | What happens when a U.S. signer has no `signer.region` | | `governing_law` | A pack code or ISO 3166 code | `null` | Fires the governing-law rules of that pack | | `allow_session_packs` | Boolean | `false` | Lets a session add a pack the profile does not enable | | `strict_jurisdictions` | Boolean | `false` | Turns the `jurisdiction_not_enabled` warning into an error | | `pack_versions` | `"latest"` or a map of code to version | `"latest"` | Pinning is an Enterprise option | Creating a profile adopts every record condition of the packs it enables. Packs you add later start in advise. See [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md). ## Modes | Mode | Which packs apply | Which rules fire | `reason` on the applied pack | |---|---|---|---| | `auto` | An enabled pack applies when the signer's asserted location matches it, when `governing_law` names it, or when your organization's registered state matches it. `US-FED` applies to every U.S. signer. | Only rules whose trigger matched. A consumer rule keyed to the signer's residence does not fire merely because the contract names that state's law. | `base`, `signer_region`, `governing_law`, `organization_region` | | `strictest` | Every enabled pack, whatever the signer's location | Every in-scope rule of every applied pack | `strictest` | | `explicit` | Exactly the packs the session sends in `jurisdictions.packs` | Every in-scope rule of those packs | `explicit` | In `explicit` mode a session without `jurisdictions.packs` returns `400 invalid_request`. ## Pass the signer's location Location is asserted by you. Esign Comply does not choose law from an IP address, and neither should your code. ```ts const { data: session, error } = await esc.sessions.create( { profile: "prof_signup_4f1a", signer: { external_id: "user_7c1d", email: "dana@example.org", class: "consumer", country: "US", region: "US-CA", // from your signup form's State field or your account data }, documents: [{ document: "doc_8Hq2", version: "current" }], context: { url: "http://localhost:3000/signup", locale: "en-US", purpose: "account_signup" }, }, { idempotencyKey: "signup-user_7c1d" }, ); if (error) throw new Error(`${error.code}: ${error.message}`); ``` - `signer.region` is an ISO 3166-2 code (`US-CA`) or a bare subdivision code with `signer.country` (`CA` with `US`). It is normalized to ISO 3166-2 before sealing. A value in neither form adds the warning `signer_region_unrecognized`. - It means the state where the signer resides or, for the `employee` class, primarily works. - `signer.locality` (for example `NYC`) is optional and read only by rules that declare a locality scope. - `signer.country` selects the base pack outside the United States: EU and EEA countries map to `EU`, `GB` to `UK`, `CH` to `CH`. A region that starts with `US-` implies the United States. - `signer.class` is `consumer`, `business` or `employee`. Where it is missing, rules treat the signer as the most protected class in scope. If your form has no State field, add one. Do not guess. ## Unknown state When a U.S. signer has no `signer.region` and the profile enables state packs, `on_unknown_region` decides: | Value | Behavior | |---|---| | `strictest` (default) | Every enabled state pack applies. Warning `signer_region_missing`. | | `base_only` | `US-FED` applies alone. Warning `signer_region_missing`. | | `reject` | The session is refused with [`signer_region_required`](https://esigncomply.com/docs/api/errors.md#signer_region_required). | When the country is unknown as well, every enabled pack applies with reason `strictest` and the warning `signer_country_missing`. When the country is known and no pack covers it, the warning is `signer_country_not_covered:`. ## A state without a pack When `signer.region` names a state that has no pack, `US-FED` applies and the session carries the warning `state_pack_unavailable:`, for example `state_pack_unavailable:US-WA`. The record states that no state-specific rules were applied for the signer's location. Do not tell the user the flow meets that state's law. The same warning appears in live mode for a state pack that is still a research draft: it is not applied to live sessions until counsel admitted in that state has reviewed it. In test mode the draft pack applies in full so you can build against it. ## Governing law `governing_law` on the profile, or `jurisdictions.governing_law` on one session, names the law your documents choose. In `auto` mode it applies that pack with reason `governing_law` and fires only the rules triggered by governing law, such as evidence wording. If the code has no pack, the session proceeds with the warning `governing_law_no_pack:`. The forum for a dispute is not a session field. You choose it when you request a certificate. See [Certificates](https://esigncomply.com/docs/guides/certificates.md). ## Session overrides A session may narrow or redirect the profile's packs for one ceremony: ```json { "jurisdictions": { "mode": "explicit", "packs": ["US-FED", "US-CA"], "governing_law": "US-NY" } } ``` - A session may narrow the profile's packs freely. - It may add a pack the profile does not enable only when `allow_session_packs` is true. A pack added by a session is not part of the profile's baseline, so its record conditions run in advise and add no required step. - Otherwise the session proceeds under the profile's packs with the warning `jurisdiction_not_enabled:`, and the record says the named pack was not applied. - With `strict_jurisdictions: true` the session is refused with [`jurisdiction_not_enabled`](https://esigncomply.com/docs/api/errors.md#jurisdiction_not_enabled) instead. Disabling a pack on a profile with live traffic never causes an error by default. See the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md). ## Facts Some rules depend on facts only you know: whether a subscription has a free trial, which state a company is formed in, whether a document is a noncompete. Pass them in `context.facts`: ```json { "context": { "purpose": "auto_renewal", "facts": { "subscription.trial_days": 14, "subscription.auto_renews": true, "document_category": "other" } } } ``` - Each pack in the catalogue lists the fact keys its rules read, with type, allowed values and rule IDs. Read them from the [pack pages](https://esigncomply.com/docs/jurisdictions.md). - Facts are sealed in the record and labeled asserted. Esign Comply does not verify them. - A boolean flag you do not send is treated as not flagged. - When a rule that fired needs a fact that is absent, the session carries `fact_missing:` and the rule does not fire. Its obligations and recommendations are still listed. - For an adopted Block condition in live mode the session is refused with [`jurisdiction_fact_required`](https://esigncomply.com/docs/api/errors.md#jurisdiction_fact_required). The error names the key in `param` and the rule ID in `rule`. - A key that no rule reads is stored as sent with the warning `fact_unrecognized:`. It is never rejected. Fact keys are never renamed. The `document_category` fact also feeds the exclusion screen. A category blocked by any applied pack returns [`document_type_excluded`](https://esigncomply.com/docs/api/errors.md#document_type_excluded) with the rule ID. A category that needs review adds `document_type_requires_review:`. The general exclusions of the Federal pack screen every session. ## Read what was applied Session creation returns the resolution. Use it at run time. Do not hard-code which state rules apply. ```json { "applied_jurisdictions": [ { "code": "US-FED", "version": "2026-11-21", "reason": "base" }, { "code": "US-CA", "version": "2026-11-21", "reason": "signer_region" }, { "code": "US-NY", "version": "2026-11-21", "reason": "governing_law" } ], "jurisdiction_mode": "auto", "rule_set_version": "2026.11.21", "rules_fired": ["US-01", "US-08", "US-09", "US-11"], "required_steps": ["client.attached", "document.presented:dv_3kT9", "notice.captured", "intent.captured", "signature.applied"], "required_strings": [], "retention_floor": null, "guidance_release": "2026.11.3", "advisories": [], "warnings": [] } ``` | Field | What to do with it | |---|---| | `applied_jurisdictions` | Log it. The same list is sealed in the record under `jurisdictions.applied`. | | `rules_fired` | Rule IDs that fired. Each links to the catalogue. | | `required_steps` | The authoritative step list. Render a state-specific step only when this list contains it. | | `required_strings` | Wording a pack asks the page to carry. Render each one in the slot it names. | | `retention_floor` | The longest floor among applied packs, when one applies | | `advisories` | Record conditions in advise that were not met. They never change the status code or `required_steps`. | | `warnings` | Non-blocking concerns. The list is open. | Each `required_strings` entry has this shape: ```json { "slot": "renewal_consent", "block": "us.purchase", "rule": "US-20", "kind": "verbatim", "text": "I agree that my subscription continues and renews automatically every {renewal term} at {price}{, which may change to {new price} on {date}} until I cancel. {Minimum purchase obligation, if any.} Cancellation policy: {cancellation policy}. I can cancel at {cancel path}.", "label": "us.purchase renewal consent (unchecked; by Esign Comply policy separate from the terms checkbox)", "statutory": false, "check": true } ``` `kind` is `verbatim` (text with `{slots}` you fill in) or `elements` (a list of required elements you supply). `statutory: true` marks text quoted from a statute: render it exactly. `check: true` means the conformance engine looks for the wording in the captured assent region ([CR-20](https://esigncomply.com/docs/conformance.md#cr-20)). `check: false` marks wording that lives outside the ceremony, such as a reminder email. The browser SDK returns the same list from `ceremony.requiredStrings()`. ## Composition When several packs apply, they compose: - Required steps are the union across applied packs. - For each parameter the most protective value wins: the longest retention floor, the stricter signature method, the larger minimum text size. - Exclusion screens are a union. A document category blocked by any applied pack is blocked. - Where two packs dictate wording for the same slot, the catalogue publishes a merged string that carries every required element. ## Warnings you may see | Warning | Meaning | |---|---| | `signer_country_missing` | No `signer.country` and none could be inferred | | `signer_region_missing` | U.S. signer without a state; `on_unknown_region` was applied | | `signer_region_unrecognized` | `signer.region` is not an ISO 3166-2 code | | `signer_country_not_covered:` | No pack covers the signer's country; every enabled pack was applied | | `signer_class_missing` | A purchase-type purpose without `signer.class` | | `state_pack_unavailable:` | No pack for that state, or the pack is a research draft and the session is live | | `jurisdiction_not_enabled:` | A matching pack exists and the profile does not enable it | | `governing_law_no_pack:` | `governing_law` names a jurisdiction with no pack | | `fact_missing:`, `fact_unrecognized:` | See [Facts](#facts) | | `document_type_requires_review:` | The exclusion screen flagged the document category for review | | `record_conditions_pending_adoption` | Live session on a profile with record conditions waiting in advise | | `pack_version_stale` | The profile's baseline is more than 12 months behind the latest pack version. Recording continues. | | `pack_not_counsel_reviewed:` | Live session under a pack whose record conditions are not yet counsel-reviewed. They run in advise. | Warnings never block. Treat unknown entries as information. ## Dry run `POST /v1/jurisdictions/resolve` accepts the same inputs as session creation and returns the resolution without creating a session. Nothing is metered. ```bash curl https://esigncomply.com/v1/jurisdictions/resolve \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile": "prof_signup_4f1a", "signer": { "class": "consumer", "country": "US", "region": "US-CA" }, "documents": [{ "document": "doc_8Hq2", "version": "current" }], "context": { "purpose": "auto_renewal" } }' ``` Any secret key can call it. Only `profile` is required. The response has `object: "jurisdiction_resolution"` and the same fields as above, plus: | Field | Content | |---|---| | `rule_states[]` | For each fired rule with a record condition: `rule`, `state` (`enforce` or `advise`) and `level` (`block` or `warn`) | | `exclusions[]` | Exclusion-screen hits for the declared `document_category` | | `obligations[]`, `recommendations[]`, `reports[]` | The parts of the resolved rules that are yours, each with rule ID, pack, text and sources | | `baseline` | `current` or `latest`, as requested | | `would_fail` | Present when session creation would be refused for an excluded document category or a missing fact: `code`, `message`, `rule`. The dry run itself still returns `200`. | Two inputs change what the dry run enforces: - `baseline: "latest"` shows what adoption of pending record conditions would require. The default, `"current"`, shows what the profile's baseline enforces today. - `livemode: true` previews live behavior with a test key. Without it, a test key shows what test mode does: every condition of the latest release enforced, and research-draft state packs applied. The conformance checker uses the same call: `npx esigncomply check --region US-CA --region US-NY`. See the [Jurisdictions API](https://esigncomply.com/docs/api/jurisdictions.md). ## What a pack is not - A pack records which rules Esign Comply applied. It is not a statement that a flow meets the law of a jurisdiction. - A pack covers selected rules, not every law in that state or country. Each pack lists the topics it covers in `coverage[]` and the topics it does not in `not_covered[]`. Read both on the pack's page. - State packs are research drafts until reviewed by counsel admitted in that state. `reviewed_at` is `null` until then, and a draft state pack runs in test mode only. - A pack does not perform your duties. Rules are split into parts: what Esign Comply records or checks, your obligations, recommendations, and what you can send. Esign Comply lists the obligations and does not perform, monitor or verify them. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md). - Later pack versions never change a sealed record. The record keeps the pack versions, the asserted inputs and each condition's state as they were. Your team is responsible for legal review and for building and sending post-signing notices. Ask your counsel whether your documents and signers have requirements beyond those a pack describes. --- # Guidance and adoption Source: https://esigncomply.com/docs/guides/guidance Markdown: https://esigncomply.com/docs/guides/guidance.md Section: Guides > How rule changes reach you as notices, why they never stop an existing integration from recording, and how to adopt or roll back new record conditions. Rules, obligations, recommendations and legal notices change far more often than an API should. Esign Comply publishes them as data on their own release train, separate from code deployments and separate from the API contract. You and your AI coding tool can read every change, and nothing in a guidance release can stop an existing integration from recording. A guidance update does not break your existing recording integration. You may still need to change your flow to meet a new legal requirement. That decision is yours. ## What guidance contains | Item | What it is | Where you meet it | |---|---|---| | Pack version | The rules of one jurisdiction pack, each split into parts with a class | Session resolution, conformance findings, reports | | Obligation | A duty the cited law places on you, with its source, scope and duty holder | The generated prompt, the dashboard obligations list, `GET /v1/profiles/{id}/guidance` | | Recommendation | A practice Esign Comply suggests | Same | | Fixed string | Wording the law constrains, with slots | `required_strings[]`, prompt blocks | | Prompt block | Reviewed text for AI coding tools | The prompt generator | | Notice | A dated message about a legal or product change in a state, country or locality | Inbox, email, webhook, feeds, API | Each publication is a guidance release with an ID such as `2026.11.3`, a content hash and a changelog. Scheduled releases go out weekly. An urgent release can go out the same business day. Every session and every record carries the `guidance_release` in force, so you can later show what you were told and when. Guidance is product information drawn from the sources it cites. It is not legal advice and it is not exhaustive. ## Notices A notice (`ntc_...`) tells you about one change: ```json { "object": "guidance_notice", "id": "ntc_2026_0931", "release": "2026.11.3", "published_at": "2026-11-17T15:00:00Z", "kind": "law_effective", "class": "obligation", "severity": "action_required", "jurisdictions": ["US-NY", "US-NY/NYC"], "topics": ["auto_renewal", "cancellation"], "title": "New York City: online cancellation after in-person signup", "summary": "...", "effective_at": "2026-10-01T04:00:00Z", "what_changes": { "esign_comply_record": "None.", "your_obligations": "...", "recommendations": "..." }, "affected_rules": ["NY-07"], "affected_profiles": ["prof_signup_4f1a"], "requires_code_change": "only_to_follow_the_rule", "update_prompt": "upd_7c1e", "review": { "state": "research_reviewed", "counsel_reviewed_at": null }, "sources": [{ "title": "...", "url": "..." }], "supersedes": null, "url": "https://esigncomply.com/docs/guidance/ntc_2026_0931", "acknowledgment": { "state": "unread", "note": null, "at": null } } ``` | Field | Values | |---|---| | `kind` | `law_enacted`, `law_effective`, `rule_change`, `case_law`, `regulator_guidance`, `enforcement_action`, `correction`, `product` | | `class` | `record_change` (Esign Comply's own behavior changes), `obligation`, `recommendation`, `information` | | `severity` | `action_required`, `recommended`, `info` | | `jurisdictions` | A pack code, an ISO 3166-1 country (`DE`), an ISO 3166-2 subdivision (`US-IL`), or a locality (`US-NY/NYC`) | | `review.state` | `draft`, `research_reviewed`, `counsel_reviewed` | `GET /v1/guidance/notices` and `GET /v1/guidance/notices/{id}` work without a key and then return the public fields only. With a secret key they add `affected_profiles` and your domain's `acknowledgment`. Treat all of these lists as open: new values may appear without a new API version. A notice may cover a place that has no pack yet, so you can hear about a change before a pack exists. An item found to be wrong is corrected by a new notice that supersedes it. The earlier one stays readable and is marked superseded. ## The three-way split Every notice states three things separately in `what_changes`, even when one of them is "None": | Key | Question it answers | |---|---| | `esign_comply_record` | What changes in what Esign Comply records or checks? | | `your_obligations` | What changes in the duties the law places on you? Esign Comply lists these. It does not perform, monitor or verify them. | | `recommendations` | What does Esign Comply suggest? Recommendations are not legal requirements or conditions of recording. | `requires_code_change` then says whether your code must change: | Value | Meaning | |---|---| | `no` | Nothing to build | | `only_to_follow_the_rule` | Recording is unaffected. You change your flow only if you decide to follow the obligation or recommendation. | | `to_adopt_a_record_condition` | A new record condition is waiting in advise. Your interface must satisfy it before you adopt it. | A notice never says that your flow is or is not lawful. ## Channels | Channel | Behavior | |---|---| | Dashboard inbox | With an unread count | | Email | To organization owners and to a notices address you configure. At once for `action_required`, weekly digest otherwise. | | Webhooks | `guidance.notice_published` and `guidance.release_published` | | API | `GET /v1/guidance/notices` with filters `jurisdiction`, `class`, `severity`, `kind`, `topic`, `since`, `affecting_profile` | | Public changelog | Atom and JSON feeds, filterable by jurisdiction | A notice reaches your domain when its jurisdictions overlap your enabled packs, your watched jurisdictions or your organization's own country and state, and its topics overlap your profiles' purposes, document types or facts. Every notice is also in the public feed, which is open to everyone. Dashboard, email, webhook and API delivery are included in every paid plan. ### Watch a jurisdiction You can watch any jurisdiction code without enabling a pack, for example `US-IL` or `FR`, to receive its notices. The call replaces the whole list and needs a `full_access` key. Up to 100 codes. ```bash curl -X PUT https://esigncomply.com/v1/domains/dom_4Kx9/watched-jurisdictions \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jurisdictions": ["US-IL", "FR", "US-NY/NYC"] }' ``` See the [Guidance API](https://esigncomply.com/docs/api/guidance.md). ### Forward notices from a webhook The handler forwards the notice to people. It never changes application behavior by itself. ```ts // app/api/esigncomply/webhook/route.ts import { esc } from "@/lib/esigncomply"; import { sendAdminEmail } from "@/lib/email"; // your own mailer export const runtime = "nodejs"; export async function POST(request: Request) { const rawBody = await request.text(); const { data: event, error } = esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!); if (error) return new Response("Invalid signature", { status: 400 }); if (event.type === "guidance.notice_published") { const { data: notice } = await esc.guidance.notices.get(event.data.notice_id); if (notice) { await sendAdminEmail({ subject: `[Esign Comply] ${notice.severity}: ${notice.title}`, text: [ notice.summary, `Record: ${notice.what_changes.esign_comply_record}`, `Your obligations: ${notice.what_changes.your_obligations}`, `Recommendations: ${notice.what_changes.recommendations}`, `Code change: ${notice.requires_code_change}`, notice.update_prompt ? `Update prompt: ${notice.update_prompt}` : "", ].join("\n\n"), }); } } // Ignore event types you do not recognize and return 200. return new Response(null, { status: 200 }); } ``` Handle deliveries idempotently on `webhook-id`. If you prefer polling, call `GET /v1/guidance/notices?since=` on a schedule. See [Webhooks](https://esigncomply.com/docs/api/webhooks.md). ## Acknowledgments An owner, admin or developer may mark a notice `read`, `applied` or `not_applicable`, with a note. Through the API this needs a `full_access` key: ```bash curl https://esigncomply.com/v1/guidance/notices/ntc_2026_0931/acknowledge \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "state": "applied", "note": "Cancellation link added to account settings." }' ``` ```json { "object": "guidance_acknowledgment", "notice_id": "ntc_2026_0931", "state": "applied", "note": "Cancellation link added to account settings." } ``` - Acknowledgment never gates recording. - Unacknowledged `action_required` notices are repeated by email at 7 and 30 days. - Esign Comply keeps a delivery log per domain: each notice delivery (channel, address or endpoint, time, result) and each acknowledgment (member, time, state). You can export it. - An acknowledgment is your own working note. It is not a finding that an obligation was met, and it never appears on an evidence report or a certificate. ## Update prompts A notice that changes what you build carries an update prompt (`upd_...`): a short reviewed block that describes only the change, under the same four headings as the original prompt: "Required for the record", "Your obligations", "Recommendations" and "What you can send us". It names the prompt ID it updates and opens with a line that says your existing integration keeps recording whether or not you apply it. Fetch it with `GET /v1/guidance/updates/upd_7c1e`, or `esc.guidance.updates.get("upd_7c1e")`. The response is JSON with the prompt in a `markdown` field. Send `Accept: text/markdown` to get the raw Markdown instead. Give it to your coding tool under review. Applying it is your choice. Code built from any earlier prompt keeps working against the API version it was written for. ## Advise until adopted Only record conditions can refuse to seal a record, add a required step or require a fact. And only the ones your profile has adopted. Each profile has a **baseline**: the pack versions whose record conditions it has adopted. Creating a profile adopts every record condition of the packs it enables at that moment. A record condition that arrives later, from a newer pack version or from a pack you have just enabled, runs in the `advise` state for that profile: - It is evaluated on every session. - Its result is stored beside the record and returned in `advisories[]`, each with the rule ID and a finding. - It never returns an error and never adds to `required_steps`. - Live sessions on that profile carry the warning `record_conditions_pending_adoption`. Everything that cannot stop a call applies to every profile at its `effective_at`: obligations, recommendations, notices, evidence wording and fixed-string text. A relaxed or retired record condition also stops blocking at once. Test mode always evaluates the latest release with every condition enforced, so you see what adoption would require before it reaches live traffic. Test mode still never blocks on a finding: it reports them. The dry run does the same comparison with `baseline: "latest"`. See [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md). ### See what is pending `GET /v1/profiles/prof_signup_4f1a` lists the conditions waiting for adoption: ```json { "object": "profile", "id": "prof_signup_4f1a", "version": 3, "jurisdictions": ["US-FED", "US-CA", "US-NY"], "baseline": "bl_7Qm2", "pending_conditions": [ { "rule": "CA-08", "pack": "US-CA", "level": "block", "reason": "new_pack" }, { "rule": "NY-03", "pack": "US-NY", "level": "warn", "reason": "changed" } ] } ``` `reason` is `new_pack` (you enabled the pack after the baseline was set), `new_rule` (a newer pack version added the rule) or `changed` (the rule's record condition changed). `GET /v1/profiles/{id}/guidance` returns everything that applies to the profile now, grouped by class: | Group | Each item carries | |---|---| | `record_conditions[]` | `rule`, `pack`, `title`, `text`, `level` (`block` or `warn`), `adoption` (`adopted` or `pending`), `adds_steps`, `checks`, `sources`, `review_state` | | `obligations[]` | `rule`, `pack`, `title`, `duty_holder`, `text`, `sources`, `review_state`, your team's `mark`, and `reports_received` (a count of supplements that name the rule) | | `recommendations[]` | `rule`, `pack`, `title`, `text`, `sources`, `review_state`, your team's `mark` | | `reports[]` | `rule`, `pack`, `title`, `text`, `supplement_types` you can send | A `mark` (`handled`, `not_applicable` or `open`) is your team's working note. `reports_received` is information for you. Neither is a finding that an obligation was met, and neither appears on an evidence report or a certificate. ### Adopt 1. Read the notice and the update prompt. 2. Apply the update prompt in your codebase and run it in test mode, where the new condition is already enforced. 3. Run the conformance check and fix findings marked `block`. See [Conformance](https://esigncomply.com/docs/conformance.md). 4. Adopt: ```bash curl -X POST https://esigncomply.com/v1/profiles/prof_signup_4f1a/adopt \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "note": "Adopted after test run on 2026-12-02." }' ``` Adoption needs a `full_access` key. It moves every pending record condition of the profile's packs to `enforce`, and writes a new baseline and a new profile version. The response is the profile at its new version, with what was adopted: ```json { "object": "profile", "id": "prof_signup_4f1a", "version": 4, "jurisdictions": ["US-FED", "US-CA", "US-NY"], "baseline": "bl_9Rk4", "change_note": "Adopted after test run on 2026-12-02.", "adopted": [ { "rule": "CA-08", "pack": "US-CA", "level": "block", "adds_steps": ["renewal_terms.presented", "renewal_consent.captured"] }, { "rule": "NY-03", "pack": "US-NY", "level": "warn", "adds_steps": [] } ], "baseline_detail": { "id": "bl_9Rk4", "pack_versions": { "US-FED": "2026-11-21", "US-CA": "2026-11-21", "US-NY": "2026-11-21" }, "rollback_until": "2027-03-02T16:20:11.402Z" } } ``` The other profile fields are omitted here. The `profile.adopted` webhook follows: ```json { "object": "event", "id": "whe_3Yb8", "type": "profile.adopted", "api_version": "2026-11-21", "livemode": true, "created_at": "2026-12-02T16:20:11.402Z", "data": { "profile_id": "prof_signup_4f1a", "profile_version": 4, "baseline": "bl_9Rk4", "adopted_rules": ["CA-08", "NY-03"], "adopted_by": "key:key_2bQ1" } } ``` Sessions already created keep the profile version they pinned. If nothing is pending, the call returns [`baseline_unchanged`](https://esigncomply.com/docs/api/errors.md#baseline_unchanged) (409). Esign Comply never adopts on your behalf. A record condition also enforces in live mode only once counsel has reviewed its pack. Until then it runs in advise even after adoption, and sessions carry `pack_not_counsel_reviewed:`. ### Roll back ```bash curl -X POST https://esigncomply.com/v1/profiles/prof_signup_4f1a/rollback \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" ``` Rollback returns the profile to its previous baseline, writes a new profile version and sends `profile.rolled_back`. The response is the profile at its new version with `baseline_detail`. It is available for 90 days after an adoption. After that, or when there is no earlier baseline, the call returns [`rollback_unavailable`](https://esigncomply.com/docs/api/errors.md#rollback_unavailable) (409). Records sealed while the newer baseline was in force keep it: a sealed record pins each condition's state and result. ## Adding or removing a state - **Adding.** Enabling a pack on a profile with live traffic needs no code change to keep recording. The pack's obligations, recommendations and notices apply at once. Its record conditions start in advise, and state-specific steps appear in `required_steps` only after adoption. - **Removing.** Disabling a pack never causes an error. A session that would have used it proceeds under the remaining packs with the warning `jurisdiction_not_enabled:`, and the record says the pack was not applied. The full rules are in the [compatibility contract](https://esigncomply.com/docs/concepts/compatibility.md). ## Related webhooks | Event | Sent when | |---|---| | `guidance.notice_published` | A notice that targets your domain was published. Payload: notice ID, kind, class, severity, jurisdictions, `effective_at`, affected profile IDs, update prompt ID. | | `guidance.release_published` | A guidance release was published that concerns your domain: a pack you enable or a jurisdiction you watch. Payload: `release_id`, `content_hash`, `published_at`, counts `added`, `changed` and `retired`, `jurisdictions`, `url`. | | `jurisdiction.pack_updated` | A new version of a pack enabled on one of your profiles was published. Payload: `code`, `previous_version`, `version`, `effective_at`, `adds_block_rule`, `adds_required_step`, `affected_profiles`. | | `profile.adoption_available` | A guidance release left a profile with record conditions waiting in advise. Payload: `profile_id`, `profile_version`, `pending_rules`, `pack_versions`, `url`. | | `profile.adopted`, `profile.rolled_back` | A member or key adopted, or the profile returned to its previous baseline | --- # AI app builders Source: https://esigncomply.com/docs/guides/ai-builders Markdown: https://esigncomply.com/docs/guides/ai-builders.md Section: Guides > Where to store the secret key in v0, Lovable, Bolt and Replit, how to keep it out of client code, and how previews and platform hosts work. AI app builders such as v0, Lovable, Bolt and Replit write and host an application for you. The Esign Comply integration is the same as anywhere else: your server holds a secret key and creates sessions, and the browser holds only a short-lived session client token. What changes is where the secret lives, which host your preview runs on, and how the domain is verified. This page describes mechanisms, not menus. Builders rename their settings often. Look for the builder's "environment variables" or "secrets" setting for server-side code. ## The credentials | Credential | Looks like | Who holds it | |---|---|---| | Secret API key | `esc_test_us_...`, `esc_live_us_...` | Server code only, read from a secret store | | Webhook signing secret | `whsec_...` | Server code only | | Session client token | `esc_ct_...` | The signer's browser, in memory, for one session | There are no publishable keys. Nothing that starts with `esc_test_` or `esc_live_` ever belongs in code that runs in a browser. ## You create the account You create the account and accept the terms once. No card. After that your AI agent can do the rest: create keys, register documents, build the flow, verify the domain and go live. To hand over, start at [`/signup?next=/dashboard/agent`](https://esigncomply.com/signup?next=/dashboard/agent). Sign-up ends on **Agent access**, where you press **Create agent token**. The token starts with `esc_agent_`, acts as you with your role, expires after the time you choose and can be revoked there at any time. The agent stores it as `ESIGNCOMPLY_AGENT_TOKEN` in the builder's secret setting and uses it two ways: it logs in to the dashboard at `/agent-login`, or it calls the [agent account API](https://esigncomply.com/docs/api/agent.md). With the token it creates the test key, registers and verifies the domain, and creates the live key when you say go live. The steps are in the [guide for AI agents](https://esigncomply.com/agents.md). A key is shown once, when it is created. It belongs in the builder's secret setting. Chat messages can end up in generated source, in logs and in project history, so keys and tokens stay out of the chat: the agent fetches its keys with the agent token and writes them to the secret setting. See the credential rules at [/auth.md](https://esigncomply.com/auth.md) and the agent runbook at [/setup.md](https://esigncomply.com/setup.md). ## Where the key goes | Builder | What it usually generates | Where to store the key | Where sessions are created | |---|---|---|---| | v0 | A Next.js application deployed on Vercel | The project's environment variables, without a `NEXT_PUBLIC_` prefix | Route handlers and server actions | | Lovable | A browser application with a hosted backend for data, auth and functions | The secrets of the backend functions | A backend function | | Bolt | Varies with the stack you asked for. Often a browser application, sometimes with a server | The project's server-side environment variables or backend function secrets | Server routes or a backend function | | Replit | An application with a server process | The workspace secrets, which the server reads as environment variables | Server routes | Use these names everywhere so that generated prompts and code line up: ```bash ESIGNCOMPLY_API_KEY=esc_test_us_... ESIGNCOMPLY_WEBHOOK_SECRET=whsec_... ``` ### If the application has no server A browser-only application, such as a single-page app built with a bundler, has nowhere safe to keep a secret. Every variable the bundler can see is shipped to the browser. Do not put the key there, under any prefix. Add a small server piece instead: a backend function, a serverless function or a server route. It does two jobs, and only these two need the key: 1. Create the session and return the client token. 2. Confirm the record before your application grants access. A backend function that creates a session, written with `fetch` so it runs on any server runtime: ```ts // A backend function, for example supabase/functions/start-ceremony/index.ts const cors = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type", }; Deno.serve(async (req) => { if (req.method === "OPTIONS") return new Response("ok", { headers: cors }); // 1. Authenticate YOUR user here with your own auth, and load their ID and email // from your database. Do not accept them from the request body. const user = await getSignedInUser(req); // your code if (!user) return new Response("Unauthorized", { status: 401, headers: cors }); // The page sends 1 at first and a higher number when it needs a new session (expired, inputs changed). const { attempt = 1 } = (await req.json().catch(() => ({}))) as { attempt?: number }; // 2. Create the session with the secret key, which only this function can read. const res = await fetch("https://esigncomply.com/v1/sessions", { method: "POST", headers: { Authorization: `Bearer ${Deno.env.get("ESIGNCOMPLY_API_KEY")}`, "Content-Type": "application/json", "Idempotency-Key": `signup-${user.id}-${Number(attempt) || 1}`, }, body: JSON.stringify({ profile: "prof_signup_4f1a", signer: { external_id: user.id, email: user.email, class: "consumer", country: user.country }, documents: [ { document: "doc_8Hq2", version: "current" }, { document: "doc_Pv71", version: "current" }, ], context: { url: `${req.headers.get("origin")}/signup`, purpose: "account_signup" }, }), }); const session = await res.json(); if (!res.ok) { return Response.json({ error: session.error?.code ?? "session_failed" }, { status: 502, headers: cors }); } // 3. Save session.id and the pinned version IDs in your own database for confirmation. await saveCeremony(user.id, session.id, session.documents.map((d: { version_id: string }) => d.version_id)); // your code // 4. Send the browser only what it needs. Never the key, never the whole response. return Response.json( { clientToken: session.client_token, apiUrl: session.api_url, documents: session.documents.map((d: { document_id: string; version_id: string; title: string }) => ({ documentId: d.document_id, versionId: d.version_id, title: d.title, })), }, { headers: cors }, ); }); ``` The browser then attaches with the client token, exactly as in the [quickstart](https://esigncomply.com/docs/quickstart.md): ```ts import { EsignComply } from "@esigncomply/browser"; const ceremony = await EsignComply.attach({ clientToken, apiUrl }); ``` Write a second function for [server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). Do not let the browser decide that an acceptance happened, and do not let it write to your acceptances table. With row-level security, give that table a read policy only, and write to it from the backend function. ## Keep the key out of client code Rules for the tool, and for you when you review what it wrote: - Only server code reads `ESIGNCOMPLY_API_KEY`: route handlers, server actions, backend functions. - No public prefix, ever. Variables named `NEXT_PUBLIC_…`, `VITE_…`, `PUBLIC_…`, `REACT_APP_…` or `EXPO_PUBLIC_…` are copied into the browser bundle by design. - The key is never written in source code, in a prompt, in a comment or in a commit. `.env` files stay out of version control. - No file marked `"use client"` imports the `esigncomply` server package. In Next.js, start the module that creates the client with `import "server-only"`. - The browser calls Esign Comply directly with the client token. Do not proxy `@esigncomply/browser` calls through your own server, and do not build a proxy route that adds the secret key to browser requests. - A server route returns `client_token`, `api_url` and the document version IDs. It does not return the key, and it does not echo environment variables in error messages. The API helps a little. `EsignComply.attach` refuses anything that is not a client token, endpoints for secret keys refuse client tokens with [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission), and a key created for an application has the `recording_access` permission by default, which cannot download evidence reports, evidence packages or certificates. None of that makes a leaked key safe. Treat it as a password. ### Check the bundle After a production build, search the files that are served to browsers: ```bash grep -RIl -e "esc_test_" -e "esc_live_" -e "ESIGNCOMPLY_API_KEY" .next/static dist build public 2>/dev/null \ && echo "LEAK: the key or its variable name is in client files" \ || echo "clean" ``` Then open the browser's network panel on your signing page. Requests to `esigncomply.com` must carry `Authorization: Bearer esc_ct_...` and nothing else. No request from the browser to your own server should contain or return a value that starts with `esc_test_` or `esc_live_`. Check the repository too: ```bash git ls-files | grep -E '(^|/)\.env' && echo "An env file is committed" || echo "clean" git grep -n -e "esc_test_" -e "esc_live_" -e "whsec_" || echo "clean" ``` ## Previews and the test allowlist Test keys work on `localhost` and `127.0.0.1` with no setup. A builder's preview runs on the builder's own host, so add that host to your test origins first. Otherwise session creation and browser calls return [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch), and the message names the origin that was refused. Add hosts in the dashboard under Domains, or with the API: ```bash curl -X PATCH https://esigncomply.com/v1/domains/dom_4Kx9 \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "test_origins": ["my-project-preview.example-builder.app"] }' ``` - List the exact preview host of your project. An entry also covers its subdomains, so do not list a platform's shared suffix. - Some builders run the preview in a frame on a different host than the one in your address bar. Use the origin named in the `domain_mismatch` message. - Preview hosts change between projects and sometimes between sessions. Update the list when the host changes. You can list up to 25. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). ## Going live on a platform host To record live you need a verified domain. A host on a shared platform suffix, such as `myapp.vercel.app`, `myapp.lovable.app` or `myapp.replit.app`, registers as its own domain and verifies with a file, because you cannot add DNS records there: ```text https://myapp.lovable.app/.well-known/esigncomply.txt ``` The file contains the token from the dashboard. In most generated projects, a file placed under the `public` folder at `.well-known/esigncomply.txt` is served at that address. Check it before you trigger verification: ```bash curl -i https://myapp.lovable.app/.well-known/esigncomply.txt ``` You should get status `200` and the token as plain text. A single-page application that answers every unknown path with its HTML page will return `200` with the wrong body. If that happens, add the static file, or a server route for that exact path. If you plan to use your own domain, register that domain instead and verify by DNS. Moving from a platform host to a custom domain later is a domain change, and a subscription can change its domain once per 12 months without contacting support. See [Register a domain](https://esigncomply.com/docs/guides/domains.md). Set the live key only in the production environment of the builder. Keep the test key for previews and development. ## What to tell the builder The fastest route is a generated prompt: choose your use case, your stack and your tool, and paste the result into the builder. See the [prompt generator](https://esigncomply.com/product/prompt-generator). The prompt names the environment variables and never contains a key. If you write your own instructions, include these rules. They are the same ones in [/llms.txt](https://esigncomply.com/llms.txt): ```text - Packages that exist: esigncomply (server), @esigncomply/browser (client). Do not invent others. - Read ESIGNCOMPLY_API_KEY only in server code. Never place the API key in client code. - Create every session on the server. Send only client_token to the browser. - Never pre-check an assent control and never submit on the user's behalf. - Pass signer.region from the form or account data. Never infer it from IP. - Read required_steps and required_strings from the session. Do not hard-code steps or legal wording. - Grant access only after the server has confirmed the record with the secret key. - When a session is refused, stop the flow and tell the person. Never fall back to an acceptance with no record. - If you are unsure how to implement a step, stop and ask. ``` ## A checklist the tool can run 1. **The key works and is a test key.** From server code or a terminal with the secret loaded: ```bash curl -s https://esigncomply.com/v1/usage -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" ``` A `200` response means the key is valid. [`invalid_api_key`](https://esigncomply.com/docs/api/errors.md#invalid_api_key) means it was copied wrong or revoked. 2. **The bundle is clean.** Run the `grep` commands above. All three must print `clean`. 3. **The browser holds only a client token.** Check the network panel as described above. 4. **The ceremony is recorded.** Complete it once on `localhost` or the preview. A test record appears in the dashboard with its findings. 5. **The interface passes the checker.** Run `npx esigncomply check --url http://localhost:3000/signup` and fix every finding marked `block`. See the [CLI](https://esigncomply.com/docs/sdk/cli.md). 6. **A forged result is refused.** Call your confirmation function with a made-up record ID. It must not grant access. ## If a key was exposed Assume it is compromised, even if the exposure was brief. 1. Revoke the key in the dashboard, or with `DELETE /v1/api-keys/{id}` using a `full_access` key. 2. Create a new key and store it in the builder's secret setting. 3. Redeploy so the server picks up the new value. 4. Remove the old value from source, chat history you control and commit history where you can. 5. Review recent sessions and records in the dashboard for activity you do not recognize. Esign Comply stores only a prefix and a hash of each key, so a lost key cannot be shown again. Create a new one. --- # The ceremony Source: https://esigncomply.com/docs/concepts/ceremony Markdown: https://esigncomply.com/docs/concepts/ceremony.md Section: Concepts > The session state machine, the ceremony steps and their order, assurance levels, signature methods, failure modes and capture modes. A ceremony is the ordered set of steps one signer completes for one bundle of document versions. You build the interface for each step. The browser SDK reports each step directly to Esign Comply, and the API refuses to seal a record until every step the session requires has been recorded in a valid order. One ceremony is one session (`ses_...`). A completed session produces one record (`rec_...`), which is the unit Esign Comply seals and meters. ## Session states | State | Entered when | Next states | |---|---|---| | `created` | Your server calls `POST /v1/sessions` | `in_progress`, `awaiting_verification`, `expired`, `cancelled` | | `in_progress` | The first ceremony event arrives | `awaiting_verification`, `ready`, `expired`, `cancelled` | | `awaiting_verification` | A code was sent, or verification is the only step left before the signing act | `in_progress`, `ready`, `expired`, `cancelled` | | `ready` | Every required step before the signing act is recorded | `completed`, `expired`, `cancelled` | | `completed` | The signing act is recorded and the record is written durably | Terminal | | `expired` | The session lifetime was reached | Terminal | | `cancelled` | Your server or the signer cancelled, or verification was locked out | Terminal | A session lives for `expires_in` seconds: 1,800 by default, from 60 to 86,400. Calls on an expired session return [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired). Calls on a completed or cancelled session return [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active). Create a new session in both cases. Sessions that expire or are cancelled are not signature events. A completed record then moves through its own seal states, independent of the session: `recorded`, `timestamped`, `anchored`. See [Evidence](https://esigncomply.com/docs/concepts/evidence.md). ## Ceremony steps | Step | Event type | Required when | Tag | |---|---|---|---| | S1 Session start | `session.created` | Always. Written by Esign Comply when your server creates the session. | Asserted | | S2 Client attach | `client.attached` | Always, except `server_only` capture | Observed | | S3 Electronic-records disclosure | `disclosure.presented` | Profiles with `consumer_econsent` and a consumer signer | Observed | | S4 Access demonstration | `access.demonstrated` | Same as S3 | Observed | | S5 Electronic-records consent | `econsent.given` | Same as S3 | Observed | | S6 Document presentation | `document.presented` | Always, once per document version | Observed | | S7 Notice snapshot | `notice.captured` | Always, except EU minimal capture and `server_only` capture | Observed | | S8 Channel or credential verification | `identity.verified` | L2 and L3. Written by Esign Comply when it confirms a code or a passkey. | Observed | | S9 Intent | `intent.captured` | Always | Observed | | S10 Final act | `signature.applied` | Always. Written by `POST /v1/sessions/{id}/complete`. | Observed | | S11 Copy delivery | `copy.delivered` | When a copy is sent | Observed if sent by Esign Comply, asserted otherwise | | S12 Sealing | Record states `recorded`, `timestamped`, `anchored` | Always | Observed | Two event names are older than the product's vocabulary. `identity.verified` records control of an email address, phone number or passkey. It does not establish legal identity. `signature.applied` records the final act. It does not turn an acknowledgment into a signature. Viewing is recorded as measured events only: link opened, time visible, scroll depth. Esign Comply never reports that a signer "read" a document. ## Required steps `required_steps` on the session is the authoritative list for that ceremony. The SDK and your code read it. Neither hard-codes steps. ```json { "required_steps": [ "client.attached", "document.presented:dv_3kT9", "document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied" ] } ``` | Step name | Added when | |---|---| | `client.attached` | Direct capture | | `document.presented:` | Once per document version in the session | | `notice.captured` | Unless the session runs under EU minimal capture or `server_only` | | `identity.verified` | Assurance level L2 or L3 | | `identity.verified:passkey` | Assurance level L3 | | `intent.captured`, `signature.applied` | Always | | `disclosure.presented`, `access.demonstrated`, `econsent.given` | The consumer consent flow applies. See [Consumer e-consent](https://esigncomply.com/docs/guides/consumer-econsent.md). | | `renewal_terms.presented`, `renewal_consent.captured` | An adopted pack rule for a renewing or trial flow | | `electronic_agreement.captured`, `sensitive_capture_consent.captured`, `acknowledgment.captured`, `review.presented` | An adopted pack rule that asks for its own control or step | Only an adopted Block condition can add a step. A record condition in advise never adds one. See [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md). Some event types satisfy a step with a different name: | Event type sent | Step satisfied | |---|---| | `renewal.consent_given` | `renewal_consent.captured` | | `electronic_agreement.given` | `electronic_agreement.captured` | | `sensitive_capture.consent_given` | `sensitive_capture_consent.captured` | | `acknowledgment.given` | `acknowledgment.captured` | `ceremony.remainingSteps()` in the browser, and `remaining_steps` in every event response, tell you what is still outstanding. Keep the action control disabled until only `signature.applied` is left. ## Order Events are append-only and strictly ordered by `sequence`. Each event's hash chains to the one before it. The API checks these prerequisites, counting only steps the session requires: | Step | Must already be recorded | |---|---| | Any step (direct capture) | `client.attached` | | `access.demonstrated` | `disclosure.presented` | | `econsent.given` | `disclosure.presented`, `access.demonstrated` | | `renewal_consent.captured` | `renewal_terms.presented` | | `intent.captured` | `client.attached`, the consumer consent steps, every `document.presented:`, `notice.captured`, `renewal_terms.presented` | | A passkey verification | A confirmed email or phone verification in the same session | An event that arrives too early returns [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) (409) with `missing_steps`. Completing while a required step is absent returns [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) (422), also with `missing_steps`. Other events the browser may send are optional and never required on their own: `review.presented`, `language.selected`, `signer.age_attested`, `billing.confirm`, `withdrawal.submitted`. Statements such as `signer.age_attested` and `billing.confirm` are tagged asserted even though they arrive on the direct channel. ## Assurance levels L1 to L3 are simple electronic signatures or recorded acceptances. The level says how the signer is tied to the act. It does not change what kind of signature the record holds. | Level | Name | How the signer is tied to the act | Plans | |---|---|---|---| | L1 | Recorded | You assert the signer's identity from your own authenticated session. Esign Comply observes the act directly from the signer's device and sends a receipt if an email is supplied. | All | | L2 | Verified | Esign Comply verifies control of an email address or phone number with a one-time code or link inside the ceremony, then sends the receipt to that address. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). | All. The Free plan verifies by email: SMS codes need a paid plan. | | L3 | Bound | L2 plus authentication of a WebAuthn credential over a one-use challenge bound to the frozen pre-signature payload. See [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md). | Unlimited and above | No level establishes legal identity, authority or sole control. A passkey may sync or be recovered. A level your plan does not include returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). ## Signature methods The profile's `method` sets what your interface builds. | Method | API value | Interface you build | Notes | |---|---|---|---| | Button acceptance | `click` | Notice text with links directly beside a clearly labeled button | Records assent or acknowledgment | | Checkbox plus button | `checkbox` | Unchecked checkbox with an explicit statement, then a button | Default. Used for consumer, purchase, trial and renewal contexts ([CR-09](https://esigncomply.com/docs/conformance.md#cr-09)). | | Typed name | `typed` | Empty text field for the full legal name plus a signing button | Default for `nda` and `contract`. Never prefilled. Only the submitted name is stored, never keystrokes. | | Drawn signature | `drawn` | Canvas capturing strokes | Stored as vector points only where drawn capture is switched on. Treated as evidence of intent, not biometric identification. | | Passkey | `passkey` | Platform passkey prompt | Requires L3. Combined with a typed name. | Every checkbox starts unchecked and every typed-name field starts empty ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)). ## Signature level Each record carries `signature_level`, Esign Comply's classification of the act: | Value | When | |---|---| | `simple` | An explicit signing or acceptance act at L1, L2 or L3 | | `not_applicable` | Signing intent is not evidenced: every document is a `privacy_notice` or `policy_ack` and the profile is not a signature profile. A privacy-notice click is recorded as an acknowledgment. | The enumeration also holds `advanced` and `qualified` for partner routes. The base product never assigns them. A profile is a **signature profile** when its method is `typed`, `drawn` or `passkey`, or when a document in the session has type `nda`, `contract` or `order_form`. Otherwise it is an **acceptance profile**. The evidence report is titled "Electronic Signature Evidence Report" or "Electronic Acceptance Evidence Report" accordingly. ## Failure modes What happens when Esign Comply cannot be reached at signing time: | Mode | Behavior | Available for | |---|---|---| | `fail_closed` (default) | The SDK reports failure. Your interface must not treat the agreement as signed. | Every profile | | `fail_open_deferred` | Your server stores the acceptance and submits it later through `POST /v1/records/deferred`. The record is sealed with `capture_mode: "deferred"`, every ceremony field is tagged asserted, and the evidence report says so. | `terms` acceptances at L1 only | A deferred submission names the exact document versions that were shown (not `current`) and the time you say the act occurred. The record's `signed_at` is the time Esign Comply received your report. Your time is kept beside it as `asserted_signed_at`. A profile that is `fail_closed` refuses deferred submissions. On a network failure or a `5xx`, show "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the same session before asking for another act. Never proceed without a record. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). ## Capture modes `capture_mode` on the record says how the events reached Esign Comply. | Mode | Meaning | Tags | |---|---|---| | `direct` | Events came from the signer's browser session over the direct channel, as they occurred | Observed | | `server_only` | Your server sent the events with a secret key, for a session created with `capture_mode: "server_only"`. `client.attached` and `notice.captured` are not required. | Asserted | | `deferred` | You reported the act after it occurred, under `fail_open_deferred` | Asserted | | `imported` | A historical acceptance you supplied. See the note below. | Asserted | > **Planned.** `imported` records come from `POST /v1/records/import`, which is not part of the current API. Only `direct` capture produces the independent browser observations the product is built around. Reports and certificates state the capture mode in plain words. ## EU minimal capture A session runs under minimal capture (`minimal_capture: true`) when the profile sets `capture_mode: "eu_minimal"`, or when an `EU`, `UK` or `CH` pack applies. - `notice.captured` is not a required step. The record points at the registered artifact instead of a live snapshot of the assent region. - Optional presentation fields are dropped from event data before storage: markup, styles, layout, link style, viewport, user agent, time zone, screen and referrer. - IP address and user agent are not stored, and the record has no `network` object. - The warning `signer_region_network_mismatch` is never produced. Refusing optional capture preserves the minimal flow: the ceremony still records the expressly submitted inputs and the necessary session data. ## More than one signer (Planned) > **Planned.** Multi-signer documents with one combined evidence report are not part of the current API. A session has exactly one signer. When two people sign the same document today, create one session per signer over the same document version. Each session resolves its packs for its own signer, and each produces its own record and its own signature event. Your application keeps the link between the records, for example with the same value in `metadata`. ## Purpose `context.purpose` tells the rules what kind of act this is: `account_signup`, `one_time_purchase`, `free_trial`, `auto_renewal`, `contract_signature`, `nda`, `policy_update` or `other`. It selects method checks and, with the applied packs, renewal and payment steps. The list is open. ## Related - [Sessions API](https://esigncomply.com/docs/api/sessions.md) for every endpoint in the ceremony. - [Browser SDK](https://esigncomply.com/docs/sdk/browser.md) for the calls that record each step. - [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md) for what the tags mean. --- # Observed and asserted Source: https://esigncomply.com/docs/concepts/observed-and-asserted Markdown: https://esigncomply.com/docs/concepts/observed-and-asserted.md Section: Concepts > How every field in a record is labeled as observed by Esign Comply, asserted by you or supplied by you later, and what Esign Comply will say about each. Every fact Esign Comply holds carries a label that says where it came from. The labels are the same in the API, the dashboard, the evidence report, the certificate and the verification page. They are never merged, because the value of an independent record depends on a reader being able to tell what the record keeper saw from what it was told. ## The three labels | Label | Meaning | Example | |---|---|---| | `observed` | Seen by Esign Comply directly from the signer's device, or generated by Esign Comply | The server receipt time of each event; the checkbox's initial state as the SDK measured it; the verified email address; the record hash | | `asserted` | Supplied by you. Not verified by Esign Comply. | The signer's name, external ID and state; `context.facts`; `metadata`; every field of a `server_only` or `deferred` record | | `customer_supplied` | Supplied by you after or outside the ceremony as a supplement. Received and sealed by Esign Comply, not verified. | A `notice.sent` report with the reminder email attached | Each event in a record has a `tag` of `observed` or `asserted`. Supplements carry `provenance: "customer_supplied"`. Observed does not mean true in every sense. It means Esign Comply received it on the direct channel and recorded it at the server time shown. A customer that scripts a fake browser can still send events. L2 verification and the signer receipt exist to make that harder to do unnoticed. See [Evidence](https://esigncomply.com/docs/concepts/evidence.md). ## Which fields are which | Category | Fields | Label | |---|---|---| | Parties | Your organization's legal name; the registered domain, verified at seal time | Asserted at signup; observed | | Signer identity | `signer.external_id`, `name`, `email`, `phone`, `class`, `country`, `region` | Asserted | | Signer verification | `signer.verified_email`, `signer.verified_phone`, method, time, attempts; passkey credential ID | Observed | | What the signer entered | `signer.typed_name`, drawn strokes where captured | Observed | | Content | Document title, version label, language, content hash, render hash, render-match result | Observed | | Presentation | Mode, link metrics, link opened, viewport, notice snapshot | Observed where captured live; a registered artifact otherwise | | Disclosures and consent | Disclosure version and hash, access demonstration, consent act, control states | Observed | | Intent | Control type, label text, button text, trusted-event flag, initial control state | Observed | | Time | Esign Comply server time for every event; the external timestamp | Observed | | Time | Client clock time reported by the browser (`client_time`) | Reported by the browser, not verified | | Network and device | IP address, user agent, accept-language, origin, page URL (omitted under EU minimal capture) | Observed | | Jurisdictions | Packs applied, versions, reasons, rules fired | Observed | | Jurisdictions | `signer.region`, `governing_law`, the facts rules read | Asserted | | Context | `context.url`, `context.purpose`, `context.facts`, `context.notes`, `context.extra`, `metadata` | Asserted | | Integrity | Record hash, seal, key ID, timestamp token, ledger sequence, previous-entry hash, checkpoint, inclusion proof | Observed | | Conformance | Rule set version and result per rule | Advisory. Stored beside the record, outside the sealed hash. The underlying measurements are sealed inside `events[]`. | | Later facts | Dispute, consent withdrawal, paper-copy request in the signer view, legal hold | Observed (annotations) | | Later material | Supplements | Customer-supplied | Two details are easy to get wrong: - **Times.** `signed_at` is the server receipt time of the final event. It is not an independently verified act time and it is not the timestamp authority's time. The external timestamp bounds when the record hash existed, not when the person acted. - **Location.** Esign Comply does not choose law from an IP address. The signer's country and state are what you sent. ## How capture mode changes the labels | `capture_mode` | Ceremony events | |---|---| | `direct` | Observed, except statements such as `signer.age_attested` and `billing.confirm`, which are asserted | | `server_only` | Asserted: your server reported them | | `deferred` | Asserted: you reported the act after it occurred | | `imported` (Planned) | Asserted | > **Planned.** `imported` records come from `POST /v1/records/import`, which is not part of the current API. For `deferred` and `imported` records Esign Comply does not say the record was made at or near the time of the act. It says when it received your report. See [The ceremony](https://esigncomply.com/docs/concepts/ceremony.md). ## Three parts, never merged Evidence reports, evidence packages and certificates are laid out in three parts: | Part | Heading | Contains | |---|---|---| | A | Esign Comply's record | Everything Esign Comply observed or checked: events, times, hashes, verification, delivery, integrity, rules applied | | B | Asserted by {customer} at signing | Signer fields, `context.facts`, `context.notes`, `context.extra` and `metadata` | | C | Supplied by {customer} after signing | A list of supplements: type, the time you say the thing happened, the time Esign Comply received it, and the hash | Part C sits under the sentence "Esign Comply received this material at the times shown and did not verify its contents." It is a list only: the content is in the evidence package under `customer_supplied/`. The report generated at sealing has an empty Part C. A report downloaded later lists what has arrived since. Parts A and B do not change. The same separation holds in the API. The record object returns `supplements[]` and `certificates[]` outside the sealed hash, and each supplement has its own seal and ledger entry. See [Supplements](https://esigncomply.com/docs/guides/supplements.md). ## Rule classes Jurisdiction rules mix three different things: what Esign Comply records, what the law requires you to do, and what Esign Comply only suggests. Every rule is split into parts, and each part has exactly one class. The class decides who does the work, who holds the record, and what Esign Comply may say about it later. | Class | Label in the catalogue | Who acts | What Esign Comply holds | What a report or certificate may say | |---|---|---|---|---| | Esign Comply record | `service` | Esign Comply | Its own record, tagged observed | "Esign Comply recorded this." | | Record condition | `record_condition` with level `block` or `warn` | Esign Comply checks its own record. Your interface must satisfy the check. | The check and its result, inside its own record | "Rule checked: met" or "not met" | | Customer obligation | `obligation` | You | Nothing, unless you send a report | Nothing about whether you performed it | | Recommendation | `recommendation` | You, if you choose | Nothing, unless you send a report | Nothing | | Customer report | `report` | You send. Esign Comply receives. | Customer-supplied material: content hash and receipt time | "The customer reported this. Esign Comply received the report at the time shown and did not verify it." | A few consequences: - A record condition exists only for something Esign Comply can observe in the ceremony. Where the law also requires something it cannot observe, that remainder is a separate obligation part. - An obligation or a recommendation never blocks a session, never adds a required step and never produces an API error. Only record conditions do, and only once your profile has adopted them. - An obligation is listed only where a cited source places the duty on a party in your position. Where the law only shifts risk, the part is a recommendation. - Obligation text names the duty holder and the source. Recommendations appear under the words "Esign Comply recommends" and never use the word "must". - The lists are not exhaustive and are not legal advice. You remain responsible for every obligation that applies to you, whether or not Esign Comply listed it. The pack pages group each rule's parts under these headings: "Esign Comply records or checks", "Your obligations", "Recommendations" and "What you can send us". The generated prompt uses the matching four headings. Browse them in the [pack catalogue](https://esigncomply.com/docs/jurisdictions.md). ## What Esign Comply will and will not say | Subject | It will say | It will not say | |---|---|---| | An observed event | That its server received the event at the time shown, with the measurements shown | That the person named is who acted, or that they read the document | | An asserted field | That you supplied it, and when | That it is accurate | | A verified email or phone | That a person controlling that address or number took part in the ceremony | That the person is the named signer in law | | A record condition | Whether the measurable check was met | That the flow is lawful or that an agreement is valid | | Your obligations | Which obligations its rule packs identify for your selections | That you performed any of them | | A supplement | That it received these exact bytes at the time shown | That the content is true, or that a duty was performed | | The seal and timestamp | That the stored record matches the sealed hash, and that the hash existed no later than the timestamp | When the person actually acted | | Conformance findings | Measurable design facts and suggested fixes | That a flow meets any law | Conformance findings are advisory. Pass or fail judgments are not printed on evidence reports or certificates. Record conditions that were in advise appear under "Rules applied" as evaluated and not enforced for that record. ## Notes your team keeps In the dashboard, a team member may mark an obligation or a recommendation "handled", "not applicable" or "open", with a note. These marks are your own working notes. They are logged with user and time, they are not evidence that the obligation was performed, and they never appear on an evidence report, a certificate or the signer's view. ## Related - [Evidence](https://esigncomply.com/docs/concepts/evidence.md) for how records are sealed. - [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md) for how obligations and recommendations reach you. - [Conformance](https://esigncomply.com/docs/conformance.md) for the checks behind record conditions. --- # Evidence Source: https://esigncomply.com/docs/concepts/evidence Markdown: https://esigncomply.com/docs/concepts/evidence.md Section: Concepts > How a record is canonicalized, chained, sealed, timestamped and anchored, and what the receipt, the evidence report and the evidence package contain. An Esign Comply record is meant to be evidence you can check without trusting Esign Comply's servers or your own. This page describes what makes it so: the layers of independence, the sealing pipeline, and the three artifacts you can hold: the receipt, the evidence report and the evidence package. Records are tamper-evident: any change to the stored record after sealing is detectable. That is a statement about integrity and time. It does not establish who acted or when the act actually occurred. ## The independence model | Layer | What it establishes | Who can defeat it | |---|---|---| | Direct browser channel | Esign Comply received a request from the signer's device at a stated time, on the registered domain, carrying the stated ceremony events | A customer that scripts a fake browser. Mitigated by L2 verification and the signer receipt. | | Independent verification (L2, L3) | A person controlling the stated email address, phone number or passkey took part in the ceremony | Someone with access to the signer's mailbox, phone or device | | Signer receipt | The signer was sent a copy and a verification link by a third party. Disputes are recorded. | Non-delivery, which is recorded as a bounce | | Registered document version | The text is fixed and hashed before the ceremony. The record names the hash. | No one after publication: the version is immutable | | Seal | The record has not changed since Esign Comply signed it | Compromise of the sealing key. Mitigated by external timestamps and anchoring. | | External timestamp | The record hash existed no later than the time stated by an outside timestamp authority | Compromise of the authority | | Ledger and public checkpoints | Records cannot be removed, reordered or back-dated without detection, including by Esign Comply staff | Collusion that also rewrites externally published checkpoints | Limits stated on every evidence report and certificate: Esign Comply did not see the signer's screen as a human would, did not verify legal identity, and did not review the agreement's content. ## Sealing pipeline | Step | Action | Timing | |---|---|---| | E1 Canonicalize | Serialize the record with the JSON Canonicalization Scheme (RFC 8785), add a random 256-bit salt, and compute SHA-256 over the salt followed by the canonical bytes | In the completion request | | E2 Chain | Insert a ledger entry containing the record hash and the hash of the previous entry for the same domain. The ledger is append-only. | Same database transaction as the record | | E3 Seal | Sign a receipt (JWS, ES256) over record ID, record hash, signed-at time, domain, ledger sequence and previous-entry hash. The private key stays in a managed key service. | In the completion request | | E4 Timestamp | Request an RFC 3161 timestamp token over the record hash from an external timestamp authority. Two authorities are configured, with automatic failover. | Asynchronous, target under 60 seconds | | E5 Batch | Add ledger entries to a per-region Merkle tree (RFC 6962 construction). Sign a checkpoint: tree size, root hash, previous root, time. Checkpoints chain. | Every 60 seconds | | E6 Anchor | Timestamp checkpoint roots externally and write batch bundles to restricted write-once storage. Publish non-identifying aggregate commitments as public anchors. | Checkpoints every 60 seconds; public anchors hourly | | E7 Prove | Compute and store the inclusion proof for each record against its checkpoint | After E6 | A record is complete evidence at E3. E4 to E7 add independent proof of time and of non-removal. The hash covers every event, every document hash and the profile version. Quota never blocks completion of a session that has been created. If the signing key service cannot be reached, the record is still committed, the response carries `status: "pending_seal"` and `receipt: null`, and the receipt is signed within 60 seconds. ## Record states | `status` | Meaning | Webhook | |---|---|---| | `pending_seal` | Committed. The receipt is not signed yet. | None | | `recorded` | The receipt is signed (E3) | `record.completed` | | `timestamped` | The external timestamp token is attached (E4) | `record.timestamped` | | `anchored` | Included in a signed checkpoint and a public anchor (E5 to E7) | `record.anchored` | | `disputed` | The signer used "This was not me". The seal state underneath is unchanged. | `record.disputed` | | `voided` | Test record purge or erasure completed. Reads return `404`. | None | When your server confirms a record, accept `recorded`, `timestamped` or `anchored`. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). > **Test mode.** Test records run the full pipeline against a separate test ledger and a test signing key. For a test record made on the Free plan no external timestamp authority is contacted: the timestamp step is simulated and is not evidence of time. Reports carry a "TEST" watermark and the statement that no attestation is given. Test records are deleted after 30 days. Live records on the Free plan go through the whole pipeline above, external timestamp included. ## Receipt A receipt is the compact proof you can store in your own database and present later. It is a JWS signed with ES256. Public keys, current and retired, are at `/.well-known/jwks.json`. ```json { "header": { "alg": "ES256", "kid": "esc-us-live-2026-11", "typ": "esc-receipt+jwt" }, "payload": { "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 } } ``` | Claim | Meaning | |---|---| | `iss` | Issuer | | `rid` | Record ID | | `dom` | Registered domain the record is bound to. Test records made without a registered domain use `sandbox:`. | | `hash` | Record hash | | `iat` | Signed-at time: server receipt time of the final event, in seconds | | `lvl` | `signature_level`: `simple` or `not_applicable` | | `asr` | Assurance level: `L1`, `L2` or `L3` | | `seq` | Sequence of the record's entry in the domain ledger | | `prev` | Hash of the previous ledger entry for the domain | | `live` | `true` for live records. A receipt signed by a test key never verifies as live evidence. | The receipt comes back from `ceremony.complete()` in the browser and from `GET /v1/records/{id}/receipt` on your server. Store it in your own acceptances table next to the record ID. Anyone who holds the full receipt can check it with `POST /v1/verify`. See [Verification](https://esigncomply.com/docs/concepts/verification.md). Annotations, supplements and certificates get their own receipts (`typ: "esc-subject-receipt+jwt"`) and their own ledger entries. ## Evidence report The evidence report is the human-readable PDF generated from the sealed record: `GET /v1/records/{id}/report`. It is included for every record on every plan and is never charged per download. Regenerating it yields the same content. It is produced in English. | Section | Content | |---|---| | Header | "Electronic Signature Evidence Report" or "Electronic Acceptance Evidence Report", record ID, verification URL and QR code, live or test mark | | Parties | Organization legal name and registered domain; signer details, each field labeled observed or asserted | | Documents | Title, version label, language, content hash | | Signature or Acceptance | Method, classification, assurance level, exact label and button text. IP address, raw device data and drawn strokes are omitted by default. | | Timeline | Server-received time and browser-reported time for each event, kept distinct. The timestamp token time is never labeled as signing time. | | Presentation | The measured assent region where it was captured, otherwise the registered artifact and its provenance | | Disclosures and consent | Where applicable: disclosure version, access demonstration, consent, withdrawal status | | Delivery | Receipt email time and status | | Integrity | Record hash, sealing key ID, timestamp authority and time, ledger sequence, checkpoint ID | | Later history | Annotations with times | | Rules applied | Packs applied with versions and reasons, the asserted signer region and governing law, the rules fired. Conditions in advise are shown as evaluated, not enforced for this record. | | Limits | "Our signature or seal, if present, authenticates this evidence artifact only. It is not the person's signature, a qualified certificate, or a determination of identity, authority, compliance or enforceability." | | Asserted at signing (Part B) | Facts you supplied with the session | | Customer-supplied material (Part C) | A list of supplements with both times and hashes | What the report never states: - That the agreement is valid or enforceable. It states what was recorded. - That a rule check passed or failed as a judgment. Measurements are printed. Advisory pass or fail results are not. - Anything about your obligations or recommendations, or whether you performed any duty. - That the signer read a document. The word "certificate" is reserved for the on-request Contemporaneous Record Statement. See [Certificates](https://esigncomply.com/docs/guides/certificates.md). A `recording_access` key cannot download reports or packages, so a leaked application key cannot export stored evidence. Use a `full_access` or `read_only` key. Records sealed now are never locked for reports, packages or certificates. A record that was locked under the earlier Starter quota rule returns [`quota_exceeded`](https://esigncomply.com/docs/api/errors.md#quota_exceeded). ## Evidence package The evidence package is a ZIP archive with everything needed to verify the record offline: `GET /v1/records/{id}/evidence`. By default the response is JSON with a signed download `url` that expires in 600 seconds. `?inline=true` returns the archive itself when it is under 4 MB. `?supplements=false` leaves out the customer-supplied folder. | File | Content | |---|---| | `manifest.json` | Package format, record ID, generation time, and the SHA-256 and size of every other file | | `record.json` | The canonical record: exactly the bytes that were hashed | | `seal.json` | Record hash, salt, status, issuer, key ID and the ledger entry | | `receipt.jws` | The signed receipt | | `keys/jwks.json` | Public sealing keys valid at seal time | | `timestamp.tsr`, `timestamp.json` | The RFC 3161 timestamp token and a readable summary, when timestamped | | `validation/tsa-chain.pem`, `validation/policy.json` | Certificates embedded in the token; the validation policy the package was produced under | | `inclusion-proof.json` | Merkle inclusion proof and the signed checkpoint, when checkpointed | | `anchors.json` | Public anchors covering the checkpoint, when anchored | | `documents/` | `manifest.json` and the exact stored bytes of each document version | | `notice/` | The captured notice data and the serialized assent region, when captured. Never execute it. | | `report.pdf` | The evidence report | | `annotations.json` | Later facts with their own seals | | `customer_supplied/` | `manifest.json` and supplement content as received, kept apart from `record.json` | | `rules.json` | Packs, rules fired with each condition's state (`enforce` or `advise`) and result, guidance release, API version | | `VERIFY.md` | Manual verification steps and the verifier command | Run `npx esigncomply-verify rec_Z4m8.zip` to check a package. The format and each check are described in [Verification](https://esigncomply.com/docs/concepts/verification.md). ## What a record pins A sealed record is fixed. It pins the API version, the profile version, the pack versions applied with their reasons, the guidance release, and each record condition's state and result. Nothing published later changes it. Later facts are added beside it, never inside it: | Addition | What it is | In the sealed hash | |---|---|---| | Annotation (`ann_...`) | A later fact Esign Comply observes or enforces: `disputed`, `consent_withdrawn`, `electronic_transactions_refused`, `paper_copy_requested`, `superseded`, `legal_hold`, `erased`, `note` | No. Own ledger entry and receipt. | | Supplement (`sup_...`) | Customer-supplied material | No. Own ledger entry and receipt. | | Certificate (`crt_...`) | An on-request statement about the record | No. Own ledger entry and receipt. | | Conformance results | Advisory findings | No. The measurements behind them are sealed inside `events[]`. | ## Signer receipt and disputes When the signer's email is known and receipts are enabled, Esign Comply sends the signer a receipt from its own domain, with a copy and a verification link. The receipt contains a "This was not me" link. Using it adds a `disputed` annotation, sends `record.disputed` to you, and shows the dispute on the evidence report. Esign Comply does not adjudicate disputes. Bounces are recorded and sent as `record.copy_bounced`. ## Retention in brief - Evidence content is kept for up to 10 years while you are subscribed. That is standard capacity, not a legal term. EU customers choose a documented schedule. - Where a rule records a retention floor on the record (`retention_floor`), content is not deleted before the floor expires. The longest floor among applied packs wins. - Bulk export of all evidence packages is available at any time on every paid plan. After cancellation, records remain exportable for 12 months. - Erasing a signer removes the content and leaves the hash, the seal and the ledger entry. Reads then return `content_available: false`. - Sealing keys are rotated annually. Retired public keys stay published permanently. - The verifier is open source, and exported packages verify offline with the bundled keys. The statutory retention duty usually sits with you. Keep your exported copies where another law requires you to keep a record. --- # Verification Source: https://esigncomply.com/docs/concepts/verification Markdown: https://esigncomply.com/docs/concepts/verification.md Section: Concepts > 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. ```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 ` | 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 ` | Trust anchors for the timestamp authority. Without it the token's certificate chain is reported as skipped, not passed. | | `--evidence ` | 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/` | 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 ``` `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": ["", "..."], "root": "", "checkpoint": "" } ``` 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. --- # Compatibility contract Source: https://esigncomply.com/docs/concepts/compatibility Markdown: https://esigncomply.com/docs/concepts/compatibility.md Section: Concepts > The rules, BC-1 to BC-22 in plain words, that keep a working integration recording while laws change, packs are added and API versions move. Most teams build their integration once, often with an AI coding tool, and may not touch it again for years. The law will change in that time, and you will add and remove states. The contract on this page keeps a working integration recording through all of it. The short version: a guidance update does not break your existing recording integration. You may still need to change your flow to meet a new legal requirement, and you decide when anything that can block takes effect. ## Three version axes | Axis | What it versions | How it moves | Who decides when it applies | |---|---|---|---| | API version | Endpoints, request and response shapes, error codes, webhook payloads | Rarely. Dated versions under `/v1`. | You, by pinning | | SDK version | The server package and browser SDK interfaces | Semantic versions | You, by upgrading | | Guidance release | Packs, rule parts, obligations, recommendations, strings, notices | Often | Esign Comply for content that cannot block. You for anything that can block. | The current API version is `2026-11-21`. Every response carries it in the `Esign-Comply-Version` header. Each API key is pinned to the version that was current when the key was created. Send the header on a request to override the pin for that request: ```bash curl https://esigncomply.com/v1/usage \ -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \ -H "Esign-Comply-Version: 2026-11-21" ``` An unknown version returns `400 invalid_request` with `param: "Esign-Comply-Version"` and the list of supported versions. ## The rules ### API and SDK versions | Rule | In plain words | |---|---| | BC-1 Independence | A guidance release never changes an endpoint, a request or response schema, an authentication rule, the meaning of an error code, a webhook payload shape or an SDK method. An API version never changes which rules apply. | | BC-2 API versions | The path stays `/v1`. Breaking changes ship only under a new dated `Esign-Comply-Version`. A dated version is supported for at least 24 months after its successor is released, with at least 12 months' notice before removal. | | BC-3 Additive changes | These may ship at any time without a new version: new endpoints, new optional request fields, new response fields, new values in any enumeration, new webhook event types, new entries in `warnings[]` and `advisories[]`, new rule IDs, new packs, new supplement types, new fact keys. Ignore fields you do not know and tolerate enumeration values you do not know. SDK types expose enumerations as open strings. | | BC-4 Fixed within a version | The meaning and type of existing fields, which request fields are required, the error code returned for a given condition, default values, the names in `required_steps`, and the format of IDs (opaque strings of at most 64 characters). | | BC-16 Webhooks | An endpoint is pinned to the API version in force when it was created. New event types are sent only to endpoints that subscribe to them or to all events. Handlers ignore event types they do not know. | | BC-17 SDKs | Server and browser SDKs follow semantic versioning. Each major version is supported for 24 months after its successor. The browser SDK is served from a versioned URL and is never changed in place except for a security fix. | | BC-18 Deprecation | A feature to be removed is announced in the changelog and by email, marked with `Deprecation` and `Sunset` response headers, and listed in the dashboard with the keys still using it. | For error handling this means: branch on `error.type` first, and treat an unknown `error.code` as its type. The type list is closed within a version. New codes may appear for new conditions. See [Errors](https://esigncomply.com/docs/api/errors.md). ### Rule changes and adoption | Rule | In plain words | |---|---| | BC-5 Rule changes do not break recording | Each profile has a baseline: the pack versions whose record conditions it has adopted. Only baseline record conditions can refuse to seal, add a required step or require a fact. A record condition that arrives later runs in the `advise` state: it is evaluated, its result is stored and returned in `advisories[]`, and it never returns an error and never adds to `required_steps`. | | BC-6 Adoption | You move pending record conditions to `enforce` by adopting them, in the dashboard or with `POST /v1/profiles/{id}/adopt`. Adoption creates a new profile version. `POST /v1/profiles/{id}/rollback` returns to the previous baseline for 90 days. Esign Comply never adopts on your behalf. | | BC-7 Test mode shows the future | Test mode always evaluates the latest release with every condition enforced, so you see what adoption would require before it reaches live traffic. `POST /v1/jurisdictions/resolve` accepts `baseline: "current"` or `"latest"` for the same comparison. | | BC-8 Changes that can only help apply at once | A relaxed or retired record condition stops blocking for every profile at its `effective_at`. Obligations, recommendations, notices, evidence wording and fixed-string text update for every profile at `effective_at`, because none of them can stop a call. A changed fixed string is served through `required_strings[]`. The presence check for the new text stays in advise until adopted, and the earlier text keeps passing meanwhile. | | BC-9 Adding a state | Enabling a pack on a profile with live traffic needs no code change to keep recording. The pack's obligations, recommendations and notices apply at once. Its record conditions start in advise. State-specific steps appear in `required_steps` only after adoption. | | BC-10 Removing a state | Disabling a pack never causes an error. A session whose signer is in that state, or which names the pack explicitly, proceeds under the remaining packs with the warning `jurisdiction_not_enabled:`, and the record says the pack was not applied. A profile may opt in to strict behavior with `strict_jurisdictions: true`, which restores the `422 jurisdiction_not_enabled` error. | | BC-12 Facts | A rule in advise that lacks a fact adds `fact_missing:` and does not fire. `422 jurisdiction_fact_required` is returned only for an adopted Block condition. A fact key is never renamed. A replaced key keeps working as an alias. | How adoption works in practice is in [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md). ### Tolerant input and stable names | Rule | In plain words | |---|---| | BC-11 Tolerant input | Unknown request fields are ignored and reported as `unknown_field:` in `warnings[]`. Unknown keys in `context.facts` are stored as sent with the warning `fact_unrecognized:`. Unknown supplement types are stored. None of these is an error. Structural errors still return `400`: malformed JSON, a wrong type for a known field, a missing required field. | | BC-13 Stable identifiers | Rule IDs, pack codes, step names, string slots, supplement types and notice IDs are never reused or renumbered. A retired rule stays in the catalogue with `status: "retired"` and its last text, so old records and old prompts still resolve. | | BC-21 Catalogue reads | Read packs, supplement types and fact keys from the catalogue and do not hard-code them. Catalogue responses carry `ETag` and a five-minute cache lifetime, so a guidance release needs no client change. | ### Records and prompts | Rule | In plain words | |---|---| | BC-14 Records are fixed | A sealed record pins the API version, the profile version, the pack versions, the guidance release, and each condition's state (`enforce` or `advise`) and result. Nothing published later changes it. | | BC-15 Prompts | Code built from any prompt Esign Comply has issued keeps working against the API version it was written for. Prompt IDs resolve permanently. Changes are offered as update prompts, never as a required rebuild. Reports sent through the earlier annotation types `notice.sent` and `cancellation.requested` are still accepted and stored as supplements. | ### Exceptions, proof and contracts | Rule | In plain words | |---|---| | BC-19 Exceptions | Esign Comply may act sooner than BC-2 and BC-5 only to fix a security vulnerability, to follow a court or regulator order, or to stop abuse. It tells affected customers directly and records the event in the changelog. | | BC-20 Proof | Request and response fixtures from every released API version and every SDK major version are replayed in continuous integration against each application deployment and each guidance release. A guidance release that changes the HTTP status, error code or response schema of any fixture for an unchanged baseline is not published. | | BC-22 Enterprise | A contract may pin pack versions and a guidance release for an agreed period and set change windows for adoption. | ## What you have to do in each case | Event | Does recording keep working with no code change? | What you receive | What you may choose to do | |---|---|---|---| | A state changes a law that Esign Comply covers | Yes | A notice, an update prompt, and advisories on new sessions if a new record condition is not met | Follow the obligation or recommendation. Adopt the new record condition. | | Esign Comply adds a pack for a new state | Yes | A notice in the public feed and to watchers | Enable the pack | | You enable another state | Yes | The pack's obligations and recommendations at once. Its record conditions in advise. | Apply the update prompt, test, adopt | | You disable a state | Yes | The warning `jurisdiction_not_enabled:` on sessions that would have used it | Nothing, or set strict behavior | | A rule is relaxed or retired | Yes | A notice | Nothing | | A new API version is released | Yes, on the pinned version | A changelog entry | Upgrade when convenient, within the support period | | You send a field, fact or supplement type Esign Comply does not know | Yes | A warning naming it | Nothing | "Recording keeps working" is a statement about the API. It is not a statement that your flow meets a new legal requirement. Read each notice: it says separately what changes in Esign Comply's record, what changes in your obligations, and what Esign Comply recommends. ## Writing a client that stays compatible - Read `required_steps` and `required_strings` from each session. Do not hard-code steps or state rules. - Read the pack catalogue, supplement types and fact keys at run time. - Ignore response fields you do not know. Treat every enumeration as an open string. - Treat unknown entries in `warnings[]` and `advisories[]` as information. Log them. - Branch on `error.type`, then on the codes you know. - In webhook handlers, ignore event types you do not recognize and return `200`. - Do not parse IDs. They are opaque strings of at most 64 characters. - Send an `Idempotency-Key` on every `POST` that creates something, and retry `5xx` responses with the same key. ## Related - [API conventions](https://esigncomply.com/docs/api.md) for versioning headers, idempotency and the error envelope. - [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md) for notices, update prompts, adopt and rollback. - [Jurisdiction packs](https://esigncomply.com/docs/guides/jurisdictions.md) for selection and warnings. --- # Browser SDK Source: https://esigncomply.com/docs/sdk/browser Markdown: https://esigncomply.com/docs/sdk/browser.md Section: SDKs > Every method of @esigncomply/browser, what each one records, and the requirements an integration has to respect. `@esigncomply/browser` is headless. It renders nothing. It observes elements you built, reports ceremony events from the signer's browser straight to the Esign Comply API, and tells your code whether the ceremony can proceed. It authenticates with the short-lived session client token (`esc_ct_...`) that your server gets from `POST /v1/sessions`. It never holds a secret API key. The steps a ceremony needs come from the session, not from this page. Read `ceremony.remainingSteps()` and satisfy what it lists. The model behind the steps is in [The ceremony](https://esigncomply.com/docs/concepts/ceremony.md). ## Install ```bash npm install @esigncomply/browser ``` ```ts import { EsignComply, EsignComplyError } from "@esigncomply/browser"; ``` The package is an ES module with type declarations and no dependencies. It exports `EsignComply` (with `attach` and `version`), the `EsignComplyError` class, the `VERSION` string and the types on this page: `Ceremony`, `AttachOptions`, `Session`, `StepResult`, `Finding`, `CompleteResult`, `Verification`, `VerificationResult`, `AccessSample`, `PresentDocumentOptions`, `ObserveAssentOptions`, `RenewalElements`, `RequiredString`, `CeremonyEventMap` and the rest. A script-tag build is also published at the versioned path `/sdk/v1/esigncomply.js` on `esigncomply.com`. It defines one global, `EsignComply`, with the same `attach` function, `version`, and `EsignComplyError`. ```html ``` ## Attach ### EsignComply.attach ```ts const ceremony = await EsignComply.attach({ clientToken, apiUrl }); ``` | Option | Type | Required | Description | |---|---|---|---| | `clientToken` | string | Yes | The `client_token` of the session your server created. Starts with `esc_ct_`. Kept in memory only. | | `apiUrl` | string | No | Regional API base, for example `https://api.eu.esigncomply.com/v1`. Pass the `api_url` field of the session your server created. Default: `https://esigncomply.com/v1`. | `attach` reads the session ID, the test or live flag and the expiry from the token itself. It then reads the session with `GET /v1/sessions/{id}` and records `client.attached` (tag `observed`). The event carries the SDK version and the page address without query string or fragment. Unless the session uses minimal capture it also carries the viewport size, the browser language and the time zone. It resolves with a `Ceremony` object. It rejects with an `EsignComplyError`: | Code | When | |---|---| | `invalid_request` | `attach` ran outside a browser (during server rendering). Raised in the browser SDK, `status` 0. | | `invalid_api_key` | `clientToken` is not a session client token. Secret keys never go to the browser. Raised in the browser SDK, `status` 0, `param: "clientToken"`. | | `client_token_expired` | The session has expired. Create a new session and attach again. | | `domain_mismatch` | The page origin is outside the registered domain (live) or the test allowlist (test). | Any other API or network error rejects the same way. A failed attach leaves nothing behind: listeners are removed and the token is forgotten. `EsignComply.version` is the SDK version string. `ceremony.session` is the last known session object: `object`, `id`, `status`, `livemode`, `expires_at`, `assurance_level`, `signature_method`, `capture_mode`, `minimal_capture`, `required_steps`, `completed_steps`, `remaining_steps`, `documents`, `required_strings`, `record_id`, `purpose`, `locale` and, when the API returns it, `api_url`. The SDK updates `status`, `completed_steps`, `remaining_steps` and `record_id` on it as steps are recorded. > **EU region.** A client token does not carry the API host. Return `api_url` from your server next to the client token and pass it as `apiUrl`, or the SDK reads the session from the US host. When `apiUrl` is not passed and the session it read names an `api_url`, the SDK uses that base for the calls that follow. ## Documents ### presentDocument ```ts await ceremony.presentDocument({ versionId: "dv_3kT9", mode: "hyperlink", // "hyperlink" | "inline" | "scrollbox" link: document.querySelector("#tos-link"), }); ``` | Option | Type | Description | |---|---|---| | `versionId` | string | A version pinned on this session (`session.documents[].version_id`). | | `mode` | `"hyperlink"`, `"inline"` or `"scrollbox"` | How the document is put in front of the signer. | | `link` | Element | The anchor the signer follows. Required for `hyperlink`. | | `container` | Element | The element that holds the document text. Required for `inline` and `scrollbox`. | | `downloadControl`, `printControl` | Element | Optional. The controls that save or print the exact pinned version. | Records `document.presented` (tag `observed`) and satisfies the step `document.presented:`. Resolves with a `StepResult`. It rejects with `invalid_request` and rule `CR-08` when `versionId` is not a version of this session, or when the element the mode needs (`link` or `container`) is missing. Every report carries the `mode` and the `language`: the `lang` or `hreflang` attribute of the element, or else the language of the registered version. What the event carries depends on the mode: | Mode | Recorded | |---|---| | `hyperlink` | Link text and address, whether the address is on the same site, and whether a download or print control exists. Unless capture is minimal: link visibility, underline, contrast against the surrounding text, font size, the viewport, whether the signer opened the link, and the hash of the page behind a same-origin link. | | `inline` | Whether a download or print control exists. Unless capture is minimal: the hash of the text inside the container (`render_hash`) and the viewport. The text is taken from the element marked `data-esc-document` when the container is or holds one, otherwise from the container. | | `scrollbox` | As `inline`, plus whether the signer scrolled to the end. | For a `hyperlink` on the same origin, the SDK fetches the linked page and hashes the text of the element marked `data-esc-document` (see [Data attributes](#data-attributes)). It prefers the element whose attribute value is the version ID, then the first marked element. If the page does not answer with HTML within 4 seconds, or has no marked element, the link is still recorded and no hash is sent. The API compares that hash, or the inline `render_hash`, with the registered version. The hash covers the element's text content in Unicode NFC with whitespace and zero-width characters removed. In live mode a mismatch on an enforced rule rejects with [`render_mismatch`](https://esigncomply.com/docs/api/errors.md#render_mismatch) ([CR-08](https://esigncomply.com/docs/conformance.md#cr-08)). A presentation can be reported more than once: when the link becomes visible, when the signer opens it (a click, or a middle-button click), or when a scroll box reaches its end. Each report is a new `document.presented` event. Calling `presentDocument` again with the same version, element and mode returns the same promise, so a re-render does not record twice. A call with another element for the same version replaces the earlier presentation. A presentation that failed can be tried again with the same element. The SDK records measured events only: link opened, scroll completed. It never reports that a signer read a document. ## Consumer e-consent steps These three steps apply when the session's `required_steps` contain `disclosure.presented`, `access.demonstrated` and `econsent.given`. The walkthrough is in [Consumer e-consent](https://esigncomply.com/docs/guides/consumer-econsent.md). ### presentDisclosure ```ts await ceremony.presentDisclosure({ container: document.querySelector("#econsent-disclosure") }); ``` Records `disclosure.presented` (tag `observed`): the hash of the disclosure text and the headings found inside the container. Unless capture is minimal, the time the disclosure was on screen is measured, and the event is sent again with that time just before the consent event. Resolves with a `StepResult`. A missing `container` rejects with `invalid_request` and rule `CR-16`. A second call with the same element returns the same promise. ### accessSample ```ts const sample = await ceremony.accessSample(); // { format, instruction, html } ``` Fetches the sample document for the access demonstration from `GET /v1/sessions/{id}/access-sample`. The sample contains a six-digit code. Show `instruction` and render `html` in the page. This call records no event. ### demonstrateAccess ```ts await ceremony.demonstrateAccess({ code: codeField.value }); ``` Records `access.demonstrated` (tag `observed`) when the code matches the one inside the sample. A wrong code rejects with [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). Calling it before the disclosure rejects with [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order). ### giveEConsent ```ts ceremony.giveEConsent({ checkbox: document.querySelector("#econsent") }); ``` Watches the consent checkbox. The promise resolves once the signer has ticked it and `econsent.given` (tag `observed`) is recorded with the control's label text, its state when the page loaded, whether the change came from a trusted user event, and its current state. Call it when the control renders, not from its change handler. If the signer unticks the box, the SDK reports that too and the step counts as outstanding again. The tick is sent only after `disclosure.presented` and `access.demonstrated` are recorded. A box the SDK did not see being ticked (rendered checked, or ticked before the call) is reported with the signing act, inside `complete()`. A missing `checkbox` rejects with `invalid_request` and rule `CR-01`. If the API refuses the event the promise rejects, and a new call for the same control starts over. ## Notice and intent ### observeAssent ```ts ceremony.observeAssent({ region: document.querySelector("#assent"), // notice text, links, checkbox, button checkbox: document.querySelector("#agree"), submit: document.querySelector("#create-account"), }); ``` | Option | Type | Required | Description | |---|---|---|---| | `region` | Element | Yes | The container that holds the notice text, the document links, the assent control and the button. | | `submit` | Element | Yes | The button that performs the signing act. | | `checkbox` | Element | No | An unchecked native checkbox, or an element with `role="checkbox"` and `aria-checked`. | | `typedName` | input or textarea | No | An empty field for the signer's full name. | | `canvas` | canvas | No | Only for a drawn signature. Strokes are collected as vector points. | | `slots` | object | No | Values for the `required_strings` slots the page fills in: literal text, the element that shows it, or named parts of an element list. | The method follows from what you pass: `canvas` gives `drawn`, `typedName` gives `typed`, `checkbox` gives `checkbox`, none of them gives button acceptance (`click`). A missing `region` rejects with `invalid_request` and rule `CR-02`. A missing `submit` rejects with `invalid_request` and rule `CR-03`. It records two steps. **`notice.captured` (tag `observed`), immediately.** The visible text of the region without control values, the checkbox label and its initial state, the submit label, the document links, the number of primary buttons, and slot values. Unless capture is minimal it also carries the serialized markup of the region (up to 100 KB, without scripts or form values), font size, weight and contrast of the notice text, the body font size, whether notice and button fit in one viewport, whether the notice sits above the button, the distance between them, the distance from each document link to the button, and the number of visible primary buttons outside the region. In minimal capture no snapshot is taken unless the session requires the step. **`intent.captured` (tag `observed`), on the signer's action.** | Control | When the event is sent | What it carries | |---|---|---| | Checkbox | When the signer ticks the box. An untick is reported as well. | Label text, button text, initial state, `trusted`, current state. | | Typed name, drawn signature, button only | Once, inside `complete()`. Nothing is sent while the signer types or draws. | Control type, labels, initial state, `trusted`, the typed name, and the strokes when a `canvas` was passed and capture is not minimal. | `trusted` is true only when every change the SDK saw on the control came from a real user event. For button acceptance it is whether the click on the button was a real user event. A box ticked by script is reported as it is, with `trusted: false`, and fails [CR-01](https://esigncomply.com/docs/conformance.md#cr-01). A control that was checked or prefilled when the page loaded is reported with that initial state. The SDK does not correct the page. When a control is rendered checked or prefilled, or was already used when the SDK started watching it, the SDK raises a `CR-01` finding of its own on the `finding` event (`source: "sdk"`) before anyone clicks. The API still judges the rule on the event. The button text is read when the signer clicks the button, before your page changes it to a busy label. Strokes are vector points relative to the canvas, without timing or pressure, up to 4,000 points. An element marked `data-esc-clear` inside the region clears them. The promise resolves with the `StepResult` of the notice, or `null` when no snapshot is taken. Calling `observeAssent` again with the same elements returns the same promise. A call with other elements replaces the earlier watch. The promise is safe to leave unawaited: a failure also reaches the `error` event. ### reviewPresented ```ts await ceremony.reviewPresented({ container: document.querySelector("#review"), correctable: true }); ``` Records `review.presented` (tag `observed`) with the hash of the summary text and whether the signer can correct inputs. `correctable` defaults to true when the container holds an element marked `data-esc-correct`. Used by [CR-13](https://esigncomply.com/docs/conformance.md#cr-13). ## Verification L2 and L3 sessions contain the step `identity.verified`. L3 sessions also contain `identity.verified:passkey`. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md) and [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md). ### verify.start ```ts const v = await ceremony.verify.start({ method: "email_otp" }); // "email_otp" | "email_link" | "sms_otp" | "passkey" ``` Calls `POST /v1/sessions/{id}/verifications`. For the first three methods it asks Esign Comply to send a one-time code or link to the address or number on the session's signer object. The browser cannot change the destination. For `passkey` use [`verify.passkey`](#verify-passkey) instead, which also runs the browser prompt. Resolves with a `Verification`: | Field | Description | |---|---| | `id` | Verification ID, for example `ver_2bQd`. | | `method` | The method started. | | `destination` | Masked destination, for example `d***@example.org`, or `null`. | | `status` | `pending`. | | `expiresAt` | Codes are valid for 10 minutes. | | `attemptsRemaining` | Starts at 5. | | `code` | Test mode only: present when the message was not delivered, so automation can continue. | | `challenge` | Passkey only: the WebAuthn options the API issued. | After `email_link` the signer confirms from the message, outside your page. The SDK then reads the session every 3 seconds, for up to 10 minutes, and emits `stepRecorded` for `identity.verified` once the link was used. ### verify.confirm ```ts const result = await ceremony.verify.confirm({ code: "418205" }); // { id, status: "confirmed" | "failed" | "registered", attemptsRemaining } ``` Confirms the code for the verification started last, with `POST /v1/sessions/{id}/verifications/{ver_id}/confirm`. On `confirmed` the API itself records `identity.verified` (tag `observed`), and the SDK emits `stepRecorded` for it with `sequence: null`. On `failed` show `attemptsRemaining` and let the signer try again. After five wrong attempts the session ends and the call rejects with [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed). `registered` occurs only in the passkey flow. Calling `confirm` before any `start` rejects in the browser with `invalid_request` and rule `CR-17`. ### verify.passkey {#verify-passkey} ```ts const result = await ceremony.verify.passkey(); // { id, status: "confirmed" | "failed" | "registered", attemptsRemaining } ``` Runs the passkey step of an L3 session. It takes no arguments. Call it from a click handler, because browsers show the passkey prompt only in response to a user action. The signer's email or phone must already be verified in the same session. What the call does: 1. It starts a verification with `{ "method": "passkey" }`. The API answers with `phase: "register"` and WebAuthn creation options when the signer has no passkey for this relying party, or with `phase: "authenticate"` and WebAuthn request options when one is on file. 2. It runs the platform prompt: `navigator.credentials.create()` for the register phase, `navigator.credentials.get()` for the authenticate phase. 3. It confirms the verification with the browser's response, sent as `attestation` (register) or `assertion` (authenticate). 4. If the API answers `registered`, the new passkey is on file but the step is not recorded yet. The SDK starts a second verification at once, which is the authenticate phase, and runs steps 2 and 3 again. The signer sees two prompts. | Outcome | Result | |---|---| | The assertion verified | Resolves with `status: "confirmed"`. The API recorded `identity.verified` for the step `identity.verified:passkey`, and the SDK emits `stepRecorded`. | | The API could not verify the response | Resolves with `status: "failed"` and the `attemptsRemaining` of that verification. Call `verify.passkey()` again to retry. | | A second registration in a row | Resolves with `status: "registered"`. The SDK registers at most once per call. Call `verify.passkey()` again. | | No passkey support in the browser, or the prompt was dismissed or did not complete | Rejects in the browser with `verification_failed`, `status` 0 and rule `CR-17`. Offer another method or let the signer try again. | | Email or phone not verified yet in this session | Rejects with `409` [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order). | | Plan without L3 | Rejects with `403` [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable). | When the session's `signature_method` is `passkey` and this call resolved with `confirmed`, `complete()` sends `passkey` as the signature method. The request and response bodies of both phases are in [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md). ## Optional events Call these only when the session's `required_steps` or the generated prompt ask for them. The checkbox methods behave like `giveEConsent`: they watch the control and resolve when the tick is recorded. | Method | Event recorded | Tag | Step satisfied | |---|---|---|---| | `languageSelected(code)` | `language.selected` | observed | none | | `ageAttested({ checkbox })` | `signer.age_attested` | asserted | none | | `renewalTerms({ region, elements })` | `renewal_terms.presented` | observed | `renewal_terms.presented` | | `renewalConsent({ checkbox, region? })` | `renewal.consent_given` | observed | `renewal_consent.captured` | | `electronicAgreement({ checkbox })` | `electronic_agreement.given` | observed | `electronic_agreement.captured` | | `sensitiveCaptureConsent({ checkbox })` | `sensitive_capture.consent_given` | observed | `sensitive_capture_consent.captured` | | `acknowledge({ checkbox })` | `acknowledgment.given` | observed | `acknowledgment.captured` | | `billingConfirm()` | `billing.confirm` | asserted | none | All of them resolve with a `StepResult`. - `languageSelected(code)` takes the language code the signer chose, for example `"de"`, and records it as `language`. - The checkbox methods take `{ checkbox }`, an unchecked native checkbox or an element with `role="checkbox"`. They record the control's label text, its state when the page loaded, whether the change was a trusted user event, and the current state. - `renewalConsent`, `electronicAgreement`, `sensitiveCaptureConsent` and `acknowledge` also record `separate_from_terms`: whether the control is a different element from the terms checkbox passed to `observeAssent`. ### renewalTerms and renewalConsent ```ts await ceremony.renewalTerms({ region: document.querySelector("#renewal-terms"), elements: { renewal_term: "every month", price: "$12.00", cancellation_policy: document.querySelector("#cancel-policy"), cancel_path: "Settings, then Billing, then Cancel plan", }, }); ceremony.renewalConsent({ checkbox: document.querySelector("#renewal-agree") }); ``` `renewalTerms` records the text of the renewal block, the value of each element (`renewal_term`, `price`, `cancellation_policy`, `cancel_path` and the optional `minimum_purchase`, each as literal text or as the element that shows it), and whether the consent control sits in the same container. Unless capture is minimal it also measures the font size, weight and contrast of the block's text, the font size of the surrounding text, whether the block is set off by a border or a background of its own (or marked `data-esc-set-off`), and its distance to the consent control. The consent control is the checkbox passed to `renewalConsent`, or else a checkbox inside the region. A missing `region` rejects with `invalid_request` and rule `CR-10`. `renewalConsent` records the tick of the renewal checkbox and whether that checkbox is separate from the terms checkbox. The tick is sent only after `renewal_terms.presented` is recorded. If the terms were measured against another control, the SDK sends `renewal_terms.presented` once more, measured against this checkbox. See [CR-10](https://esigncomply.com/docs/conformance.md#cr-10), [CR-21](https://esigncomply.com/docs/conformance.md#cr-21) and [CR-23](https://esigncomply.com/docs/conformance.md#cr-23). ### billingConfirm Call `ceremony.billingConfirm()` immediately before your page submits a payment or starts billing. It is used only to order events ([CR-22](https://esigncomply.com/docs/conformance.md#cr-22)). ## Steps and strings ### remainingSteps ```ts submitButton.disabled = ceremony.remainingSteps().some((s) => s !== "signature.applied"); ``` Returns the outstanding steps in ceremony order. The ceremony is ready when only `signature.applied` is left. The list follows the page, not only the API: a checkbox that was unticked or a name field that was emptied counts as outstanding again. Subscribe to `change` to keep a button in sync. ### requiredStrings ```ts for (const s of ceremony.requiredStrings()) { // { slot, block, rule, kind: "verbatim" | "elements", text?, translations?, elements?, statutory?, label, check } } ``` Returns the wording the session's jurisdiction packs ask the page to carry. Render each `verbatim` string unchanged in the slot it names, and fill each `elements` list with your own values. Strings with `check: true` are looked for in the captured assent region ([CR-20](https://esigncomply.com/docs/conformance.md#cr-20)). ## Complete and cancel ### complete ```ts const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status } ``` Sends the signing act. Call it from the real submit handler, after the user's own click. It takes one optional argument, `{ typedName }`, for pages that do not pass a `typedName` element to `observeAssent`. What happens, in order: 1. Events already on their way are sent first, and every watched control reports its final state, in ceremony order. 2. If a step other than `signature.applied` is still outstanding, the SDK reads the session once more, in case a step was recorded outside the page (an emailed link). If steps are still outstanding, the call rejects in the browser with `steps_incomplete`, `missingSteps`, a rule and a `fix`. The signing act is not sent. 3. A typed-name signature without a name rejects in the browser with `steps_incomplete` and `param: "signature.typed_name"`. 4. The SDK calls `POST /v1/sessions/{id}/complete` with the method, the label and button text, the typed name and the client time, under one idempotency key per signing act. 5. A network failure or a 5xx answer retries the same request with the same key, up to two more times. If the answer is still lost, the SDK reads the session and, when a record already exists, resolves with it. The signer is never asked to act twice. The method sent is `passkey` when the session's `signature_method` is `passkey` and `verify.passkey()` resolved with `confirmed` on this ceremony object. Otherwise it is `drawn` when a `canvas` was passed, `typed` when there is a typed name, and else the method `observeAssent` derived (`checkbox` or `click`), or the session's `signature_method` when `observeAssent` was not called. | Field | Description | |---|---| | `recordId` | The record, for example `rec_Z4m8`. | | `receipt` | Signed receipt, or `null` while the seal is pending or when the record was recovered after a lost response. | | `verifyUrl` | Verification page for the record, or `null` when recovered. | | `status` | `recorded` or `pending_seal` as the API answered, or `unknown` when the record was recovered. | A double click gets the same promise. After a completed ceremony, further calls resolve with the same result. On success the SDK stops watching the page, emits `stepRecorded` for `signature.applied` with the findings and advisories the API returned, and sets `session.status` to `completed`. When the API refuses the signing act, the SDK reads the session again so that `remainingSteps()` shows the API's view, and the next try uses a new idempotency key. > **Never.** Do not grant access or show "signed" on this result. It was delivered to the browser. Your server confirms the record with a secret key first: see [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). ### cancel ```ts await ceremony.cancel(); ``` Cancels the session with `POST /v1/sessions/{id}/cancel`, for a decline control. The session moves to `cancelled`, the SDK stops watching the page, and no record is made. Resolves with nothing. ## Events ### on ```ts const off = ceremony.on("finding", (f) => console.log(f.rule, f.message, f.fix)); off(); // unsubscribe ``` | Event | Payload | Fired when | |---|---|---| | `finding` | `Finding` | A conformance finding did not pass: in an event response, behind an error, or with the signing act. Includes findings the SDK raises before the API sees the event (`source: "sdk"`). | | `stepRecorded` | `StepResult` | The API recorded a ceremony step. For `identity.verified` and `signature.applied`, which the API records itself, `sequence` is `null`. | | `expired` | `{ sessionId }` | The token's expiry time passed, or the API answered `client_token_expired`. Create a new session. | | `error` | `EsignComplyError` | Any method failed. The same error also rejects the caller's promise. Each error is emitted once. | | `change` | `{ remainingSteps }` | The list `remainingSteps()` returns has changed: a step was recorded, or a watched control changed. | `on` returns the function that unsubscribes. An exception thrown by a handler is caught and logged. It does not stop the ceremony. ### destroy `ceremony.destroy()` removes every listener and observer and forgets the token. Call it when the component unmounts. Every method that talks to the API rejects with `session_not_active` afterwards, and no further events are emitted. ## Results ```ts interface StepResult { id: string; // evt_91xA type: string; // "document.presented" sequence: number | null; // null for steps the API records itself tag: string; // "observed" | "asserted" versionId?: string; status: "pass" | "warn" | "block"; findings: Finding[]; remainingSteps: string[]; } interface Finding { rule: string; // "CR-01" status: "pass" | "warn" | "block"; state: "enforce" | "advise"; message: string; fix?: string; measurement?: Record; maps_to?: string[]; event_type?: string; version_id?: string; doc_url: string; // https://esigncomply.com/docs/conformance#cr-01 source?: "sdk"; } ``` Findings are advisory. `state: "enforce"` can refuse a live record. `state: "advise"` is measured and stored only. Test mode never blocks. The rules are listed in [Conformance rules](https://esigncomply.com/docs/conformance.md). ## Errors Every method rejects with one type, `EsignComplyError`, so a person or an AI coding tool can read the error and repair the page. | Field | Description | |---|---| | `code` | Stable machine code from the [error reference](https://esigncomply.com/docs/api/errors.md), for example `steps_incomplete`. `network_error` when the API could not be reached. | | `type` | Error type from the API envelope, for example `ceremony_error`. | | `status` | HTTP status. `0` for a refusal made in the browser or a network failure. | | `message` | What happened. `name` is always `EsignComplyError`. | | `rule` | Conformance or pack rule that produced the error, for example `CR-01`. | | `missingSteps` | Steps still outstanding, on `steps_incomplete` and `step_out_of_order`. | | `findings` | The findings behind a `conformance_failed` or `render_mismatch`. | | `fix` | Plain-language repair: the fix of the first finding that has one, or the calls that record the missing steps, or a standard fix for the code. | | `param` | The option or request field at fault. | | `docUrl` | Link to the conformance rule when the rule is a `CR-` rule, otherwise the link the API sent for the code. | | `recordId` | Set when the session already has a record. | | `retryAfter` | Seconds, from `Retry-After`. | | `requestId` | The API request ID. | Errors raised in the browser, before or without an API answer, have `status` 0: | Code | Type | When | |---|---|---| | `invalid_request` | `invalid_request_error` | A required option or element is missing, `attach` ran outside a browser, `confirm` was called before `start`, or Web Crypto is not available on the page. | | `invalid_api_key` | `authentication_error` | `clientToken` is not a session client token. | | `steps_incomplete` | `ceremony_error` | `complete()` was called with steps outstanding, or without the typed name. | | `verification_failed` | `ceremony_error` | `verify.passkey()`: no passkey support, or the prompt was dismissed. | | `client_token_expired` | `authentication_error` | The token's expiry time has passed. | | `session_not_active` | `conflict_error` | The ceremony was destroyed. | | `network_error` | `api_error` | The API could not be reached. | | `internal_error` | `api_error` | An unexpected failure inside the SDK. | An API answer without an error body becomes `not_found` for a `404` and `internal_error` otherwise. ```ts try { const result = await ceremony.complete(); await confirmOnServer(result.recordId); } catch (err) { if (err instanceof EsignComplyError) { if (err.code === "client_token_expired") return restartCeremony(); if (err.code === "network_error" || err.status >= 500) { return showMessage("We could not confirm whether your acceptance was recorded. Please wait while we check."); } showMessage(err.message); // keep the form, do not retry automatically } } ``` On `network_error` do not treat the agreement as signed. Reconcile the same session on your server before asking the signer to act again. ## Data attributes The SDK reads these optional attributes on your own elements. | Attribute | Where | Meaning | |---|---|---| | `data-esc-document` | The element that renders a document version. Optionally set its value to the version ID. | The text that is hashed and compared with `render_hash`. | | `data-esc-download`, `data-esc-print` | Controls on the document page or inside the container. | A control that saves or prints the exact pinned version. | | `data-esc-slot=""` | An element inside the assent region. | The text shown for a `required_strings` slot. | | `data-esc-primary` | A custom element that acts as a primary button. | Counted with submit buttons for [CR-07](https://esigncomply.com/docs/conformance.md#cr-07). | | `data-esc-clear` | A button inside the assent region. | Clears the strokes of a drawn signature. | | `data-esc-correct` | An element inside the review container. | The signer can correct inputs from the review step. | | `data-esc-set-off` | The renewal terms region. | The block is set off from the surrounding text. | ## Requirements that matter to an integrator - **Small and self-contained.** Under 15 KB compressed, no third-party dependencies, no cookies, no local or session storage. The client token lives in memory only. - **Direct channel.** Events go with `fetch` from the signer's browser to the regional API host, one at a time and in the order the page produced them. Each request carries the client token in the `Authorization` header and no cookies. An event that fails on the network or with a 5xx answer is sent again, up to two more times, under the same idempotency key. Never proxy SDK calls through your own server: the record would then show your server, not the signer's device. - **Registered text only.** Inline text and same-origin link targets are hashed and compared with the registered version. Render the version fetched from Esign Comply, unmodified. Do not copy document text into your repository. - **Controls start clear.** Every checkbox starts unchecked and every typed-name field starts empty. The SDK reports a pre-checked or prefilled control as it found it. - **The user acts.** Never call `.click()`, set `.checked` or submit on the user's behalf. Programmatic changes are reported with `trusted: false`. A trusted event shows that a user gesture occurred in the browser. It does not establish who acted. - **No keystrokes, no screenshots.** Only the submitted name is sent, once, with the signing act. Drawn strokes are sent only when a `canvas` is passed and are kept only when drawn capture is switched on for the domain. Apart from two page-level measurements (the body font size and a count of primary buttons outside the region), the SDK reads only the elements you name and the page behind a same-origin document link. - **Minimal capture.** When `session.minimal_capture` is true (EU, UK and CH packs, or a profile set to `eu_minimal`), the SDK sends no markup, styles, layout, link measurements, viewport, browser language, time zone or strokes, does not fetch the page behind a document link, and does not time the disclosure. The steps and method calls stay the same. - **Outstanding steps.** Keep the action control disabled until `remainingSteps()` contains only `signature.applied`. - **Typed errors.** Every rejection carries the rule ID and a fix. - **Test mode is verbose.** With a test session every recorded event, every finding that did not pass and every error is logged to the browser console with the rule ID and a documentation link. - **Browser support.** Current Chrome, Safari, Firefox and Edge, and mobile web views. The page must be served over HTTPS or from `localhost`, because hashing uses Web Crypto. ## Content Security Policy The SDK makes no network calls except `fetch` to the API host and a same-origin read of a linked document page. It uses no `eval` and injects no styles or scripts, so no `unsafe-inline` is needed. ```text Content-Security-Policy: connect-src https://esigncomply.com https://api.eu.esigncomply.com ``` Keep only the host of your region if you prefer. If your policy does not already allow same-origin requests, add `'self'` so the SDK can read the document page behind a link. Without it the link is still recorded, and its target is not compared. ## Server-rendered frameworks Importing the package during server rendering is safe: nothing at module scope touches `window` or `document`. `EsignComply.attach()` itself must run in the browser. Call it inside an effect or an event handler of a client component. In Next.js that means a file marked `"use client"`. See [React hooks](https://esigncomply.com/docs/sdk/react.md) and the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). ## Complete example A signup form with a checkbox and a button, at L1. The server creates the session with the [Node SDK](https://esigncomply.com/docs/sdk/node.md) and returns only the client token, the API URL and the documents. ```html

By checking the box and clicking Create account, you agree to the Terms of Service and acknowledge the Privacy Notice.

``` ```ts import { EsignComply, EsignComplyError } from "@esigncomply/browser"; const form = document.querySelector("#signup")!; const submit = document.querySelector("#create-account")!; const message = document.querySelector("#message")!; // Your own route. It calls esc.sessions.create() with the secret key and returns // { clientToken, apiUrl, documents } to the browser. Nothing else. const res = await fetch("/api/ceremony", { method: "POST" }); if (!res.ok) throw new Error("Unable to create ceremony"); const { clientToken, apiUrl, documents } = await res.json(); const ceremony = await EsignComply.attach({ clientToken, apiUrl }); await ceremony.presentDocument({ versionId: documents[0].version_id, mode: "hyperlink", link: document.querySelector("#tos-link") }); await ceremony.presentDocument({ versionId: documents[1].version_id, mode: "hyperlink", link: document.querySelector("#privacy-link") }); ceremony.observeAssent({ region: document.querySelector("#assent"), checkbox: document.querySelector("#agree"), submit, }); const sync = () => { submit.disabled = ceremony.remainingSteps().some((step) => step !== "signature.applied"); }; ceremony.on("change", sync); ceremony.on("expired", () => { message.textContent = "This page has been open for a while. Reload it to continue."; }); sync(); form.addEventListener("submit", async (event) => { event.preventDefault(); try { const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status } // Your authenticated route confirms the record with the secret key before creating the account. const confirmed = await fetch("/api/signup/finish", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ recordId: result.recordId, email: form.email.value }), }); if (!confirmed.ok) throw new Error("Not confirmed"); location.assign("/welcome"); } catch (err) { // A refusal (4xx, or one made in the browser) carries a message and a fix: keep the form. // Anything else is inconclusive: never proceed without a confirmed record. const refused = err instanceof EsignComplyError && err.code !== "network_error" && err.status < 500; message.textContent = refused ? err.message : "We could not confirm whether your acceptance was recorded. Please wait while we check."; } }); ``` --- # React hooks Source: https://esigncomply.com/docs/sdk/react Markdown: https://esigncomply.com/docs/sdk/react.md Section: SDKs > How to run a ceremony from a React client component, with the @esigncomply/react hooks or with the browser SDK directly. `@esigncomply/react` is a thin layer of hooks over the [browser SDK](https://esigncomply.com/docs/sdk/browser.md). It ships no visual components: you build every element of the signing screen, and the hooks connect those elements to the ceremony. ```bash npm install @esigncomply/react @esigncomply/browser ``` `react` (18 or later) and `@esigncomply/browser` are peer dependencies. The package is an ES module with type declarations. Its built file starts with `"use client"`, so the hooks run in the browser only. ## What the package contains | Export | Kind | Purpose | |---|---|---| | `useCeremony` | Hook | Attaches to one session by its client token and follows it: status, outstanding steps, findings, the last error. | | `useDocument` | Hook | Reports the presentation of one pinned document version for an element you render. | | `EsignComplyError` | Class | The error class of the browser SDK, exported again so `instanceof` works without a second import. | | `CeremonyStatus`, `UseCeremonyOptions`, `UseCeremonyResult`, `UseDocumentOptions`, `UseDocumentResult` | Types | The hook signatures, described below. | | `Ceremony`, `CompleteResult`, `Finding`, `PresentationMode`, `StepResult` | Types | Exported again from `@esigncomply/browser`. | ```ts import { useCeremony, useDocument, EsignComplyError } from "@esigncomply/react"; import type { Ceremony, CeremonyStatus, UseCeremonyResult, UseDocumentResult } from "@esigncomply/react"; ``` Both hooks call the browser SDK. Everything on the [browser SDK](https://esigncomply.com/docs/sdk/browser.md) page applies: the methods of the `ceremony` object, the events each one records, the errors, and the requirements. > **Never.** Do not import `esigncomply` (the server package) or read `ESIGNCOMPLY_API_KEY` in a file marked `"use client"`. The browser receives the session client token (`esc_ct_...`) and nothing else. ## useCeremony ```ts function useCeremony(options: UseCeremonyOptions): UseCeremonyResult; interface UseCeremonyOptions { clientToken: string | null | undefined; apiUrl?: string; } interface UseCeremonyResult { ceremony: Ceremony | null; status: CeremonyStatus; remainingSteps: string[]; findings: Finding[]; error: EsignComplyError | null; canComplete: boolean; } type CeremonyStatus = "idle" | "attaching" | "ready" | "error" | "completed"; ``` | Option | Description | |---|---| | `clientToken` | The session client token from your server. While it is `null`, `undefined` or empty, the hook stays `idle` and attaches nothing. | | `apiUrl` | The `api_url` of the session your server created. Pass it for sessions outside the US region. | The hook calls `EsignComply.attach({ clientToken, apiUrl })` in an effect and returns: | Field | Description | |---|---| | `ceremony` | The attached `Ceremony` from `@esigncomply/browser`, or `null` until the attach has resolved. | | `status` | `idle`: no token yet. `attaching`: the attach is running. `ready`: attached. `error`: the attach failed or the session expired. `completed`: the signing act was recorded. | | `remainingSteps` | The steps still outstanding, from `ceremony.remainingSteps()`. It follows the page: unticking the box puts `intent.captured` back. Empty until the ceremony is ready. | | `findings` | Conformance findings that did not pass, the latest for each step. A new result for a step replaces the earlier findings of that step. Each has `rule`, `status`, `message`, `fix` and `doc_url`. | | `error` | The reason the attach failed, or the last error a ceremony method raised, as an `EsignComplyError` with `code`, `rule` and `fix`. `null` when there is none. After the session expires it is an error with code `client_token_expired`. | | `canComplete` | `true` when `status` is `ready` and `signature.applied` is the only step left. Use it to enable the action control. | How the hook attaches: - **Once per session.** One attachment exists per pair of `clientToken` and `apiUrl`. Every component that calls `useCeremony` with the same pair shares it and gets the same `ceremony` object. - **Strict mode.** In development React runs effects twice. The session is still attached once, and `client.attached` is recorded once. - **Cleanup.** The ceremony is destroyed when the last component that uses the token unmounts. You do not call `ceremony.destroy()` yourself. - **Retry.** A failed attach is forgotten, so a later mount with the same token tries again. - **A method error does not change `status`.** A rejected `presentDocument` or `complete` sets `error` and leaves `status` at `ready`. Only a failed attach or an expired session sets `status` to `error`. ## useDocument ```ts function useDocument( ceremony: Ceremony | null | undefined, options: UseDocumentOptions, ): UseDocumentResult; interface UseDocumentOptions { versionId: string | null | undefined; mode: PresentationMode; // "hyperlink" | "inline" | "scrollbox" } interface UseDocumentResult { ref: (element: T | null) => void; presented: boolean; error: EsignComplyError | null; } ``` | Parameter | Description | |---|---| | `ceremony` | The `ceremony` from `useCeremony`. While it is `null` the hook waits. | | `versionId` | A document version pinned on the session (`documents[].version_id` of the session your server created). While it is empty the hook waits. | | `mode` | `hyperlink`: put `ref` on the link. `inline` or `scrollbox`: put `ref` on the element that holds the document text. | | Field | Description | |---|---| | `ref` | A callback ref. It goes on the link or on the container. | | `presented` | `true` once `document.presented` is recorded for this version. | | `error` | The `EsignComplyError` of a presentation that failed, or `null`. | Once the ceremony, the element and the version ID all exist, the hook calls `ceremony.presentDocument({ versionId, mode, link })` for a hyperlink, or `ceremony.presentDocument({ versionId, mode, container })` for the other two modes. The browser SDK treats the same element and version as one presentation, so a strict-mode rerun sends nothing twice. For a download or print control, mark it with `data-esc-download` or `data-esc-print` inside the container or on the linked document page. Every other step is a method on `ceremony`: `observeAssent`, `verify.start`, `verify.confirm`, `verify.passkey`, `presentDisclosure`, `reviewPresented`, `complete`, `cancel` and the rest. Call them from effects and event handlers. ## Rules for React components - **Client only.** Call the hooks in a file marked `"use client"`. They attach in an effect, never during render. - **Start when the form mounts.** Render the form with the client token already in its props, so the ceremony attaches before the signer acts. Do not attach on submit. - **Refs, not selectors.** Pass DOM elements from refs. Call ceremony methods after the elements are mounted. - **Do not drive the controls.** Every checkbox starts unchecked and every typed-name field starts empty. Leave the checkbox uncontrolled, or control it with state that starts `false`. Never set `checked`, call `.click()` or submit on the user's behalf. The SDK reports the control as it finds it ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)). - **Disable, do not hide.** Keep the action button disabled until `canComplete` is `true`. - **Confirm on the server.** The result of `ceremony.complete()` is delivered to the browser. Grant access only after your server has confirmed the record. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). ## Signup form example The parent server component, or a server action, creates the session with the [Node SDK](https://esigncomply.com/docs/sdk/node.md) and passes four values down: `clientToken`, `apiUrl` and the two pinned version IDs. The form runs an L1 ceremony with a checkbox and a button. `finishSignup` is your server action. It confirms the record with the secret key before it creates the account. ```tsx "use client"; import { useEffect, useRef, useState, type FormEvent } from "react"; import { EsignComplyError, useCeremony, useDocument } from "@esigncomply/react"; import { finishSignup } from "./actions"; // server action: (form: FormData, recordId: string) => Promise type Props = { clientToken: string; apiUrl: string; tosVersionId: string; privacyVersionId: string }; export function SignupForm({ clientToken, apiUrl, tosVersionId, privacyVersionId }: Props) { const { ceremony, status, error, canComplete } = useCeremony({ clientToken, apiUrl }); const tos = useDocument(ceremony, { versionId: tosVersionId, mode: "hyperlink" }); const privacy = useDocument(ceremony, { versionId: privacyVersionId, mode: "hyperlink" }); const assentRef = useRef(null); const checkboxRef = useRef(null); const submitRef = useRef(null); const [message, setMessage] = useState(null); const [pending, setPending] = useState(false); // Observe the assent controls once both documents are presented. // A failure reaches the hook's `error`, so the returned promise needs no handler here. useEffect(() => { if (!ceremony || !tos.presented || !privacy.presented) return; void ceremony.observeAssent({ region: assentRef.current, // notice, links, checkbox, button checkbox: checkboxRef.current, submit: submitRef.current, }); }, [ceremony, tos.presented, privacy.presented]); // The signing act, from the signer's real click. async function onSubmit(event: FormEvent) { event.preventDefault(); if (!ceremony) return; const form = new FormData(event.currentTarget); setPending(true); setMessage(null); try { const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status } await finishSignup(form, result.recordId); } catch (err) { // A refusal (4xx, or one made in the browser) carries a message and a fix: keep the form. // Anything else is inconclusive: never proceed without a confirmed record. const refused = err instanceof EsignComplyError && err.code !== "network_error" && err.status < 500; setMessage(refused ? err.message : "We could not confirm whether your acceptance was recorded. Please wait while we check."); } finally { setPending(false); } } const shown = message ?? (status === "error" ? "We could not start the signing step. Reload the page to try again." : null) ?? tos.error?.message ?? privacy.error?.message ?? error?.message ?? null; return (

By checking the box and clicking Create account, you agree to the{" "} Terms of Service and acknowledge the{" "} Privacy Notice.

{shown ?

{shown}

: null}
); } ``` What the example relies on: - The checkbox is uncontrolled and has no `defaultChecked`. It starts unchecked and only the user changes it. - The notice, both links, the checkbox and the button sit inside the one element passed as `region`. Nothing sits between the notice and the button. - The links point at document pages on your own domain that render the registered version inside `
`. See the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). - `canComplete` turns true when the documents and the notice are recorded and the box is ticked. If the user unticks the box, the button is disabled again. - A rejected call carries a rule ID and a `fix`. In test mode the SDK also logs both to the browser console. During development you can render `findings` from `useCeremony` to see each rule, message and fix on the page. ## Typed-name signatures For an NDA or a contract, pass an empty text field instead of a checkbox. The name leaves the page once, with the signing act. ```tsx const nameRef = useRef(null); useEffect(() => { if (!ceremony || !nda.presented) return; void ceremony.observeAssent({ region: assentRef.current, typedName: nameRef.current, submit: submitRef.current }); }, [ceremony, nda.presented]); // (no defaultValue, no value prop) ``` Here `nda` is the result of `useDocument` for the document being signed. Do not prefill the field from the account profile, and do not render the name in a cursive font as the signature. For email verification before signing, call `ceremony.verify.start()` and `ceremony.verify.confirm()` from your own buttons: see [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). ## Without the hooks The hooks are optional. `@esigncomply/browser` works in a client component on its own: call `EsignComply.attach()` inside `useEffect`, keep the ceremony in state, subscribe to `change` to track `remainingSteps()`, and call `destroy()` in the cleanup. In strict mode guard the async attach with a flag and destroy a ceremony that resolves after cleanup. The methods are on the [browser SDK](https://esigncomply.com/docs/sdk/browser.md) page. ## Server components and server actions Keep three things on the server: the secret key, session creation, and confirmation of the record. A typical split in the Next.js App Router: | Piece | Where | Uses | |---|---|---| | Create the session | Server action or route handler | `esigncomply`, `ESIGNCOMPLY_API_KEY` | | Run the ceremony | Client component | `@esigncomply/react` or `@esigncomply/browser`, the client token | | Confirm the record and grant access | Server action or webhook route | `esigncomply`, `ESIGNCOMPLY_API_KEY` | The full walkthrough, including the Supabase table and the webhook, is in the [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md). --- # Node SDK Source: https://esigncomply.com/docs/sdk/node Markdown: https://esigncomply.com/docs/sdk/node.md Section: SDKs > The esigncomply server package for Node.js and TypeScript, with every method, the endpoint it calls and the data-and-error convention. `esigncomply` is the server SDK. It wraps the REST API for the calls your server makes: registering documents, creating sessions, confirming records, sending supplements, requesting certificates, reading guidance and verifying webhooks. It holds your secret API key, so it runs on the server only. The same package carries the [CLI](https://esigncomply.com/docs/sdk/cli.md). ```bash npm install esigncomply ``` Node.js 20.19 or later. The package is an ES module with type declarations. It depends on `esigncomply-verify` (used by the CLI) and lists `playwright` as an optional peer dependency that only the CLI's `check` and `demo --auto` commands load. ```ts import { EsignComply, verifyWebhookSignature, baseUrlForKey, VERSION } from "esigncomply"; import type { EscError, Result, EsignComplyOptions, RequestOptions, BinaryResponse } from "esigncomply"; ``` `EsignComply` is also the default export. Every request and response type on this page (`SessionCreateParams`, `EscRecord`, `Supplement` and the rest) is exported as a type. ## Create the client Create one client in a server-only module and import it wherever you need it. ```ts // lib/esigncomply.ts import "server-only"; import { EsignComply } from "esigncomply"; export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!); ``` ```ts new EsignComply(apiKey?: string, options?: EsignComplyOptions) ``` - **The key is a secret.** `apiKey` defaults to the `ESIGNCOMPLY_API_KEY` environment variable. Store it as a server environment variable. Never use a `NEXT_PUBLIC_` name, never import this module from a file marked `"use client"`, never print or commit the key. The rules are in [/auth.md](https://esigncomply.com/auth.md). - **The constructor refuses to run in a browser.** If `window` is defined it throws an `Error`. This is the only place the SDK throws. `import "server-only"` makes a Next.js build fail earlier, when a client component imports the module. - **The region comes from the key.** A key starting with `esc_test_us_` or `esc_live_us_` uses `https://esigncomply.com/v1`. A key starting with `esc_test_eu_` or `esc_live_eu_` uses `https://api.eu.esigncomply.com/v1`. `esc.baseUrl` returns the base URL in use. - **Test and live are separate.** A test key reads and writes test objects only. Use the test key in development and preview, and the live key in production. - **A missing key does not throw.** Every call then resolves with the error `missing_api_key`. | Option | Type | Default | Description | |---|---|---|---| | `baseUrl` | string | Host for the key's region | API base URL including `/v1`. The `ESIGNCOMPLY_API_URL` environment variable is used when the option is not set. An empty value counts as not set. A bare origin gets `/v1` appended. | | `apiVersion` | string | The version the key is pinned to | Sent as `Esign-Comply-Version` on every request. | | `fetch` | function | The global `fetch` | A fetch implementation. | | `maxRetries` | number | `2` | Retries after the first attempt. See [Retries and timeouts](#retries-and-timeouts). | | `timeoutMs` | number | `60000` | Timeout for each attempt, in milliseconds. | ```ts const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY, { apiVersion: "2026-11-21", maxRetries: 3, timeoutMs: 20_000 }); ``` Each request carries `Authorization: Bearer `, `X-Esc-Sdk: node/` and `User-Agent: esigncomply-node/`. `VERSION` is the SDK version string. ## Data and error Every method resolves to `{ data, error }` and does not throw or reject. Exactly one of the two is `null`. Check `error` every time. When `error` is set, do not use `data`. ```ts type Result = { data: T; error: null } | { data: null; error: EscError }; ``` ```ts const { data: record, error } = await esc.records.get("rec_Z4m8"); if (error) { console.error(error.code, error.message, error.request_id); return; } console.log(record.status); ``` `error` is the `error` object of the [API error envelope](https://esigncomply.com/docs/api.md), plus two fields the SDK adds (`status` and `retry_after`): | Field | Type | Description | |---|---|---| | `type` | string | One of `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `ceremony_error`, `conformance_error`, `quota_error`, `billing_error`, `rate_limit_error`, `api_error`. | | `code` | string | Stable machine value, for example `domain_mismatch`. Every API code is listed in the [error reference](https://esigncomply.com/docs/api/errors.md). | | `message` | string | What happened, why, and the fix. | | `status` | number | HTTP status. `0` when no response was received or the SDK raised the error itself. Always present. | | `param` | string | The request field that caused the error, when there is exactly one. | | `missing_steps` | string[] | On `steps_incomplete` and `step_out_of_order`. | | `rule` | string | The rule ID behind the error, when there is one. | | `quote` | object | On `certificate_charge_unconfirmed`: what the request would cost. | | `findings` | array | Conformance findings behind the error. | | `doc_url` | string | A link to the code's documentation. | | `request_id` | string | The value of `X-Request-Id`. Quote it to support. | | `retry_after` | number | Seconds, from the `Retry-After` header, when the API sent one. | Any further machine-readable detail the API attached to the envelope is kept on the object as well. Branch on `type` first and treat a `code` you do not know as its `type`. New codes for new conditions can be added without a new API version. Enumerations in the SDK types are open strings (`Open<...>`). Statuses, warning names, event types, supplement types and pack codes can gain new values at any time, so write a default branch. See [Compatibility](https://esigncomply.com/docs/concepts/compatibility.md). ### Errors the SDK raises itself These codes never come from the API. All have `status: 0` unless noted. | Code | Type | When | |---|---|---| | `missing_api_key` | `authentication_error` | No key was passed and `ESIGNCOMPLY_API_KEY` is not set. | | `network_error` | `api_error` | The request failed, timed out or was aborted, no fetch implementation exists, or a response body could not be read (then `status` is the HTTP status). | | `invalid_response` | `api_error` | The API answered `2xx` with a body that is not JSON (`status` is the HTTP status), or registered a file without returning an upload URL. | | `invalid_request` | `invalid_request_error` | The base URL is not a valid URL (`param: "baseUrl"`), or `esc.files.upload` could not read the path or was given no name (`param: "file"` or `"name"`). | | `service_unavailable` | `api_error` | The storage service refused a file upload or an evidence download. `status` is the status storage answered. | | `webhook_signature_missing` | `invalid_request_error` | A delivery lacks `webhook-id`, `webhook-timestamp` or `webhook-signature`. | | `webhook_timestamp_out_of_tolerance` | `invalid_request_error` | The delivery's timestamp is further from now than the tolerance. | | `webhook_signature_invalid` | `invalid_request_error` | No secret was passed, or no signature in the header matches. | | `webhook_payload_invalid` | `invalid_request_error` | The body is not a string or bytes, or the signature is valid but the body is not a JSON object. | When an error response has no JSON envelope (for example from a proxy), the SDK builds the error from the status: `400` and `422` give `invalid_request`, `401` `invalid_api_key`, `402` `quota_exceeded`, `403` `insufficient_permission`, `404` `not_found`, `409` `idempotency_conflict`, `421` `region_mismatch`, `429` `rate_limit_exceeded`, `503` `service_unavailable` and any other `5xx` `internal_error`. ## Request options Methods that create or change something take a last argument `options`: | Option | Description | |---|---| | `idempotencyKey` | Sent as `Idempotency-Key`. The SDK sends it on `POST` requests only. | | `apiVersion` | Overrides `Esign-Comply-Version` for this call. | | `signal` | An `AbortSignal` that cancels the call. | ```ts const { data: session, error } = await esc.sessions.create(body, { idempotencyKey: `signup-${signerId}` }); ``` A repeat with the same key and the same body returns the original response and records nothing twice. The same key with a different body returns [`idempotency_conflict`](https://esigncomply.com/docs/api/errors.md#idempotency_conflict). Build the key from your own stable identifiers, not from a timestamp. The methods with an `options` argument are marked `options?` in the tables below. Read methods, `esc.certificates.quote`, `esc.jurisdictions.resolve`, `esc.domains.verify`, `esc.files.upload` and the `PATCH`, `PUT` and `DELETE` methods take none. ### Retries and timeouts {#retries-and-timeouts} The SDK repeats a call only when repeating it cannot act twice. - A call is repeatable when it is a `GET`, or a `POST` that carries an `idempotencyKey`. - A network failure or a timeout is retried for repeatable calls, unless your own `signal` aborted the call. - A `429` answer is retried for every call. A `5xx` answer is retried for repeatable calls only. - The wait is the `Retry-After` value when the API sent one, otherwise 500 ms doubling per attempt up to 8 seconds, with jitter. If `Retry-After` asks for more than 60 seconds, the SDK returns the error instead of waiting. - At most `maxRetries` retries follow the first attempt (default 2). Each attempt has its own `timeoutMs` (default 60 seconds). A `POST` without an idempotency key is therefore not retried after a network failure or a `5xx`. Pass a key on every call that must not be lost, then retry with the same key yourself if the final answer is still an error. ## Reading the reference tables In each table the first column is the method with its real argument list, the second is the endpoint it calls, and the third is a one-line call. Every call resolves to `{ data, error }`: destructure it and check `error` as in the snippet under the table. `options?` is the [request options](#request-options) object. List methods resolve `data` to `{ object: "list", data, has_more }` and take `limit` (1 to 100, default 20), `after` and `before` where the table shows `params?` or `filters?`. ## Documents | Method | Endpoint | Example | |---|---|---| | `esc.documents.create(body, options?)` | `POST /v1/documents` | `esc.documents.create({ name: "Terms of Service", type: "terms" })` | | `esc.documents.list(params?)` | `GET /v1/documents` | `esc.documents.list({ type: "terms", limit: 50 })` | | `esc.documents.get(id)` | `GET /v1/documents/{id}` | `esc.documents.get("doc_8Hq2")` | | `esc.documents.versions.create(documentId, body, options?)` | `POST /v1/documents/{id}/versions` | `esc.documents.versions.create("doc_8Hq2", version)` | | `esc.documents.versions.list(documentId)` | `GET /v1/documents/{id}/versions` | `esc.documents.versions.list("doc_8Hq2")` | | `esc.documents.versions.get(documentId, versionId)` | `GET /v1/documents/{id}/versions/{version_id}` | `esc.documents.versions.get("doc_8Hq2", "dv_3kT9")` | | `esc.documents.versions.getContent(documentId, versionId, params?)` | `GET /v1/documents/{id}/versions/{version_id}/content` | `esc.documents.versions.getContent("doc_8Hq2", "current", { locale: "en" })` | - `documents.create` body: `name`, `type` (`terms`, `privacy_notice`, `nda`, `contract`, `consent`, `policy_ack`, `custom`), optional `metadata`. `documents.list` filters by `type`. - `versions.create` body: `version_label`, `content`, and optionally `language`, `effective_at`, `material_change`, `summary_of_changes`. `content` is `{ format: "markdown" | "html" | "text", text }` or `{ format: "pdf", data_base64 }`. - `versionId` is a version ID or `"current"`. `getContent` takes `{ locale }` to pick a translation when `"current"` is used. It resolves to the stored `text`, the sanitized `html`, or `data_base64` for a PDF, with `content_hash` and `render_hash`. ```ts const { data: version, error } = await esc.documents.versions.create( "doc_8Hq2", { version_label: "2026-11-21", language: "en", content: { format: "markdown", text: "# Terms of Service\n..." }, material_change: true, summary_of_changes: "Added arbitration clause in section 14.", }, { idempotencyKey: "tos-2026-11-21-en" }, ); if (error) throw new Error(`${error.code}: ${error.message}`); console.log(version.id, version.content_hash); ``` A published version is immutable. Fields and responses are in the [documents API](https://esigncomply.com/docs/api/documents.md). ## Profiles | Method | Endpoint | Example | |---|---|---| | `esc.profiles.create(body, options?)` | `POST /v1/profiles` | `esc.profiles.create({ name: "Signup", jurisdictions: ["US-FED"] })` | | `esc.profiles.list()` | `GET /v1/profiles` | `esc.profiles.list()` | | `esc.profiles.get(id)` | `GET /v1/profiles/{id}` | `esc.profiles.get("prof_signup_4f1a")` | | `esc.profiles.guidance(id)` | `GET /v1/profiles/{id}/guidance` | `esc.profiles.guidance("prof_signup_4f1a")` | | `esc.profiles.adopt(id, body?, options?)` | `POST /v1/profiles/{id}/adopt` | `esc.profiles.adopt("prof_signup_4f1a", { note: "Reviewed update upd_7c1e." })` | | `esc.profiles.rollback(id, options?)` | `POST /v1/profiles/{id}/rollback` | `esc.profiles.rollback("prof_signup_4f1a")` | - `profiles.create` body: `name`, and optionally `jurisdictions`, `jurisdiction_mode`, `on_unknown_region`, `governing_law`, `allow_session_packs`, `strict_jurisdictions`, `pack_versions`, `signer_class`, `document_type`, `purpose`, `method`, `assurance_level`, `failure_mode`, `consumer_econsent`, `capture_mode`, `receipts_enabled`, `signer_certificates_enabled`, `change_note`. - `profiles.guidance` resolves to `{ record_conditions, obligations, recommendations, reports }`: everything that applies to the profile now. - `profiles.adopt` moves every pending record condition from advise to enforce and writes a new profile version. Body: `note` (optional, up to 500 characters). Adoption covers every pending condition: there is no list of rules to pass. It resolves to the profile at its new version, plus `adopted` and `baseline_detail`. `profiles.rollback` returns to the previous baseline, within 90 days of an adoption. - The SDK has no method for updating a profile. Use `esc.request("POST", "/profiles/prof_signup_4f1a", { body })`: see [Any other endpoint](#any-other-endpoint). ```ts const { data: profile, error } = await esc.profiles.create({ name: "Signup", jurisdictions: ["US-FED", "US-CA", "US-NY"], jurisdiction_mode: "auto", on_unknown_region: "strictest", }); if (error) throw new Error(`${error.code}: ${error.message}`); ``` See the [profiles API](https://esigncomply.com/docs/api/profiles.md) and [Guidance](https://esigncomply.com/docs/guides/guidance.md). ## Jurisdictions | Method | Endpoint | Example | |---|---|---| | `esc.jurisdictions.list(params?)` | `GET /v1/jurisdictions` | `esc.jurisdictions.list({ limit: 100 })` | | `esc.jurisdictions.get(code)` | `GET /v1/jurisdictions/{code}` | `esc.jurisdictions.get("US-CA")` | | `esc.jurisdictions.versions(code)` | `GET /v1/jurisdictions/{code}/versions` | `esc.jurisdictions.versions("US-CA")` | | `esc.jurisdictions.resolve(body)` | `POST /v1/jurisdictions/resolve` | `esc.jurisdictions.resolve({ profile: "prof_signup_4f1a", signer: { region: "US-CA" } })` | `resolve` body: `profile`, and optionally `signer`, `jurisdictions` (`mode`, `packs`, `governing_law`), `documents`, `context` and `baseline` (`"current"` or `"latest"`). ```ts // Dry run: which packs, rules, steps and strings would apply. Creates nothing and is not metered. const { data: resolution, error } = await esc.jurisdictions.resolve({ profile: "prof_signup_4f1a", signer: { class: "consumer", country: "US", region: "US-CA" }, documents: [{ document: "doc_8Hq2", version: "current" }], context: { purpose: "account_signup" }, }); if (error) throw new Error(`${error.code}: ${error.message}`); console.log(resolution.applied_jurisdictions, resolution.required_steps); ``` Read the catalogue from the API. Do not hard-code pack codes. See [Jurisdictions](https://esigncomply.com/docs/guides/jurisdictions.md). ## Sessions | Method | Endpoint | Example | |---|---|---| | `esc.sessions.create(body, options?)` | `POST /v1/sessions` | `esc.sessions.create(body, { idempotencyKey })` | | `esc.sessions.get(id)` | `GET /v1/sessions/{id}` | `esc.sessions.get("ses_5nWq")` | | `esc.sessions.cancel(id, options?)` | `POST /v1/sessions/{id}/cancel` | `esc.sessions.cancel("ses_5nWq")` | `sessions.create` body: `profile`, `signer` (`external_id` required; `email`, `name`, `phone`, `class`, `country`, `region`, `locality`, `actor_type`, `operator`, `authority_reference` optional), `documents` (1 to 10 of `{ document, version? }`), and optionally `jurisdictions`, `context` (`url`, `locale`, `purpose`, `facts`, `notes`, `extra`), `metadata`, `expires_in` (60 to 86,400 seconds) and `capture_mode` (`"direct"` or `"server_only"`). ```ts const { data: session, error } = await esc.sessions.create( { profile: "prof_signup_4f1a", signer: { external_id: signerId, email, class: "consumer", country: "US", region: "US-CA" }, documents: [ { document: "doc_8Hq2", version: "current" }, { document: "doc_Pv71", version: "current" }, ], context: { url: `${origin}/signup`, locale: "en-US", purpose: "account_signup" }, }, { idempotencyKey: `signup-${signerId}` }, ); if (error) throw new Error(error.message); // Send only these to the browser. Never the key, never the whole session. return { clientToken: session.client_token, apiUrl: session.api_url, documents: session.documents }; ``` `sessions.create` resolves to the session with `client_token` and `api_url`. `sessions.get` resolves to the session with `completed_steps`, `remaining_steps` and `record_id`, which is set once the ceremony completed. Read `required_steps`, `applied_jurisdictions`, `required_strings` and `warnings` from the response: see the [sessions API](https://esigncomply.com/docs/api/sessions.md). The ceremony steps themselves (events, verifications, completion) are sent by the [browser SDK](https://esigncomply.com/docs/sdk/browser.md) with the client token. The server SDK has no named methods for them. A server that reports the steps of a `server_only` session calls those endpoints through [`esc.request`](#any-other-endpoint), and every event is then tagged `asserted`. ## Records | Method | Endpoint | Example | |---|---|---| | `esc.records.list(filters?)` | `GET /v1/records` | `esc.records.list({ signer_external_id: "user_7c1d" })` | | `esc.records.get(id)` | `GET /v1/records/{id}` | `esc.records.get("rec_Z4m8")` | | `esc.records.report(id)` | `GET /v1/records/{id}/report` | `esc.records.report("rec_Z4m8")` | | `esc.records.evidence(id, options?)` | `GET /v1/records/{id}/evidence` | `esc.records.evidence("rec_Z4m8", { inline: true })` | | `esc.records.receipt(id)` | `GET /v1/records/{id}/receipt` | `esc.records.receipt("rec_Z4m8")` | | `esc.records.annotate(id, body, options?)` | `POST /v1/records/{id}/annotations` | `esc.records.annotate("rec_Z4m8", { type: "legal_hold", data: { matter: "2026-0412" } })` | | `esc.records.certify(id, body?, options?)` | `POST /v1/records/{id}/certificates` | `esc.records.certify("rec_Z4m8", { confirm_charge: true })` | | `esc.records.submitDeferred(body, options?)` | `POST /v1/records/deferred` | `esc.records.submitDeferred(deferred, { idempotencyKey })` | - `list` filters: `signer_external_id`, `email`, `document_id`, `version_id`, `created_after`, `created_before`, `status`, plus the list parameters. - `report` resolves to a `BinaryResponse` with the evidence report PDF: `{ bytes, contentType, filename? }`. - `evidence` options: `inline` and `supplements`. Without `inline` it resolves to a download link: `{ object: "evidence_package", record_id, url, expires_in, size, files, format }`. With `{ inline: true }` it resolves to a `BinaryResponse` with the ZIP archive. When the archive is too large to travel inline, the SDK follows the link and still returns the bytes. `{ supplements: false }` leaves out the customer-supplied folder. This option object is not the request options object. - `receipt` resolves to `{ object: "receipt", record_id, receipt, kid, payload }`. `receipt` is the compact JWS. - `annotate` body: `{ type, data?, note? }` with `type` one of `superseded`, `legal_hold`, `legal_hold_released`, `note`, `paper_copy_requested`. `note` is free text, up to 4,000 characters, stored as `data.note`. The earlier report types `notice.sent` and `cancellation.requested` are still accepted and are stored as supplements. New code sends those to `esc.supplements.create`. - `certify` body: `type`, `wording`, `reference`, `include`, `share`, `confirm_charge`, `reissue_of`, all optional. With `share: { expires_in }` the certificate in the response carries the new link as `share: { id, url, expires_at, opens, last_opened_at }`. `share.url` holds the access secret after `#` and is returned only in this response; `share_url` and `share_expires_at` repeat `share.url` and `share.expires_at`. `seal.ledger` is the certificate's full ledger entry, which the [offline verifier](https://esigncomply.com/docs/sdk/verify.md) recomputes. - `submitDeferred` is for profiles with `failure_mode: "fail_open_deferred"`: a signing act your own system captured while Esign Comply was unreachable. The record says the acceptance was reported, not observed. Body: `profile`, `signer` (`external_id`, and optionally `email`, `name`, `class`, `country`, `region`), `documents` (each `{ document, version }` with an exact version ID, not `"current"`), `signed_at`, `signature` (`method`, and optionally `label_text`, `button_text`), and optionally `context` (`url`, `locale`, `purpose`, `notes`), `reason` and `metadata`. ```ts // Server confirmation: the only place access is granted. const { data: record, error } = await esc.records.get(recordId); const confirmed = !error && ["recorded", "timestamped", "anchored"].includes(record.status) && record.signer.external_id === expectedSignerId && record.livemode === (process.env.VERCEL_ENV === "production"); ``` ```ts import { writeFile } from "node:fs/promises"; const { data: pkg, error } = await esc.records.evidence("rec_Z4m8", { inline: true }); if (error) throw new Error(`${error.code}: ${error.message}`); await writeFile(pkg.filename ?? "rec_Z4m8.zip", pkg.bytes); ``` Compare the record's document versions with the versions your server pinned for that session as well: the full check is in [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). A key with `recording_access` gets the status fields of a record, which is what confirmation needs. Evidence reports and packages need `full_access` or `read_only`. See the [records API](https://esigncomply.com/docs/api/records.md) and the [offline verifier](https://esigncomply.com/docs/sdk/verify.md). ## Certificates | Method | Endpoint | Example | |---|---|---| | `esc.certificates.quote(body)` | `POST /v1/certificates/quote` | `esc.certificates.quote({ type: "contemporaneous_record", record_id: "rec_Z4m8" })` | | `esc.certificates.create(body, options?)` | `POST /v1/certificates` | `esc.certificates.create({ type: "contemporaneous_record_set", filter, confirm_charge: true })` | | `esc.certificates.list(filters?)` | `GET /v1/certificates` | `esc.certificates.list({ record_id: "rec_Z4m8" })` | | `esc.certificates.get(id)` | `GET /v1/certificates/{id}` | `esc.certificates.get("crt_7Hd2")` | | `esc.certificates.pdf(id)` | `GET /v1/certificates/{id}/pdf` | `esc.certificates.pdf("crt_7Hd2")` | | `esc.certificates.share(id, body, options?)` | `POST /v1/certificates/{id}/share` | `esc.certificates.share("crt_7Hd2", { expires_in: 2592000 })` | | `esc.certificates.revokeShare(id)` | `DELETE /v1/certificates/{id}/share` | `esc.certificates.revokeShare("crt_7Hd2")` | - `create` issues one certificate over a set of records. Body: `type` and `filter` (`record_ids`, `signer_external_id`, `document_id`, `version_id`, `created_after`, `created_before`), plus the same optional fields as `records.certify`. It is asynchronous: the answer has `status: "processing"` and the `certificate.issued` webhook follows. - `quote` takes the body of either request, with `record_id` for a single record. It issues nothing and charges nothing. - `list` filters: `record_id`, `type`, `status`, `created_after`, `created_before`. - `pdf` resolves to a `BinaryResponse`. `share` takes `expires_in` in seconds (90 days at most) and resolves to `{ object: "certificate_share", certificate_id, id, share_url, share_expires_at }`. ```ts const request = { type: "contemporaneous_record", wording: "auto", reference: "Matter 2026-0412" }; // 1. Quote. Issues nothing and charges nothing. const quoted = await esc.certificates.quote({ ...request, record_id: "rec_Z4m8" }); if (quoted.error) throw new Error(quoted.error.message); // 2. Show quoted.data.amount to an administrator. Only after they confirm: const { data: certificate, error } = await esc.records.certify("rec_Z4m8", { ...request, confirm_charge: true }); if (error) throw new Error(`${error.code}: ${error.message}`); ``` > **Never.** Do not build a certificate request that can run without a person confirming the charge. Without `confirm_charge: true` a request that would incur a charge returns [`certificate_charge_unconfirmed`](https://esigncomply.com/docs/api/errors.md#certificate_charge_unconfirmed) with a `quote` on the error and issues nothing. See [Certificates](https://esigncomply.com/docs/guides/certificates.md) and the [certificates API](https://esigncomply.com/docs/api/certificates.md). ## Supplements and files | Method | Endpoint | Example | |---|---|---| | `esc.supplements.create(body, options?)` | `POST /v1/supplements` | `esc.supplements.create({ subject: { record: "rec_Z4m8" }, type: "note", text: "Called the customer." })` | | `esc.supplements.list(filters?)` | `GET /v1/supplements` | `esc.supplements.list({ subject: { record: "rec_Z4m8" } })` | | `esc.supplements.get(id)` | `GET /v1/supplements/{id}` | `esc.supplements.get("sup_5Hc1")` | | `esc.supplements.content(id)` | `GET /v1/supplements/{id}/content` | `esc.supplements.content("sup_5Hc1")` | | `esc.supplements.withdraw(id)` | `DELETE /v1/supplements/{id}` | `esc.supplements.withdraw("sup_5Hc1")` | | `esc.supplements.types()` | `GET /v1/supplement-types` | `esc.supplements.types()` | | `esc.files.upload(pathOrBytes, options?)` | `POST /v1/files`, `PUT` to the upload URL, `GET /v1/files/{id}` | `esc.files.upload("./renewal-notice.eml", { contentType: "message/rfc822" })` | | `esc.files.get(id)` | `GET /v1/files/{id}` | `esc.files.get("fil_9Qe2")` | - `supplements.create` body: at least one of `text`, `data` or `files`. Optional: `subject` (exactly one of `record`, `session`, `signer`, `document_version`, `domain`; omit it to attach the supplement to the domain), `type`, `occurred_at`, `rule_ids`, `labels`, `supersedes`. - `supplements.list` filters: `subject`, `type`, `rule_id`, `label`, `received_after`, `received_before`. Pass `subject` as an object with one key, as a bare ID string, or as `"domain"`. The SDK sends the ID. - `supplements.content` resolves to `{ text, data, files }` as stored. `withdraw` marks the supplement withdrawn. It stays listed. - `files.upload` takes a file path or the bytes (`Uint8Array` or `Buffer`). Its second argument is `{ name?, contentType? }`, not the request options object. `name` defaults to the base name of the path and is required for bytes. `contentType` defaults to `application/octet-stream`. ```ts const uploaded = await esc.files.upload("./renewal-notice.eml", { contentType: "message/rfc822" }); if (uploaded.error) console.error("File not uploaded", uploaded.error.code); const { data: supplement, error } = await esc.supplements.create( { subject: { record: "rec_Z4m8" }, type: "notice.sent", occurred_at: "2027-01-04T15:02:11.000Z", rule_ids: ["NY-05"], text: "Annual renewal reminder emailed to the address on the account. Template v7.", data: { channel: "email", template: "renewal-v7" }, files: uploaded.data ? [uploaded.data.id] : [], }, { idempotencyKey: "renewal-notice-user_7c1d-2027-01" }, ); if (error) console.error("Supplement not filed", error.code); // never block the user's action on this ``` `esc.files.upload` performs the upload steps for you. It registers the file with its name, size, content type and SHA-256 hash, sends the bytes with `PUT` to the returned upload URL without the API key, then reads the file back so `status` reflects what the API saw. A file not referenced by a supplement within 7 days is deleted. A supplement is the customer's own statement. Esign Comply seals it with its receipt time and does not verify its contents. See [Supplements](https://esigncomply.com/docs/guides/supplements.md) and the [supplements API](https://esigncomply.com/docs/api/supplements.md). ## Guidance | Method | Endpoint | Example | |---|---|---| | `esc.guidance.notices.list(filters?)` | `GET /v1/guidance/notices` | `esc.guidance.notices.list({ severity: "action_required" })` | | `esc.guidance.notices.get(id)` | `GET /v1/guidance/notices/{id}` | `esc.guidance.notices.get("ntc_2026_0931")` | | `esc.guidance.notices.acknowledge(id, body, options?)` | `POST /v1/guidance/notices/{id}/acknowledge` | `esc.guidance.notices.acknowledge("ntc_2026_0931", { state: "read" })` | | `esc.guidance.releases.list(params?)` | `GET /v1/guidance/releases` | `esc.guidance.releases.list({ limit: 10 })` | | `esc.guidance.releases.get(id)` | `GET /v1/guidance/releases/{id}` | `esc.guidance.releases.get(releaseId)` | | `esc.guidance.updates.get(id)` | `GET /v1/guidance/updates/{id}` | `esc.guidance.updates.get("upd_7c1e")` | - `notices.list` filters: `jurisdiction`, `class`, `severity`, `kind`, `topic`, `since`, `affecting_profile`. - `notices.acknowledge` body: `state` (`read`, `applied` or `not_applicable`) and an optional `note`. - `updates.get` resolves to an object with the update prompt in `markdown`. The SDK accepts the endpoint's JSON form and its Markdown form. ```ts const { data: notices, error } = await esc.guidance.notices.list({ since: "2026-11-21T00:00:00.000Z", severity: "action_required" }); if (error) throw new Error(`${error.code}: ${error.message}`); for (const notice of notices.data) console.log(notice.id, notice.title, notice.what_changes.your_obligations); ``` Reading or acknowledging a notice never changes how your integration records. See [Guidance](https://esigncomply.com/docs/guides/guidance.md) and the [guidance API](https://esigncomply.com/docs/api/guidance.md). ## Signers | Method | Endpoint | Example | |---|---|---| | `esc.signers.records(externalId, params?)` | `GET /v1/signers/{external_id}/records` | `esc.signers.records("user_7c1d", { limit: 50 })` | | `esc.signers.status(externalId)` | `GET /v1/signers/{external_id}/status` | `esc.signers.status("user_7c1d")` | | `esc.signers.withdrawConsent(externalId, body?, options?)` | `POST /v1/signers/{external_id}/consents/withdraw` | `esc.signers.withdrawConsent("user_7c1d", { note: "Requested by phone." })` | | `esc.signers.requestErasure(externalId, body?, options?)` | `POST /v1/signers/{external_id}/erasure-requests` | `esc.signers.requestErasure("user_7c1d", { scope: "erasure" })` | `externalId` is your own identifier for the signer, the value you sent as `signer.external_id`. The SDK percent-encodes it. `status` resolves to `{ object: "signer_status", signer, documents, outstanding }`. Each entry of `documents` has `document_id`, `name`, `type`, `current_version`, `accepted_version`, `outstanding`, `reason` and `summary_of_changes`. The top-level `outstanding` lists the documents that still have to be accepted. `withdrawConsent` body (`ConsentWithdrawParams`): `record_id`, `scope` and `note`, all optional. It resolves to `{ object: "consent_withdrawal", signer, record_id, annotation_id, recorded_at }`. `requestErasure` body (`ErasureRequestParams`): `scope` (`"erasure"`, the default, or `"restriction"`) and `basis`, both optional. It resolves to `{ object: "erasure_request", id, signer, scope, status }` with `status` one of `completed`, `blocked_by_hold` or `rejected`, plus `erased`, `restricted` or `reason` as the outcome requires. See the [signers API](https://esigncomply.com/docs/api/signers.md). ```ts // Gate: is any current document version outstanding for this signer? const { data: status, error } = await esc.signers.status(signerId); if (error) throw new Error(`${error.code}: ${error.message}`); const mustAccept = status.documents.some((d) => d.outstanding); ``` See [Re-acceptance](https://esigncomply.com/docs/guides/reacceptance.md) and the [signers API](https://esigncomply.com/docs/api/signers.md). ## Webhooks | Method | Endpoint | Example | |---|---|---| | `esc.webhooks.verify(rawBody, headers, secret, options?)` | None. Local check. | `esc.webhooks.verify(rawBody, request.headers, secret)` | | `esc.webhooks.create(body, options?)` | `POST /v1/webhooks` | `esc.webhooks.create({ url: "https://example.com/api/esigncomply/webhook", events: ["record.completed"] })` | | `esc.webhooks.list()` | `GET /v1/webhooks` | `esc.webhooks.list()` | | `esc.webhooks.update(id, body)` | `PATCH /v1/webhooks/{id}` | `esc.webhooks.update("wh_6Tn3", { status: "disabled" })` | | `esc.webhooks.delete(id)` | `DELETE /v1/webhooks/{id}` | `esc.webhooks.delete("wh_6Tn3")` | | `esc.webhooks.listDeliveries(params?)` | `GET /v1/webhooks/deliveries` | `esc.webhooks.listDeliveries({ since: "2026-11-21T15:00:00.000Z", include: "payload" })` | - `create` body: `url`, and optionally `events` (omit for all) and `description`. The response carries the signing `secret` (`whsec_...`) once. `update` body: `url`, `events`, `description`, `status` (`"enabled"` or `"disabled"`). - `listDeliveries` takes `since`, `limit`, `include`, `endpoint` and `status`. It resolves to the delivery history with response codes: `id`, `endpoint_id`, `webhook_id` (the event ID, the value of the `webhook-id` header), `type`, `status`, `attempts`, `response_status`, `response_excerpt`, `created_at`, `delivered_at`, `last_attempt_at`. With `since` the list holds deliveries created after that time, oldest first. `include: "payload"` adds each event as `payload`. The CLI's `webhooks listen` command uses it. ### Verify a delivery ```ts esc.webhooks.verify(rawBody: string | Uint8Array, headers: HeadersLike, secret: string, options?: WebhookVerifyOptions): Promise>> ``` `verify` checks the signature and the timestamp of a delivery and resolves to the parsed event: `{ object: "event", id, type, api_version, livemode, created_at, data }`. It makes no network call. ```ts // app/api/esigncomply/webhook/route.ts import { esc } from "@/lib/esigncomply"; export const runtime = "nodejs"; export async function POST(request: Request) { const rawBody = await request.text(); // the raw body, before any JSON parsing const { data: event, error } = await esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!); if (error) return new Response(error.code, { status: 400 }); // Deliveries are at-least-once: handle each event.id once. It equals the webhook-id header. switch (event.type) { case "record.completed": // upsert your acceptance row for event.data.record_id break; default: break; // ignore event types you do not recognize } return new Response(null, { status: 200 }); } ``` - `rawBody` is the body exactly as received, as a string or bytes. A parsed object is refused with `webhook_payload_invalid`, because the signature covers the bytes. - `headers` is a fetch `Headers` object or a plain record such as Node's `req.headers`. The check reads `webhook-id`, `webhook-timestamp` and `webhook-signature`. - `secret` is the endpoint's `whsec_...` value. - `options.toleranceSeconds` (default `300`) is how far the delivery's timestamp may be from now. `options.now` replaces the clock. - The signature is HMAC-SHA256 over `..`. The header may carry several `v1,` signatures while a secret is rotated. One match is enough. The four error codes are listed under [Errors the SDK raises itself](#errors-the-sdk-raises-itself). The exported function `verifyWebhookSignature(rawBody, headers, secret, options?)` is the same check without the promise: it returns the `{ data, error }` result synchronously. ```ts import { verifyWebhookSignature } from "esigncomply"; const { data: event, error } = verifyWebhookSignature(rawBody, req.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!); ``` Event types, payloads and the signature scheme are in [Webhooks](https://esigncomply.com/docs/api/webhooks.md). ## Usage and verification | Method | Endpoint | Example | |---|---|---| | `esc.usage.get()` | `GET /v1/usage` | `esc.usage.get()` | | `esc.verify(receiptOrIdOrHash)` | `POST /v1/verify` | `esc.verify(storedReceipt)` | ```ts // Also the simplest way to check that a key works. const { data: usage, error } = await esc.usage.get(); if (error) throw new Error(`${error.code}: ${error.message}`); // Proof status for a signed receipt you stored. const checked = await esc.verify(storedReceipt); if (checked.error) throw new Error(checked.error.message); console.log(checked.data.valid, checked.data.checks); ``` `esc.verify` takes one string and chooses the request field from its shape: a value with three dot-separated parts is sent as `receipt`, a value starting with `sha256:` (or 64 hexadecimal digits alone) as `record_hash`, and anything else as `record_id`. Anyone holding the full signed receipt may ask. A record ID or a record hash is answered only for a record in the domain and environment of your secret key; for any other record the answer is `valid: false` with `reason: "not_verifiable"`. See the [verification API](https://esigncomply.com/docs/api/verification.md). The result is `{ object: "verification_result", valid, reason?, livemode?, attestation?, status?, checks?, checked_at?, note? }`. `esc.verify` reports whether the record matches its seal. It does not establish who signed or whether any agreement is valid or enforceable. For a check that does not involve Esign Comply's servers, use the [offline verifier](https://esigncomply.com/docs/sdk/verify.md). ## Conformance, prompts, domains and API keys | Method | Endpoint | Example | |---|---|---| | `esc.conformance.run(body?, options?)` | `POST /v1/conformance/runs` | `esc.conformance.run({ session_ids: ["ses_5nWq"] })` | | `esc.conformance.get(id)` | `GET /v1/conformance/runs/{id}` | `esc.conformance.get(runId)` | | `esc.prompts.generate(body?, options?)` | `POST /v1/prompts/generate` | `esc.prompts.generate({ use_case: "signup_terms", jurisdictions: ["US-FED", "US-CA"] })` | | `esc.prompts.list(params?)` | `GET /v1/prompts` | `esc.prompts.list({ limit: 20 })` | | `esc.prompts.get(id)` | `GET /v1/prompts/{id}` | `esc.prompts.get("esc_prompt_8Hq2")` | | `esc.domains.create(body, options?)` | `POST /v1/domains` | `esc.domains.create({ domain: "example.com", region: "us" })` | | `esc.domains.get(id)` | `GET /v1/domains/{id}` | `esc.domains.get("dom_4Kx9")` | | `esc.domains.verify(id)` | `POST /v1/domains/{id}/verify` | `esc.domains.verify("dom_4Kx9")` | | `esc.domains.update(id, body)` | `PATCH /v1/domains/{id}` | `esc.domains.update("dom_4Kx9", { certificate_spend_limit: 5000 })` | | `esc.domains.watchJurisdictions(id, jurisdictions)` | `PUT /v1/domains/{id}/watched-jurisdictions` | `esc.domains.watchJurisdictions("dom_4Kx9", ["US-IL", "FR"])` | | `esc.apiKeys.create(body, options?)` | `POST /v1/api-keys` | `esc.apiKeys.create({ name: "CI", permission: "recording_access", mode: "test" })` | | `esc.apiKeys.list()` | `GET /v1/api-keys` | `esc.apiKeys.list()` | | `esc.apiKeys.delete(id)` | `DELETE /v1/api-keys/{id}` | `esc.apiKeys.delete("key_2bQ1")` | - `conformance.run` body: `session_ids`, `since` (default: the last 24 hours), `url` and `limit` (1 to 500 sessions), all optional. It resolves to a run with `status`, `rules_version`, `summary`, `findings` and `markdown`. Each finding is one rule's result across the sessions of the run: `rule`, `status`, `state`, `counts`, `message`, `measurement`, `fix`, `pages`. Findings are advisory statements about measurable design facts. - `prompts.generate` body (`PromptGenerateParams`): the wizard selections, all optional. `use_case` or `use_cases` (each a use case ID such as `signup_terms`, `checkout`, `free_trial`, `auto_renewal`, `nda` or `contract`, or `{ use_case, assurance_level?, method?, profile?, documents? }`), `company`, `profile`, `signers`, `jurisdictions`, `jurisdiction_mode`, `on_unknown_region`, `governing_law`, `facts`, `consumer_econsent`, `failure_mode`, `stack` (a framework ID or `{ framework, hosting, database, language }`), `tool` and `options` (`receipts`, `confirmation`, `mobile`, `languages`, `certificate_action`, `reports`, `guidance_updates`). It creates or reuses the profiles the prompt names, stores the prompt and resolves to the `prompt` object: `id`, `title`, `markdown`, `content_hash`, `word_count`, `guidance_release`, `jurisdictions`, `pack_versions`, `block_versions`, `profiles`, `documents`, `env`, `files`, `fact_keys`, `selections`, `warnings`, `status`, `regenerated_from`, `created_by`, `created_at`. Each default that was applied is named in `warnings`. It needs a `full_access` key. - `prompts.list` takes the list parameters and resolves to the stored prompts of the domain and environment, newest first, without `markdown`, `files`, `fact_keys` and `selections`. `prompts.get` resolves to one prompt with its text. `status.state` is `current` or `update_available`: whether a block or a pack the prompt was built from has a newer version. - `domains.update` takes a settings object, for example `certificate_spend_limit`. `watchJurisdictions` takes the full list of codes to watch, sends it as `{ jurisdictions }` and resolves to `{ object: "watched_jurisdictions", domain_id, jurisdictions }`: the list as stored, in upper case and without duplicates. - `apiKeys.create` body: `name`, and optionally `permission` (`full_access`, `recording_access`, `read_only`) and `mode` (`test`, `live`). The full key is in the response once, as `key`. ```ts const { data: created, error } = await esc.apiKeys.create({ name: "CI", permission: "recording_access", mode: "test" }); if (error) throw new Error(`${error.code}: ${error.message}`); // Store created.key in your secret manager now. It is not shown again. Never log it. ``` Fields and responses are in the [account API](https://esigncomply.com/docs/api/account.md). ## Any other endpoint {#any-other-endpoint} ```ts esc.request(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, params?: { query?: object; body?: unknown; idempotencyKey?: string; apiVersion?: string; token?: string; signal?: AbortSignal; }): Promise> ``` `esc.request` calls an endpoint this SDK version has no method for. It follows the same contract as every other method: it resolves to `{ data, error }` and does not throw. `path` is relative to the base URL, for example `/profiles/prof_signup_4f1a`. A `POST` without a `body` sends `{}`. `token` authenticates the call with a session client token in place of the API key. ```ts import type { Profile } from "esigncomply"; // Update a profile: writes a new profile version. const { data: updated, error } = await esc.request("POST", "/profiles/prof_signup_4f1a", { body: { jurisdictions: ["US-FED", "US-CA"], change_note: "Added California." }, idempotencyKey: "profile-signup-add-ca", }); if (error) throw new Error(`${error.code}: ${error.message}`); ``` Endpoints without a named method today include updating a profile, updating a document, listing domains, listing conformance runs, sending a test webhook event and the ceremony endpoints of a session (`/sessions/{id}/events`, `/sessions/{id}/complete`). ## Exported helpers | Export | Signature | Purpose | |---|---|---| | `baseUrlForKey` | `(apiKey: string) => string` | The API base URL for a key. The two-letter region in `esc_test__` or `esc_live__` selects the host. Anything else gives the US host. | | `verifyWebhookSignature` | `(rawBody, headers, secret, options?) => Result>` | The synchronous core of `esc.webhooks.verify`. | | `VERSION` | `string` | The SDK version, sent as `X-Esc-Sdk: node/`. | ```ts baseUrlForKey("esc_test_eu_..."); // "https://api.eu.esigncomply.com/v1" ``` ## Other languages (Planned) > **Planned.** Server SDKs for Python, Go, Ruby and PHP, generated from the OpenAPI document, are not available yet. Until then call the REST API directly. The machine-readable description is at [/openapi.json](https://esigncomply.com/openapi.json). --- # CLI Source: https://esigncomply.com/docs/sdk/cli Markdown: https://esigncomply.com/docs/sdk/cli.md Section: SDKs > The esigncomply command-line tool for running a demo ceremony, checking a page against the conformance rules, publishing documents, forwarding test webhooks and verifying evidence. The `esigncomply` CLI ships inside the [Node SDK](https://esigncomply.com/docs/sdk/node.md) package. Run it without installing anything: ```bash npx esigncomply@latest ``` In a project that already depends on `esigncomply`, `npx esigncomply ` uses the installed version. The CLI needs Node.js 20.19 or later. ## Commands | Command | What it does | |---|---| | `demo` | Serves a local signup page, runs a test ceremony and prints the record ID. | | `check` | Runs the conformance check of your page at three window sizes, or a pack resolution dry run. Returns an exit code for CI. | | `documents publish` | Publishes a file as a new version of a document. | | `webhooks listen` | Forwards test webhook deliveries to a server on your machine. | | `verify` | Verifies an evidence package offline. | ```text esigncomply [options] esigncomply --help Options of one command. esigncomply help [command] The same help. esigncomply --version The version. Also -v. esigncomply --help The command list. Also -h. ``` Flags are written `--name value` or `--name=value`. `--` ends the flags. Output is plain text. Colors are used only when the output is a terminal and `NO_COLOR` is not set. ## Before you start `demo`, `check`, `documents publish` and `webhooks listen` authenticate with a secret API key, like the SDK. `verify` needs no key. | Variable | Description | |---|---| | `ESIGNCOMPLY_API_KEY` | Your secret key. `demo`, `check` and `webhooks listen` take test keys (`esc_test_...`) only and refuse a live key. `documents publish` takes a test or a live key. | | `ESIGNCOMPLY_API_URL` | API base URL. Default: the host for the region in the key. Set it only for local development against another API host. | | `ESIGNCOMPLY_WEBHOOK_SECRET` | `webhooks listen` only: the signing secret of your test endpoint (`whsec_...`), used when `--secret` is not given. | ```bash export ESIGNCOMPLY_API_KEY=esc_test_us_... ``` > **Never.** Do not paste a live key into a terminal or a chat that an AI coding tool can read. Every command on this page works with a test key. The rules are in [/auth.md](https://esigncomply.com/auth.md). Test keys work on `localhost`, `127.0.0.1` and the preview hosts listed for your domain, with no domain verification. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md). ## Exit codes Every command follows the same convention. The command sections name what counts as a failure. | Code | Meaning | |---|---| | `0` | The command did what was asked. | | `1` | The command ran and failed: an API call returned an error, a check found a problem, or a verification did not pass. | | `2` | The command could not run: unknown command or option, a missing argument, a missing key, a live key where a test key is required, or a missing tool. | | `130` | `demo` only: stopped with Ctrl+C before a record was made. | A usage error prints the reason and `Run esigncomply --help for usage.` to standard error. An API error prints the message with the error code, the HTTP status and the request ID. Running `esigncomply` with no command prints the command list and exits with `2`. So do `esigncomply documents` and `esigncomply webhooks` without a subcommand, with that command's help. ## demo ```bash npx esigncomply@latest demo ``` ```text esigncomply demo [--port 4310] [--auto] ``` Records a first test signature without writing any code. The command: 1. Creates a document named "Demo Terms of Service", a document named "Demo Privacy Notice" and a profile named "Demo signup" (`US-FED`, method `checkbox`, level `L1`) in test mode. On a later run it reuses the ones it made before. 2. Serves a signup page at `http://localhost:4310/` and waits. 3. When you tick the box and click "Create account", the page runs a real ceremony against the API with a session client token. 4. Confirms the record from the command's own process with the secret key: it must be a test record, with status `recorded`, `timestamped` or `anchored`, for the signer and the document versions the command asked for. 5. Prints the record ID, its status, the verify URL, a link to the record in the dashboard and how the ceremony was captured. | Flag | Description | |---|---| | `--port ` | Port for the local page. Default `4310`. `0` lets the system pick a free port. | | `--auto` | Do not wait for a person. The command drives the page with Playwright when it is installed. Otherwise it reports the ceremony from its own process as a `server_only` session, and says so. | | `--help`, `-h` | Show the usage. | The secret key stays in the command's process. The page receives only the session's client token. The local server listens on `127.0.0.1`, answers only requests addressed to `localhost` or `127.0.0.1`, and refuses cross-origin posts. The page loads the [browser SDK](https://esigncomply.com/docs/sdk/browser.md) from the API host at `/sdk/v1/esigncomply.js`. If that bundle is not available, the page reports the same steps itself with `fetch` and the client token, and the output says which of the two happened. With `--auto` and no Playwright, no browser is involved: the command sends each required step with the secret key, and every step in the record is tagged `asserted` instead of `observed`. See [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md). ```text Record sealed. Record ID rec_Z4m8 Status recorded (test mode: sealed with the test key, no attestation) Verify https://esigncomply.com/verify/rec_Z4m8 Dashboard Captured in the browser, by the browser SDK (direct channel) Confirm it from your own server the same way this command did: const { data: record } = await esc.records.get("rec_Z4m8"); ``` Exit codes: `0` when a record was sealed and confirmed, `1` when an API call or the confirmation failed, `2` for a usage error or a port that is in use, `130` when stopped with Ctrl+C before a record was made. The demo page is a sample. It does not change your project. ## check `check` is the active mode of the [conformance rules](https://esigncomply.com/docs/conformance.md). It has two uses, which can be combined in one run. ```text esigncomply check --url [--region US-CA ...] [--json] ``` | Flag | Description | |---|---| | `--url ` | The page that runs the ceremony, for example `http://localhost:3000/signup`. An `http` or `https` URL. | | `--region ` | Dry-run the pack resolution for a signer in this region, for example `US-CA`. Repeatable. Works without `--url`. | | `--profile ` | Profile for the dry run. Default: the domain's only profile. | | `--purpose ` | `context.purpose` for the dry run, for example `auto_renewal`. | | `--signer-class ` | `consumer` (default), `business` or `employee`, for the dry run. | | `--checkbox ` | The assent checkbox, when the checker cannot find it. | | `--submit ` | The button that performs the signing act. | | `--fill ` | Fill a field before submitting. Repeatable. | | `--callback ` | Your server's confirmation endpoint. The checker posts a forged success to it and expects a refusal. | | `--timeout ` | How long to wait for the ceremony to complete at each size. Default `20`, from 1 to 300. | | `--json` | Print the report as JSON. | | `--help`, `-h` | Show the usage. | Pass `--url`, `--region` or both. With neither the command exits with `2`. `ESIGNCOMPLY_API_KEY` must be a test key for the domain the page uses. ### Check a page ```bash npx esigncomply@latest check --url http://localhost:3000/signup ``` Run the command once per page that hosts a ceremony, for example once for `/signup` and once for `/nda/test`. The command opens the page in headless Chromium and watches the calls the page itself makes to the ceremony endpoints. Your page creates its own sessions, as it does for a real visitor. **Violations.** First, at the phone size, the checker tries things that must be refused: | Attempt | What the checker does | Refused when | |---|---|---| | Submit with the checkbox untouched | Fills the form and clicks the button without ticking the box. | No record is made, or the record is flagged by a blocking finding. | | Completion from another origin | Calls the completion endpoint from its own process with the token the page used, under a foreign `Origin`. | The API answers `403` [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch). | | Programmatic click | Ticks the box and clicks the button from a script. | No record is made, or the record is flagged by a blocking finding. | | Forged success posted to your callback | Only with `--callback`. Posts a JSON body that names a record that does not exist. | Your endpoint answers anything other than `2xx`. | In test mode the API seals a record even when a blocking rule failed, so that the finding can be seen. Live mode refuses that record. The checker therefore counts a violation as refused when the test record carries a blocking finding, and names the rule. A violation is `ACCEPTED` only when a record was made and no rule flagged it. Each attempt is reported as `REFUSED`, `ACCEPTED` or `SKIPPED` with a reason. An attempt is skipped when it cannot be made: no checkbox and button were found, the page made no ceremony call on load, or `--callback` was not given. Two more attempts, "Altered document text" and "Skipped verification step", are listed as `SKIPPED`: this version of the checker does not attempt them. The forged callback checks your server. Your application must grant access only after its own server has confirmed the record: see [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). **Ceremonies.** Then the checker runs the ceremony as a signer would, once at each window size: | Window | Size | |---|---| | Phone | 390 by 844 | | Tablet | 768 by 1024 | | Desktop | 1440 by 900 | At each size it waits for the page to settle, fills the fields named with `--fill`, fills empty visible email, password, phone and text fields with test values, waits for a checkbox the page keeps disabled until it is ready, ticks it with a real pointer click, clicks the button and waits up to `--timeout` seconds for the page to complete the ceremony. Without `--checkbox` and `--submit` it looks for a visible checkbox (`input[type="checkbox"]`, then `[role="checkbox"]`) and a visible button (`button[type="submit"]`, then `input[type="submit"]`, then a button inside a form, then any button). **Findings.** Last, the checker asks the API for one conformance run per window size, over the session it ran at that size (`POST /v1/conformance/runs`), and waits for each result. A rule that fails at one size only is reported for that size. If the run endpoint is not available, it reads the findings from each record and from the API's answers to each ceremony event instead, and the report says so. The headless browser is driven through Playwright, an optional peer dependency of the package. If the command reports that Playwright or its browser is missing, it exits with `2`. Add them to the project: ```bash npm install --save-dev playwright npx playwright install chromium ``` ### Read the report The report is printed in the terminal. With `--json` it is one JSON object. ```text Conformance check of http://localhost:3000/signup Window sizes: 390x844, 768x1024, 1440x900 Violations that must be refused REFUSED Submit with the checkbox untouched No record was made. REFUSED Completion from another origin The API answered 403 domain_mismatch. REFUSED Programmatic click No record was made. SKIPPED Altered document text Not attempted by this version of the checker. SKIPPED Skipped verification step Not attempted by this version of the checker. SKIPPED Forged success posted to your callback Pass --callback to post a forged success to your server and expect a refusal (CC-3). Ceremonies 390x844 record rec_Z4m8 session ses_5nWq, 5 events ... Findings WARN CR-05 390x844 measured: contrast_ratio=2.23 element: #tos-link fix: Summary: 0 block, 1 warn, 14 pass. Findings are advisory statements about measurable design facts. The checker does not state that a flow is lawful or enforceable. ``` Messages, counts and IDs above are sample values. Findings with status `pass` are counted in the summary and not listed. Each listed finding has: | Part | Meaning | |---|---| | Status | `BLOCK` or `WARN`. `(advise)` marks a rule that is measured and stored only. | | Rule | The rule ID, for example `CR-04`. Each ID has a section, for example [CR-04](https://esigncomply.com/docs/conformance.md#cr-04). | | Window | The window size the finding was measured at. | | `measured` | The numbers behind the result, for example a contrast ratio or a pixel distance. | | `element` | The selector of the element that was measured. | | `fix` | A plain-language repair for the page. | | `prompt` | The instruction in your generated prompt that the rule relates to. | The JSON report has these fields: | Field | Content | |---|---| | `url`, `viewports` | The page and the three window sizes. | | `dry_runs` | One `{ region, resolution, error }` per `--region`. | | `attempts` | One `{ id, title, outcome, detail }` per violation attempt. `outcome` is `refused`, `accepted` or `skipped`. The IDs are `untouched_checkbox`, `foreign_origin`, `programmatic_click`, `altered_document`, `skipped_verification` and `forged_callback`. | | `sessions` | The sessions the page ran: `id`, `viewport`, `purpose`, `apiBase`, `events`, `recordId`, `completeStatus`, `completeError`. Client tokens are left out. | | `run_endpoint_available`, `runs` | Whether the conformance run endpoint answered, and one `{ viewport, run }` per window size. Each run's `markdown` field holds its findings as Markdown to paste into a coding tool. | | `findings` | Every finding: `rule`, `status`, `state`, `message`, `measurement`, `selector`, `fix`, `prompt_instruction`, `viewport`, `record_id`, `session_id`, `event_type`. | | `summary` | `{ pass, warn, block }`. | | `problems`, `note` | Notes about the run, and the advisory sentence. | Fix every finding marked `block`. List every finding marked `warn` in your report to the developer. Then run the command again. Findings describe measurable design facts. They are not a statement that a flow is lawful or enforceable. ### Check which rules apply ```bash npx esigncomply@latest check --region US-CA --region US-NY --purpose auto_renewal ``` With `--region` the command runs a dry run of pack resolution for a signer in each region and prints the packs with their versions and reasons, the required steps, the required strings, the number of rules fired, the rule set version, the guidance release, and any advisories and warnings. It creates no session and is not metered. It is the terminal form of `POST /v1/jurisdictions/resolve`: see the [jurisdictions API](https://esigncomply.com/docs/api/jurisdictions.md). The dry run needs a profile. Without `--profile` the command uses the domain's profile. When the domain has several it uses the first one listed and adds a note to the report's `problems`. When it has none the command exits with `2`. The signer's country is taken from the region code: `US-CA` gives `US`. ### Exit codes of check | Code | Meaning | |---|---| | `0` | No blocking finding. | | `1` | A blocking finding, a violation that was not refused, a ceremony that did not complete, or a dry run that failed. | | `2` | The check could not run: bad arguments, no key, a live key, or Playwright or its browser not installed. | ### Use it in CI `check` returns an exit code, so a regression such as a restyled link or a pre-checked box fails the build. Start your application, then run the check against it with a test key stored as a CI secret. ```yaml # .github/workflows/conformance.yml name: conformance on: [pull_request] jobs: check: runs-on: ubuntu-latest env: ESIGNCOMPLY_API_KEY: ${{ secrets.ESIGNCOMPLY_TEST_KEY }} steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - run: npx playwright install chromium - run: npm run build - run: npm run start & - run: npx wait-on http://localhost:3000/signup - run: npx esigncomply check --url http://localhost:3000/signup ``` Test mode never blocks a ceremony on a finding. The check is what turns a finding into a failed build before the page reaches live traffic. ## documents publish ```bash npx esigncomply@latest documents publish ./legal/terms.md --document doc_8Hq2 --label 2026-11-21 --material --summary "Added arbitration clause in section 14." ``` ```text esigncomply documents publish --document --label [options] ``` Publishes a file as a new, immutable version of a registered document, for example from a release script. The API returns the content hash that every record of this version will name. Publish when the text is final. | Flag | Description | |---|---| | `--document ` | The document to add the version to. Required. | | `--label