Skip to content

Server confirmation

Confirm every record on your server with a secret key or a verified webhook before your application grants access.

POST /v1/sessions/{id}/complete answers the signer's browser. Your server must not trust that answer. A browser can be scripted, a response can be replayed, and a record ID can be made up. Before your application creates an account, unlocks a feature, or shows "signed", your server confirms the record itself.

There are two ways to confirm, and most integrations use both:

Way When it runs Use it for
GET /v1/records/{id} with a secret key In the request that follows the signing act The normal path: the signer is waiting
The record.completed webhook When the record is written and its receipt is signed The backstop: the browser closed or lost its connection before your server heard about the record

What to check

Compare the record with state your server owns. Save that state when you create the session: the signer's external ID and the version_id of every entry in the session's documents.

Check Rule
The call succeeded No error. A made-up ID, a record from another domain or environment, and a voided record all return not_found.
status One of recorded, timestamped, anchored.
livemode What you expect for this deployment: true in production, false everywhere else. A test record must never unlock production access.
signer.external_id Equals the signer ID your server holds for this user or signup.
documents[].version_id Exactly the set of versions the session pinned. Not a subset, not an older version.

Do not use anything else the browser sends. The only value your server takes from the browser is the record ID, and it treats that as a claim to check.

A record whose status is disputed exists and is sealed, and the signer has since used "This was not me" on the receipt. That happens after completion, so it does not appear in the first confirmation. Decide in your own policy what a dispute means for access. Esign Comply records the dispute and does not adjudicate it.

Confirm with the server SDK

Server SDK calls return { data, error } and do not throw.

import "server-only";
import { esc } from "@/lib/esigncomply";

const SEALED = new Set(["recorded", "timestamped", "anchored"]);

export async function confirmRecord(input: {
  recordId: string; // from the browser: untrusted
  expectedSignerId: string; // from your server
  expectedVersionIds: string[]; // saved when the session was created
  expectedLivemode: boolean;
}) {
  const { data: record, error } = await esc.records.get(input.recordId);
  if (error) return { ok: false as const, reason: error.code };

  const actual = record.documents.map((d) => d.version_id).sort();
  const expected = [...input.expectedVersionIds].sort();

  const ok =
    SEALED.has(record.status) &&
    record.livemode === input.expectedLivemode &&
    record.signer.external_id === input.expectedSignerId &&
    actual.length === expected.length &&
    actual.every((v, i) => v === expected[i]);

  return ok ? { ok: true as const, record } : { ok: false as const, reason: "record_mismatch" };
}

Call it from the server action or route that grants access:

const confirmed = await confirmRecord({
  recordId,
  expectedSignerId: signerId,
  expectedVersionIds: ceremony.version_ids,
  expectedLivemode: process.env.VERCEL_ENV === "production",
});
if (!confirmed.ok) {
  return { ok: false, message: "We could not confirm whether your acceptance was recorded. Please wait while we check." };
}
// Only now grant access, and store confirmed.record.id and confirmed.record.receipt in your own table.

Confirm with fetch

The same check without the SDK:

const res = await fetch(`https://esigncomply.com/v1/records/${encodeURIComponent(recordId)}`, {
  headers: { Authorization: `Bearer ${process.env.ESIGNCOMPLY_API_KEY}` },
  cache: "no-store",
});
if (!res.ok) throw new Error("Esign Comply confirmation failed");
const record = await res.json();

const actual = record.documents.map((d: { version_id: string }) => d.version_id).sort();
if (
  !["recorded", "timestamped", "anchored"].includes(record.status) ||
  record.signer.external_id !== expectedSignerId ||
  record.livemode !== expectedLivemode ||
  JSON.stringify(actual) !== JSON.stringify([...expectedVersionIds].sort())
) {
  throw new Error("Unexpected record");
}

What the key can read

GET /v1/records/{id} works with every key permission. A recording_access key, the default for an application, receives the reduced view below: enough for confirmation and nothing that would let a leaked key export evidence. full_access and read_only keys receive the full record. See the Records API.

{
  "object": "record",
  "id": "rec_Z4m8",
  "livemode": false,
  "status": "recorded",
  "signed_at": "2026-11-21T15:03:20.291Z",
  "signature_level": "simple",
  "assurance_level": "L1",
  "capture_mode": "direct",
  "signer": { "external_id": "user_7c1d" },
  "documents": [
    { "document_id": "doc_8Hq2", "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." },
    { "document_id": "doc_Pv71", "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." }
  ],
  "record_hash": "sha256:5be7...",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "verify_url": "https://esigncomply.com/verify/rec_Z4m8",
  "seal": { "timestamp": "pending", "anchor": "pending", "ledger_seq": 18244 },
  "metadata": { "plan": "pro" },
  "quota_locked": false
}

