Skip to content

L2 verification

Verify control of the signer's email address or phone number inside the ceremony with a one-time code or link.

At assurance level L1 your application tells Esign Comply who the signer is, and that identity is recorded as asserted. At L2, Esign Comply itself sends a one-time code or link to the signer's email address or phone number during the ceremony and records whether it came back. The receipt then goes to the verified address.

L2 records that a person who controlled that mailbox or phone at that moment took part in the ceremony. It does not establish legal identity, authority to sign, or who was holding the device. L2 is the default for NDAs, order forms and contracts, and it is still a simple electronic signature or recorded acceptance.

What you need

  • A profile with assurance_level: "L2". L2 is available on every plan, in test mode and live. The Free plan verifies by email: SMS codes need a paid plan.
  • A session whose signer has the destination: signer.email for the email methods, signer.phone for SMS. The destination always comes from the session your server created. The browser cannot change it.
const { data, error } = await esc.sessions.create(
  {
    profile: "prof_nda_9c2e", // assurance_level L2, method typed
    signer: { external_id: "user_7c1d", email: "dana@example.org", name: "Dana Whitfield", class: "business", country: "US" },
    documents: [{ document: "doc_Nd55", version: "current" }],
    context: { url: "https://app.example.com/nda/42", locale: "en-US", purpose: "nda" },
  },
  { idempotencyKey: "nda-42-user_7c1d-1" },
);

The session's required_steps then include identity.verified:

["client.attached", "document.presented:dv_3kT9", "notice.captured", "identity.verified", "intent.captured", "signature.applied"]

Read the list from the session. Do not hard-code it.

Methods

Method Sent to The signer
email_otp signer.email Types a 6-digit code on your page
email_link signer.email Opens a link in the message, which confirms on an Esign Comply page
sms_otp signer.phone Types a 6-digit code on your page

Esign Comply sends the message from its own domain. The message names your organization and the document titles, and says that Esign Comply is an independent record keeper. You do not send or see the code.

email_otp is the simplest to build because the signer stays on your page. The examples below use it.

Limits

Limit Value
Code length 6 digits
Code lifetime 10 minutes
Wrong attempts per code 5. The fifth wrong attempt ends the session.
Messages per session 3
SMS per subscription year Free none, Starter 500, Unlimited 5,000, Enterprise as contracted. Email verification is not limited.

When the SMS allowance is used up, or the plan has none, sms_otp returns plan_feature_unavailable. Offer email_otp instead.

With the browser SDK

Two calls. verify.start sends the message and returns the masked destination. verify.confirm checks the code the signer typed against the most recent verification.

const verification = await ceremony.verify.start({ method: "email_otp" });
// { id: "ver_2bQd", method: "email_otp", destination: "d***@example.org",
//   status: "pending", expiresAt: "2026-11-21T15:13:01.000Z", attemptsRemaining: 5 }

const result = await ceremony.verify.confirm({ code: "418205" });
// { id: "ver_2bQd", status: "confirmed", attemptsRemaining: 5 }

A wrong code does not reject. It resolves with status: "failed" and the attempts left, so you can ask the signer to try again. The call rejects with an EsignComplyError whose code is verification_failed in three cases: the code has expired, the session has used its 3 messages, or the fifth wrong attempt has ended the session.

When a verification is confirmed, Esign Comply records the identity.verified step itself. ceremony.remainingSteps() no longer lists it, and the change and stepRecorded events fire. The event name is historical. It records verified control of a channel, not identity.

A complete verification block

"use client";

import { useState } from "react";
import type { Ceremony, EsignComplyError } from "@esigncomply/browser";

export function EmailVerification({ ceremony, onVerified }: { ceremony: Ceremony; onVerified: () => void }) {
  const [destination, setDestination] = useState<string | null>(null);
  const [canSend, setCanSend] = useState(true);
  const [verified, setVerified] = useState(false);
  const [ended, setEnded] = useState(false);
  const [message, setMessage] = useState<string | null>(null);

  async function send() {
    setMessage(null);
    try {
      const v = await ceremony.verify.start({ method: "email_otp" });
      setDestination(v.destination); // masked, for example d***@example.org
      setCanSend(false);
      setTimeout(() => setCanSend(true), 30_000); // allow a resend after 30 seconds
    } catch (err) {
      const error = err as EsignComplyError;
      setMessage(error.message); // for example: the limit of 3 messages was reached
      if (error.code === "session_not_active" || error.code === "client_token_expired") setEnded(true);
    }
  }

  async function confirm(form: FormData) {
    setMessage(null);
    try {
      const result = await ceremony.verify.confirm({ code: String(form.get("code") ?? "") });
      if (result.status === "confirmed") {
        setVerified(true);
        onVerified();
      } else {
        setMessage(`That code did not match. Attempts left: ${result.attemptsRemaining}.`);
      }
    } catch (err) {
      const error = err as EsignComplyError;
      setMessage(error.message); // expired code, or too many wrong attempts
      if (error.code === "verification_failed") setDestination(null); // this code is finished: ask for a new one
      else setEnded(true);
    }
  }

  if (verified) return <p>Email verified: {destination}</p>;
  if (ended) return <p role="alert">{message} Reload the page to start a new session.</p>;

  return (
    <section aria-label="Verify your email">
      <button type="button" onClick={send} disabled={!canSend}>
        {destination ? "Send a new code" : "Send code"}
      </button>
      {destination ? (
        <form action={confirm}>
          <label htmlFor="otp">Enter the 6-digit code sent to {destination}</label>
          <input id="otp" name="code" inputMode="numeric" autoComplete="one-time-code" pattern="[0-9]{6}" maxLength={6} required />
          <button type="submit">Verify</button>
        </form>
      ) : null}
      {message ? <p role="alert">{message}</p> : null}
    </section>
  );
}

