Skip to content

Quickstart

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.

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. 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. Every step for agents is in the guide for AI agents.
  • 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:

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:

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

Check that the key works:

export ESIGNCOMPLY_API_KEY=esc_test_us_...
curl https://esigncomply.com/v1/usage \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

The response, abbreviated:

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

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.

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:

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

Now send the ceremony events with the client token. These are the calls the browser SDK makes.

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}'
{
  "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 with missing_steps.

The completion response goes to the browser, so your server must not trust it. Confirm the record with the secret key:

sleep 1
curl -s $ESC/records/$REC -H "$KEY" \
  | jq '{id, status, livemode, signer: .signer.external_id, versions: [.documents[].version_id]}'
{
  "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.

Option C: the SDK

Install the two packages:

npm install esigncomply @esigncomply/browser

Create the server module. The server-only import makes the build fail if a client component ever imports it.

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

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

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

<form id="signup">
  <!-- your fields -->
  <div id="assent">
    <label>
      <input type="checkbox" id="agree" />
      I agree to the Terms of Service and Privacy Notice
    </label>
    <p>
      By checking the box and clicking Create account, you agree to the
      <a id="tos-link" href="/legal/terms">Terms of Service</a> and acknowledge the
      <a id="privacy-link" href="/legal/privacy">Privacy Notice</a>.
    </p>
    <button type="submit" id="create-account">Create account</button>
  </div>
</form>

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:

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

Check the result

Run the conformance check against your page:

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.

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:

curl https://esigncomply.com/v1/domains \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "app.example.com", "region": "us" }'
{
  "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=<token>"
  },
  "api_url": "https://esigncomply.com/v1"
}

Add a TXT record named _esigncomply (for example, _esigncomply.example.com) with value esc-verify=<token>. 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:

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.

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

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

Working with an AI tool? This page is also available as Markdown: /docs/quickstart.md