# Quickstart

> Create a test key, record your first test signature on localhost with curl or the SDK, register your domain, and go live.

Source: https://esigncomply.com/docs/quickstart

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

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

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