Skip to content
Use case · consent form

Build a consent form with a recorded signature

You're asking people for consent to something specific: a research interview, a photo release, a recorded call. You build the form in your own UI with your AI coding tool, and Esign Comply records each consent as its own sealed record, separate from any terms the person accepted.

Free plan: 10 live signatures a month and a full test mode. No card required.

Live demo · test mode

Try a consent form

This is a real signing ceremony against the real Esign Comply API in test mode: check the box, click Give consent, and the consent is sealed as a record of its own.

your-app.com · Consent formTEST

This is a working signing screen, the kind your AI tool builds. Run it and watch the record being made on the right.

What Esign Comply records

Each step the signer takes is reported from the browser straight to Esign Comply. Run the demo to see the steps for this flow, then the sealed record.

The demo runs the setup Esign Comply recommends for a consent form: an unchecked checkbox, a named button and level L1. Nothing is emailed and no account is needed.

The prompt · from the generator

The prompt that builds the consent form

The Esign Comply prompt generator produced this for a consent form signed by consumers, on Next.js App Router with Supabase and Vercel, under the U.S. Federal rule pack. Paste it into Cursor, Claude Code, v0, Lovable, Bolt or Replit. Your tool builds the form, the server confirmation, the webhook and the screen that asks again when the form changes.

The generator's use case here is a custom agreement with a document of type consent, which is why the prompt says "custom agreement" and labels the button Agree and continue. Rename the button to fit your form: the notice has to name it exactly. IDs in angle brackets are placeholders the prompt tells your tool to ask for.

Generate it for your own regions and stack
esigncomply-consent-form-prompt.md · 1,741 words
# Esign Comply integration: custom agreement
Prompt esc_prompt_cd41065304ac · blocks 2026.11 · guidance bundled · region US
Jurisdictions: US-FED · mode auto

You are adding legally significant acceptance flows to this Next.js App Router application (TypeScript, Supabase Auth and Postgres, deployed on Vercel). Esign Comply is the independent record keeper. You build every screen. The Esign Comply SDK observes the screens you build and seals the record.

Follow this prompt exactly. If something here 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.

This prompt has four kinds of instruction. Keep them apart:
- "Required for the record": build all of it. Esign Comply checks these.
- "Your obligations": duties the law places on {Company}. Esign Comply does not check them. Build what code can do and list the rest in your report.
- "Recommendations": suggestions. Ask the developer before applying any that changes the product.
- "What you can send us": optional reports {Company} may file with Esign Comply.

## Context
- Packages (the only ones that exist): `esigncomply` (server), `@esigncomply/browser` (client), `@esigncomply/react` (optional hooks).
- API host: https://esigncomply.com/v1
- Environment variables (server only, never NEXT_PUBLIC_): ESIGNCOMPLY_API_KEY, ESIGNCOMPLY_WEBHOOK_SECRET
- Profiles: custom agreement = `<profile ID for custom agreement>`
- Documents: Consent Form = `<document ID for Consent Form>`
- An ID in angle brackets does not exist yet. Ask the developer for it. Do not invent IDs.
- Rule pack versions: 2026-11-21 (all selected packs).
- Server SDK calls return `{ data, error }` and do not throw. Check `error` every time.

## Required for the record
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).
4. Notice wording for custom agreement, verbatim, with links:
   "By checking the box and clicking Agree and continue, you agree to the [Consent Form]." (CR-02, CR-03)
5. Links to documents must be underlined and use a colour that differs from the surrounding text with 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, CR-06).
6. Every checkbox starts unchecked (CR-01).
7. Only one primary button inside the assent container. Any other action sits outside it (CR-07).
8. Serve each document at a stable page on this domain that renders the registered version fetched from Esign Comply, unmodified (CR-08).
9. Treat the browser result as untrusted. Grant access only after the server has confirmed the record with the secret key (step 5 below).
10. Pass an `Idempotency-Key` on session creation.

### 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 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" in the interface before step 5 confirms it.
- Never write or change the text of the Consent Form.

## Your obligations
These are {Company}'s duties under the rule packs selected. Esign Comply lists them and does not perform, monitor, or verify them. The list is not exhaustive.

US-FED · pack 2026-11-21
- Customer: where another law requires {Company} to keep a record, keep an accurate, accessible copy for that period, including after export (US-31); before offering a record in court, give the adverse party reasonable written notice and access to the record and declaration (US-38). Outside this codebase.

