# L2 verification

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

Source: https://esigncomply.com/docs/guides/l2-verification

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.

```ts
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`:

```json
["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`](https://esigncomply.com/docs/api/errors.md#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.

```ts
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`](https://esigncomply.com/docs/api/errors.md#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

```tsx
"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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/sessions.md).

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

{ "method": "email_otp" }
```

`201 Created`

```json
{
  "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
}
```

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

{ "code": "418205" }
```

`200 OK`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#invalid_request) |
| The session has expired | `401` [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#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`:

```json
{
  "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 links

`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.

```ts
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`](https://esigncomply.com/docs/api/errors.md#service_unavailable): offer `email_otp`.

## What ends up in the record

The record keeps what Esign Comply observed, tagged `observed`:

```json
{
  "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](https://esigncomply.com/docs/conformance.md#cr-17): verification complete for L2 and L3. A session that reaches the final act without it returns [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/guides/test-mode.md). For a credential bound to the signing act on top of L2, see [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md).
