Consumer e-consent
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)). 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, and refuses to complete a session that lacks one with steps_incomplete. The matching conformance rule is 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:
- The profile has
consumer_econsent: true. - The session's signer is a consumer:
signer.classis"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:
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:
{
"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 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:
Consent to receive records electronically
Sub-headings:
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:
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. Then render the consent block before the documents and the assent control. This component takes the attached ceremony.
"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<HTMLElement>(null);
const consentRef = useRef<HTMLInputElement>(null);
const [sampleHtml, setSampleHtml] = useState<string | null>(null);
const [demonstrated, setDemonstrated] = useState(false);
const [message, setMessage] = useState<string | null>(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 (
<section aria-labelledby="econsent-heading">
<article ref={disclosureRef}>
<h2 id="econsent-heading">Consent to receive records electronically</h2>
<h3>What you are agreeing to</h3>
<p>{/* your text */}</p>
<h3>Whether this consent covers one transaction or all records</h3>
<p>{/* your text */}</p>
<h3>Your right to receive paper copies</h3>
<p>{/* your text */}</p>
<h3>How to request a paper copy after consenting, and any fee</h3>
<p>{/* your text */}</p>
<h3>How to withdraw consent, and any conditions, consequences, or fees</h3>
<p>{/* your text */}</p>
<h3>How to update your contact details</h3>
<p>{/* your text */}</p>
<h3>What you need to access and keep the records</h3>
<p>{/* your text */}</p>
</article>
<div>
<p>To confirm you can open the records we will send, open this sample and enter the code shown inside it.</p>
<button type="button" onClick={openSample}>
Open sample
</button>
{sampleHtml ? <div role="document" aria-label="Sample record" dangerouslySetInnerHTML={{ __html: sampleHtml }} /> : null}
<form action={submitCode}>
<label htmlFor="access-code">Code shown in the sample</label>
<input id="access-code" name="code" inputMode="numeric" autoComplete="off" required />
<button type="submit">Confirm code</button>
</form>
</div>
<div>
<input ref={consentRef} id="econsent" type="checkbox" disabled={!demonstrated} />
<label htmlFor="econsent">I consent to receive these records electronically.</label>
</div>
{message ? <p role="alert">{message}</p> : null}
</section>
);
}
Rules for this screen:
- The consent checkbox starts unchecked and is ticked only by the consumer (CR-01). It is its own control. Do not reuse the terms checkbox for it.
- Call
giveEConsentonce, 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,
formatis"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 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.
const { data, error } = await esc.signers.withdrawConsent("user_7c1d", {
note: "Requested in account settings.",
});
if (error) throw new Error(error.message);
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
{
"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. A signer with no record returns 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:
{
"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.
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:
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.
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:
- Update the text under "What you need to access and keep the records".
- 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.
- Offer withdrawal without a fee on the same screen.
- Optionally file a
notice.sentsupplement with rule IDUS-26for the notice you sent.
Checklist
- The profile has
consumer_econsent: trueand the session sendssigner.class: "consumer". required_stepslistsdisclosure.presented,access.demonstratedandeconsent.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-pagereports no finding markedblockfor CR-16.