## Recommendations
Esign Comply recommends the following. Ask the developer which to apply.

- Give the signer a clear way to decline (US-04).
- Before a material terms update takes effect, notify users in advance and present a blocking screen with an unchecked checkbox (US-18). Step 7 builds the screen; the advance notice email is the developer's choice.
- Keep saving and printing open wherever a signed record is shown (US-29).
- Where minors may sign, consider an age attestation checkbox: `ceremony.ageAttested({ checkbox })` (US-42).

## What you can send us
Optional. Each report is sealed with Esign Comply's receipt time and marked as supplied by {Company}; Esign Comply does not verify it. Every field is optional and any text, JSON, or file is accepted.
Reports never affect recording, and a failed one never blocks the user's action. Suggested `data` per type: `esc.supplements.types()`.

- When the terms-update notice email is sent:
  `esc.supplements.create({ subject: { signer: signerId }, type: "notice.sent", rule_ids: ["US-18"], text, data: { channel: "email", template } })`
- Anything else worth keeping (support ticket, screenshot, policy in force): type `note`, or omit `type`.

Only wire these if the developer says yes.

## Build steps

### 1. Install and configure
`npm install esigncomply @esigncomply/browser`
Create `lib/esigncomply.ts`:
```ts
import "server-only";
import { EsignComply } from "esigncomply";
export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!);
```
Keys go in `.env.local` and the Vercel project settings, never in chat.
Run commands in the integrated terminal. Rules file: `.cursor/rules/esigncomply.mdc`.

### 2. Database (Supabase migration)
```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 unique,
  document_id text not null,
  version_id text not null,
  purpose text not null,
  signed_at timestamptz not null,
  created_at timestamptz not null default now()
);
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.
```
Add `signer_id uuid unique` to the profile table.

### 3. Document pages
Create `app/legal/[slug]/page.tsx` for `consent-form`. Resolve `current` on session creation only. Fetch with `esc.documents.versions.getContent(documentId, versionId)`; render, print and download by the exact version ID returned on the session; the cache key includes that ID. Render inside `<article data-esc-document>` and reject stale versions before the final action. Give users a real opportunity to read the terms.

### 4. Custom agreement ceremony (`/agreements/[slug]`)
Server action `startAgreementCeremony()`:
- `signerId` is the signed-in user's `signer_id`; create and store one with `crypto.randomUUID()` if it is missing. Never accept it from the browser. `attemptId` is a UUID made when the page first renders and reused on retry.
- Call:
```ts
const { data, error } = await esc.sessions.create({
  profile: "<profile ID for custom agreement>",
  signer: { external_id: signerId, email, class: "consumer", country, region },
  documents: [
    { document: "<document ID for Consent Form>", version: "current" },
  ],
  context: { url: `${origin}/agreements/${slug}`, locale, purpose: "other" },
}, { idempotencyKey: `custom-${attemptId}` });
```
- Obtain `country` and applicable jurisdiction from the form/customer configuration; do not guess from IP. `region`: the U.S. state as an ISO code ("US-NY"), if collected.
- Return `data.client_token` and `data.documents` to the client.

Client component `AgreementForm`:
```tsx
"use client";
import { EsignComply } from "@esigncomply/browser";
// after the server action returns clientToken:
const ceremony = await EsignComply.attach({ clientToken });
await ceremony.presentDocument({ versionId: consentFormVersionId, mode: "hyperlink", link: consentFormLinkRef.current });
ceremony.observeAssent({
  region: assentRef.current,    // contains notice, links, checkbox, button
  checkbox: checkboxRef.current,
  submit: submitRef.current,
});
// in the submit handler, from the user's real click:
try {
  const result = await ceremony.complete();           // { recordId, receipt, verifyUrl }
  await finishAgreement(formData, result.recordId);   // server action, step 5
} catch (err) {
  showError(err.message);                             // typed error with rule ID
}
```
Disable the button until `ceremony.remainingSteps()` contains only "signature.applied".
Start the ceremony when the page renders, not on submit.

### 5. Server confirmation (the only place access is granted)
Server action `finishAgreement(formData, recordId)`:
- `const { data: record, error } = await esc.records.get(recordId);`
- Require: no error; `record.status` is "recorded", "timestamped", or "anchored"; `record.signer.external_id` equals the signed-in user's `signer_id`; `record.livemode` equals `process.env.VERCEL_ENV === "production"`; the record lists the exact versions pinned in that session.
- Only then apply the agreement, and insert one `esign_acceptances` row per document using the service-role client.
- If checks are inconclusive, do not apply the agreement. Show: "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the existing session before requesting another act.