Store record.id and record.receipt in your own database. The receipt is a compact signed token that names the record hash. You can present it later to POST /v1/verify or check it offline. See Verification.

Confirm from the webhook

record.completed is sent once the record is durably written and its receipt is signed. Verify the signature on the raw body first, handle each webhook-id once, then run the same comparison. The payload carries IDs and status, and no personal data beyond the signer's external ID.

{
  "object": "event",
  "id": "whe_8Rt4",
  "type": "record.completed",
  "api_version": "2026-11-21",
  "livemode": false,
  "created_at": "2026-11-21T15:03:20.412Z",
  "data": {
    "record_id": "rec_Z4m8",
    "session_id": "ses_5nWq",
    "signer_external_id": "user_7c1d",
    "status": "recorded",
    "record_hash": "sha256:5be7...",
    "signed_at": "2026-11-21T15:03:20.291Z",
    "assurance_level": "L1",
    "signature_level": "simple",
    "documents": [
      { "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." },
      { "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." }
    ],
    "purpose": "account_signup"
  }
}
export async function POST(request: Request) {
  const rawBody = await request.text();
  const { data: event, error } = await esc.webhooks.verify(
    rawBody,
    request.headers,
    process.env.ESIGNCOMPLY_WEBHOOK_SECRET!,
  );
  if (error) return new Response("Invalid signature", { status: 400 });

  if (event.type === "record.completed") {
    const ceremony = await loadCeremonyBySession(event.data.session_id); // your server-owned state
    const versions = event.data.documents.map((d: { version_id: string }) => d.version_id).sort();
    const matches =
      ceremony !== null &&
      event.livemode === (process.env.VERCEL_ENV === "production") &&
      event.data.signer_external_id === ceremony.signer_id &&
      JSON.stringify(versions) === JSON.stringify([...ceremony.version_ids].sort());
    if (matches) await grantAccess(ceremony, event.data.record_id); // idempotent upsert
  }
  return new Response(null, { status: 200 });
}

A verified webhook already comes from Esign Comply, so the handler does not need a second API call to trust it. Fetch the record anyway when you need fields the payload does not carry, such as document_id. Signature verification, retries and the full event list are under Webhooks.

Records that are still being sealed

The record is written and the receipt is signed before the completion response returns. One exception: if the signing key service cannot be reached, the record is still committed, the response carries status: "pending_seal" and receipt: null, and the receipt is signed within 60 seconds. record.completed fires only once the receipt exists.

For a pending_seal record, the default is to wait: show a short "Finishing up" state and continue when the webhook arrives or when GET /v1/records/{id} returns recorded. You may treat pending_seal as provisional access at your own choice.

The external timestamp (target: within 60 seconds) and the public anchor follow asynchronously and move the status to timestamped and anchored. You do not need to wait for them before granting access.

When the result is inconclusive

A network failure, a 5xx, or a mismatch on any check means your server does not know that a matching record exists. In that case:

  1. Do not grant access and do not create the account.
  2. Show: "We could not confirm whether your acceptance was recorded. Please wait while we check."
  3. Reconcile the existing session before asking the signer to act again. Read it with the secret key:
const { data: session, error } = await esc.sessions.get(sessionId);
if (!error && session.status === "completed" && session.record_id) {
  // The act was recorded. Confirm session.record_id as above.
}

If the session is still active, the signer can repeat the final act on the same session: the browser SDK sends the completion with the same idempotency key, so a repeat never creates a second record. If the session is expired or cancelled, create a new one.

The browser SDK already does part of this. When the completion response is lost, ceremony.complete() looks for the record on the session and resolves with status: "unknown" and the record ID. Your server confirms in every case, whatever the browser reports.

Test it

  • Call your confirmation code with a made-up record ID. It must not grant access.
  • Call it with the ID of a real test record that belongs to a different signer. It must not grant access.
  • In production, call it with a test record ID. The livemode check must refuse it.
  • Run npx esigncomply check --url http://localhost:3000/signup. The active checker posts a forged success to your application and expects access to stay blocked. See the CLI.

For the complete flow in a Next.js application, see Next.js with Supabase.