Guidelines for the screen:

  • Show the masked destination the API returns. Do not print the full address from your own data next to it.
  • Let the signer ask for a new code after 30 seconds, and tell them when no more can be sent.
  • After too many wrong attempts the session has ended. The next call rejects with session_not_active: create a new session on your server and attach again.
  • Keep the signing button disabled until ceremony.remainingSteps() contains only "signature.applied".
  • Do not ask for the code in your own form and forward it through your server. The SDK sends it straight to Esign Comply.

The API calls underneath

The SDK calls two browser endpoints with the session client token. Use them directly only if you cannot use the SDK. See the Sessions API.

POST /v1/sessions/ses_5nWq/verifications
Authorization: Bearer esc_ct_...
Content-Type: application/json

{ "method": "email_otp" }

201 Created

{
  "object": "verification",
  "id": "ver_2bQd",
  "method": "email_otp",
  "destination": "d***@example.org",
  "status": "pending",
  "expires_at": "2026-11-21T15:13:01.000Z",
  "attempts_remaining": 5,
  "sends_remaining": 2,
  "delivered": true
}
POST /v1/sessions/ses_5nWq/verifications/ver_2bQd/confirm
Authorization: Bearer esc_ct_...
Content-Type: application/json

{ "code": "418205" }

200 OK

{
  "object": "verification",
  "id": "ver_2bQd",
  "status": "confirmed",
  "attempts_remaining": 5,
  "remaining_steps": ["intent.captured", "signature.applied"]
}

A wrong code returns 200 with "status": "failed" and a lower attempts_remaining.

Situation Response
Wrong code, attempts left 200, status: "failed"
Fifth wrong attempt 422 verification_failed. The session is cancelled.
Code older than 10 minutes 422 verification_failed. Send a new code.
Fourth message in one session 422 verification_failed. Create a new session.
The session has no signer.email or signer.phone 400 invalid_request
The session has expired 401 client_token_expired

Session status

Sending a code moves the session to awaiting_verification. A confirmed verification moves it back to in_progress, or to ready when every step before the final act is recorded. GET /v1/sessions/{id} with your secret key shows the status and lists identity.verified under completed_steps.

A lockout cancels the session. Your server receives session.cancelled:

{
  "object": "event",
  "id": "whe_8Rt4",
  "type": "session.cancelled",
  "api_version": "2026-11-21",
  "livemode": false,
  "created_at": "2026-11-21T15:09:44.120Z",
  "data": { "session_id": "ses_5nWq", "cancelled_by": "system", "reason": "verification_failed" }
}

To let the signer try again, create a new session on your server and attach again.

email_link sends a link instead of a code. Opening the link confirms the verification on a page served by Esign Comply, which tells the signer to return to the page where they were signing. The link is valid for 10 minutes and counts toward the 3 messages per session.

const verification = await ceremony.verify.start({ method: "email_link" });
// Show: "We sent a link to d***@example.org. Open it, then come back to this page."

ceremony.on("stepRecorded", (step) => {
  if (step.type === "identity.verified") showVerified();
});

There is nothing to confirm from your page. After verify.start, the SDK checks the session every few seconds for up to 10 minutes. When the link has been used it fires stepRecorded and change, and ceremony.remainingSteps() no longer lists identity.verified. Keep the page open while the signer goes to their mailbox.

SMS

sms_otp needs signer.phone on the session, in international format. The destination is masked to its last two digits, for example ***42. SMS verifications count against the plan's yearly allowance. If SMS cannot be sent, the call returns service_unavailable: offer email_otp.

What ends up in the record

The record keeps what Esign Comply observed, tagged observed:

{
  "signer": {
    "external_id": "user_7c1d",
    "name": "Dana Whitfield",
    "email": "dana@example.org",
    "verified_email": "dana@example.org",
    "verification": [
      { "method": "email_otp", "destination": "d***@example.org", "at": "2026-11-21T15:04:11.902Z", "attempts": 1 }
    ]
  },
  "assurance_level": "L2"
}

signer.email and signer.name remain asserted by you. signer.verified_email is present only because Esign Comply verified control of it. The evidence report masks the address and shows the method, the time and the number of attempts.

The conformance rule is CR-17: verification complete for L2 and L3. A session that reaches the final act without it returns steps_incomplete with identity.verified in missing_steps.

Test mode

  • signer+ok@test.esigncomply.com accepts the code 000000.
  • signer+wrongcode@test.esigncomply.com never verifies. Use it to build the failure and lockout screens.
  • Codes for other addresses are emailed only to verified addresses of your own team. For any other address nothing is sent, and the code comes back as code in the response (verification.code in the SDK), with delivered: false, so automated tests can finish the ceremony.

See Test mode. For a credential bound to the signing act on top of L2, see L3 passkeys.