### 6. Webhook
`app/api/esigncomply/webhook/route.ts`, Node.js runtime. Read the raw body, then `esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!)`.
Reject on failure with 400. Handle idempotently by `webhook-id`:
- `record.completed`: upsert `esign_acceptances` (covers a browser that closed early).
- `record.disputed`: flag the row and notify the admin email.
- `signer.reacceptance_required`: no action; the gate in step 7 handles it.
- Ignore event types you do not recognise and return 200.
Return 200 within 5 seconds.

### 7. Gate and re-acceptance
In the authenticated layout, call `esc.signers.status(signerId)` (cache 5 minutes per user). If any required document is outstanding, redirect to `/accept-updates`. That page shows the list of updated documents with links, the summary of changes returned by the API, an unchecked checkbox labelled "I agree to the updated [document titles]", and a button labelled "Accept and continue". It runs the same ceremony with `purpose: "policy_update"`. Offer "Log out" as the alternative. Do not offer "Remind me later".

### 8. Errors
- `ceremony.complete()` rejected with a rule ID: show the message, keep the form, do not retry automatically.
- Network failure or 5xx: show "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the same session and idempotency key before requesting another act. Never proceed without a record.
- `client_token_expired`: create a new session and re-attach.

## 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/agreements/test`. Fix every finding marked "block", re-running until none is left. List every finding marked "warn" in your report.
3. Confirm by test that submitting with the box unchecked does nothing, and that calling `finishAgreement` with a made-up record ID does not apply the agreement.
4. Report: files created or changed, anything in this prompt you did not implement and why, the conformance summary, each item under "Your obligations" with "built", "partly built", or "needs a process outside this codebase", and each recommendation with the developer's decision.

5 required steps

The five steps a recorded consent needs

A session created with the recommended consent profile returns these required_steps. There is no identity step at L1, so the whole ceremony is one box and one button.

Esign Comply's guidance for a consent form

An unchecked checkbox and a named button

For a consent form, Esign Comply recommends the checkbox method at level L1. The box starts unchecked, the sentence beside it says what the person agrees to, and the button carries the label the notice names. Switch the profile to a typed name when the form needs a signature line, and to L2 when you want Esign Comply to confirm the person's email with a one-time code.

  • MethodCheckbox
  • LevelL1, no identity step
  • method: checkboxassurance_level: L1document_type: consentpurpose: other
  1. 01

    The SDK attaches to your form

    client.attached
    The signer sees

    Your consent form, wherever it lives: a booking flow, a study signup, a settings page.

    Esign Comply records

    The page the form ran on and the SDK that attached to it, with the viewport, the language and the time zone.

  2. 02

    The consent text is shown

    document.presented:<version_id>
    The signer sees

    The consent text itself, or a clear link to it, placed before the checkbox.

    Esign Comply records

    The version presented and how: inline with a hash of the text, or as a link with its wording, its address and whether it was opened.

  3. 03

    The notice is captured

    notice.captured
    The signer sees

    The notice above the button: "By checking the box and clicking Give consent, you agree to the Research Participation Consent."

    Esign Comply records

    The notice text, the checkbox label and its unchecked starting state, the button label and the layout of the area.

  4. 04

    The person ticks the box

    intent.captured
    The signer sees

    An unchecked box with a full sentence beside it, which they tick themselves.

    Esign Comply records

    The tick, the label text, the box's starting state, and whether a real user event changed it. An untick is recorded too.

  5. 05

    The consent is given

    signature.applied
    The signer sees

    The button named in the notice. It stays disabled until the box is ticked.

    Esign Comply records

    The final act and the time Esign Comply received it. The record is sealed and a signed receipt comes back.

A box that is pre-checked, or ticked by a script, is reported exactly as the SDK found it and fails the rule that every checkbox starts unchecked. The prompt tells your tool never to pre-check a box and never to treat scrolling or continued use as consent.

You vibe code · Esign Comply handles

What you build for a consent form, and what Esign Comply handles

Consent is its own question, so it gets its own record. You own the form and what the consent switches on. Esign Comply owns the rules for the form and the record of each answer.

A consent of its own

You vibe code

Keep the consent apart from signup: its own step, its own checkbox, its own button.

