Re-acceptance
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:
- Publish the new version with
material_change: true. - Ask
GET /v1/signers/{external_id}/statuswhether a signed-in user has anything outstanding. - Show a blocking screen and run a ceremony with
purpose: "policy_update". - Confirm the new record on your server and let the user through.
Publish a material change
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: trueis 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_atmay be in the future. The new version becomescurrentat 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:
{
"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
GET /v1/signers/user_7c1d/status
Authorization: Bearer esc_test_us_...
Any secret key can call it, including a recording_access key.
{
"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:
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<string, { at: number; value: OutstandingDocument[] }>();
export async function outstandingDocuments(signerId: string): Promise<OutstandingDocument[]> {
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:
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.
"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.
"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<Awaited<ReturnType<typeof startUpdateCeremony>>, { ok: true }>;
const PAGES: Record<string, string> = { doc_8Hq2: "/legal/terms", doc_Pv71: "/legal/privacy" };
export function AcceptUpdatesForm({ summaries }: { summaries: Array<{ documentId: string; name: string; summaryOfChanges: string | null }> }) {
const assentRef = useRef<HTMLDivElement>(null);
const checkboxRef = useRef<HTMLInputElement>(null);
const submitRef = useRef<HTMLButtonElement>(null);
const ceremonyRef = useRef<Ceremony | null>(null);
const requestedRef = useRef(false);
const [started, setStarted] = useState<Started | null>(null);
const [ready, setReady] = useState(false);
const [message, setMessage] = useState<string | null>(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<HTMLAnchorElement>("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<HTMLFormElement>) {
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 <p>{message ?? "Loading the updated documents."}</p>;
return (
<form onSubmit={onSubmit}>
<h1>We have updated our terms</h1>
<ul>
{summaries.map((s) => (
<li key={s.documentId}>
<strong>{s.name}</strong>
{s.summaryOfChanges ? <p>{s.summaryOfChanges}</p> : null}
</li>
))}
</ul>
<div ref={assentRef}>
<input ref={checkboxRef} id="agree-updates" type="checkbox" />
<label htmlFor="agree-updates">
I agree to the updated{" "}
{started.documents.map((d, i) => (
<span key={d.versionId}>
{i > 0 ? " and " : ""}
<a data-version={d.versionId} href={`${PAGES[d.documentId]}?v=${d.versionId}`} target="_blank" rel="noopener">
{d.title}
</a>
</span>
))}
.
</label>
<button ref={submitRef} type="submit" disabled={!ready}>
Accept and continue
</button>
</div>
<p>
<a href="/logout">Log out</a>
</p>
{message ? <p role="alert">{message}</p> : null}
</form>
);
}
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.
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.purposeset topolicy_update. - After the record exists, the status call reports
outstanding: falsefor 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. If you want your own evidence of the notice on file, send it as a supplement when the email goes out:
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.
Test it
- With a test key, publish a second version of a test document with
material_change: true. - Call the status endpoint for a signer who accepted the first version.
outstandinglists the document. - Load a page inside the gated layout. You are redirected to
/accept-updates. - Accept. The record appears in the dashboard, and the status call returns
outstanding: []. - Confirm that the button does nothing while the box is unchecked, and that
finishUpdatewith a made-up record ID does not clear the gate.