Esign Comply handles

A separate session and a separate sealed record for the consent, apart from the record of your terms.

The form text

You vibe code

Write the form in plain words and register each version through the API.

Esign Comply handles

Pins the exact version each person agreed to, by hash. A reworded form is a new version.

The checkbox and the button

You vibe code

An unchecked native checkbox, a label that says what the person agrees to, and a button whose label matches the notice.

Esign Comply handles

The rules prompt tells your AI tool exactly that, and the SDK records the box's starting state and the person's own tick.

Who consented

You vibe code

Pass your own ID for the person as signer.external_id, plus their email when you want them to get a copy.

Esign Comply handles

Records the ID as supplied by you and emails the receipt. At L2 it also confirms a one-time code sent to that address.

Acting on the consent

You vibe code

Check for a confirmed record before you record the call, publish the photo or start the study.

Esign Comply handles

Server confirmation with GET /v1/records/{id} and the signed record.completed webhook.

A changed form

You vibe code

Publish the new version as a material change and ask again on a screen with an unchecked box.

Esign Comply handles

GET /v1/signers/{external_id}/status lists the people whose consent to the current version is outstanding.

Withdrawal

You vibe code

Build the control that lets a person withdraw, and act on it in your app.

Esign Comply handles

Seals your report of the withdrawal beside the record when you send it with POST /v1/supplements. The original record stays unchanged.

The record

The record you get for each consent

One person, one consent, one sealed record. It stands apart from the record of your terms, so you show the consent by itself to whoever asks.

Sealed at signing · kept by Esign Comply

What the sealed record holds

  • The exact version of the consent form, by SHA-256 hash.
  • The checkbox label, its unchecked starting state and the person's own tick.
  • The notice text and the button label as rendered.
  • The ID you passed for the person, marked as supplied by you.
  • Esign Comply's server time for each step.
  • A signed receipt (ES256), an RFC 3161 timestamp from an outside authority and an entry in the hash-chained ledger.
Yours to store, send and check

What you do with it

  • Signed receiptStore it in your consents tableOne row per consent with the record ID and the receipt. Your app reads its own table, and the receipt ties each row to the sealed record.
  • PDF, per recordEvidence reportGET /v1/records/{id}/report returns the Electronic Acceptance Evidence Report for that consent: the form version, the exact label and button text, and the timeline.
  • verify_urlVerification pageEach consent has a verification page. With an email on the session, Esign Comply also sends the person a copy with that link.
  • ZIP, verifies offlineEvidence packageThe record, the receipt, the timestamp token, the ledger proof and the exact document bytes. Anyone you hand it to runs the open-source esigncomply-verify with no account and no network.

Questions about recording consent on your own form

How do I record consent on a form I built myself?

Register the form text as a document, create a session on your server with POST /v1/sessions, and attach the browser SDK to your own checkbox and button. The SDK reports the form, the notice and the person's tick straight from their browser, and the API seals a record and returns a signed receipt that you store next to the consent.

Read the quickstart

Should consent be separate from my terms of service?

Yes. Give the consent its own unchecked box, its own sentence and its own button, and record it in its own session. The person answers one clear question, and you hold one record that covers that consent and nothing else.

Is a checkbox enough for a consent form?

A checkbox is the method Esign Comply recommends for a consent form: an unchecked box, a sentence that says what the person agrees to, and a named button, at level L1. Switch the profile to a typed name when the form needs a signature line, and to L2 when you want Esign Comply to confirm the person's email with a one-time code.

What does the record of a consent contain?

The exact version of the form by hash, the notice and button text as rendered, the checkbox label with its unchecked starting state and the person's own tick, Esign Comply's server time for every step, a receipt signed with keys you do not hold, an RFC 3161 timestamp from an outside authority, and an entry in a hash-chained ledger.

Evidence and verification

What happens when I change the consent form?

Publish the changed text as a new version and mark it as a material change. GET /v1/signers/{external_id}/status then lists the form as outstanding for everyone who agreed to an earlier version, and your app asks them again. Each new consent is a new record, and the earlier ones stay on file unchanged.

Re-acceptance guide

Build the consent form yourself. Leave the record to us.

Free plan: 10 live signatures a month and a full test mode. No card required.

Cursor, Lovable, Supabase and the other product names on this page are trademarks of their owners. Esign Comply is not affiliated with them.

Working with an AI tool? This page is also available as Markdown: /use-cases/consent-form.md