# Sessions

> Start a ceremony, append its events from the browser, verify a channel or passkey, and complete it into a sealed record.

Source: https://esigncomply.com/docs/api/sessions

A session is one ceremony in progress for one signer over a bundle of document versions. Your server creates it with a secret key and hands the returned `client_token` to the browser. The browser SDK then reports each step straight to Esign Comply with that token, and the final call seals a record. The API refuses to seal until every step in the session's `required_steps` has been recorded in a valid order.

Most integrations call only the first endpoint directly. The [browser SDK](https://esigncomply.com/docs/sdk/browser.md) makes the client-token calls for you. They are documented here so that you can read network traces, write tests, and build server-only flows.

| Method and path | Key | Purpose |
|---|---|---|
| `POST /v1/sessions` | Secret (`full_access`, `recording_access`) | Start a ceremony. Returns `client_token` and `required_steps`. |
| `GET /v1/sessions/{id}` | Secret (any permission) or client token | Read state and remaining steps. |
| `POST /v1/sessions/{id}/events` | Client token | Append one ceremony event. |
| `GET /v1/sessions/{id}/access-sample` | Client token | Sample document with the access code, for the consumer consent flow. |
| `POST /v1/sessions/{id}/verifications` | Client token | Send a one-time code or link, or start a passkey challenge. |
| `POST /v1/sessions/{id}/verifications/{ver_id}/confirm` | Client token | Confirm the code or the passkey response. |
| `POST /v1/sessions/{id}/complete` | Client token | Apply the signing act. Returns the record and receipt. |
| `POST /v1/sessions/{id}/cancel` | Secret (`full_access`, `recording_access`) or client token | Cancel. |

A client token is scoped to one session. It cannot read other sessions, records or account data: any other session ID returns [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found). Client-token calls are accepted only from origins inside the registered domain (live) or from `localhost`, `127.0.0.1`, the registered domain and your listed preview hosts (test). They are rate limited per session, at 240 calls per minute, not per key.

## Session states

| State | Entered when | Next states |
|---|---|---|
| `created` | Your server calls `POST /v1/sessions`. | `in_progress`, `awaiting_verification`, `expired`, `cancelled` |
| `in_progress` | The first client event arrives. | `awaiting_verification`, `ready`, `expired`, `cancelled` |
| `awaiting_verification` | A one-time code or link has been sent, or only verification and intent remain. | `in_progress`, `ready`, `expired`, `cancelled` |
| `ready` | Every required step before the signing act is recorded. | `completed`, `expired`, `cancelled` |
| `completed` | The signing act is recorded and the record is written durably. | Terminal |
| `expired` | The session lifetime is reached (default 30 minutes, maximum 24 hours). | Terminal |
| `cancelled` | Your server or the signer cancels, or verification locks out. | Terminal |

A completed record then moves through its own seal states, independent of the session: `recorded`, `timestamped`, `anchored`. See [Records](https://esigncomply.com/docs/api/records.md).

## Create a session

`POST /v1/sessions`

Key: secret key with `full_access` or `recording_access`. Send an `Idempotency-Key`.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `profile` | string | Yes | Profile ID, for example `prof_signup_4f1a`. |
| `signer.external_id` | string, 1 to 255 characters | Yes | Your own identifier for the person. Asserted by you. |
| `signer.email` | string | No | Used for the receipt and for `email_otp` and `email_link` verification. |
| `signer.name` | string | No | Asserted name. |
| `signer.phone` | string | No | Needed for `sms_otp`. |
| `signer.class` | string | No | `consumer`, `business` or `employee`. Another value is kept with the warning `signer_class_unrecognized:<value>`. When absent, the profile's `signer_class` applies. |
| `signer.country` | string | No | ISO 3166-1 alpha-2, for example `US`. Take it from your form or account data. |
| `signer.region` | string | No | The signer's state as ISO 3166-2 (`US-CA`), or a bare code with `signer.country` (`CA` with `US`). It means where the signer resides or, for employees, primarily works. Never infer it from an IP address. |
| `signer.locality` | string | No | Locality code read by rules with a locality scope, for example `NYC`. |
| `signer.actor_type` | string | No | `human` (default) or `electronic_agent`. |
| `signer.operator`, `signer.authority_reference` | string | No | For `electronic_agent` sessions: who operates the agent and under what authority. |
| `jurisdictions.mode` | `auto`, `strictest`, `explicit` | No | Overrides the profile's mode for this ceremony. |
| `jurisdictions.packs` | array of pack codes | No | Narrows the profile's packs. Required in `explicit` mode. |
| `jurisdictions.governing_law` | string | No | Overrides the profile's governing law. |
| `documents[]` | array, 1 to 10 items | Yes | Each item is `{ "document": "doc_...", "version": "dv_..." }`. Omit `version` or send `"current"` to resolve the version in effect now. |
| `context.url` | string | Live: yes | The page where the ceremony runs. In live mode it must be inside the registered domain. In test mode it must be on `localhost`, `127.0.0.1`, the registered domain or a listed preview host. |
| `context.locale` | string | No | For example `en-US`. Selects document translations when `version` is `current`. |
| `context.purpose` | string | No | `account_signup`, `one_time_purchase`, `free_trial`, `auto_renewal`, `contract_signature`, `nda`, `policy_update`, `other`. Feeds rule scope and the method check. |
| `context.facts` | object | No | Asserted facts that pack rules read, for example `document_category`. Keys are listed per pack in the [catalogue](https://esigncomply.com/docs/api/jurisdictions.md). |
| `context.notes` | string, up to 2,000 characters | No | Free text, sealed in the record as asserted. Not read by any rule. |
| `context.extra` | any JSON, up to 16 KB | No | Arbitrary JSON, sealed in the record as asserted. Not read by any rule. |
| `metadata` | object, up to 50 keys | No | Your own key-value pairs. Returned on the record. |
| `expires_in` | integer, 60 to 86,400 | No | Lifetime in seconds. Default 1,800. |
| `capture_mode` | `direct`, `server_only` | No | `direct` (default): events come from the signer's browser. `server_only`: your server sends the events with the secret key, and every event is tagged asserted. |

**Example request**

```bash
curl https://esigncomply.com/v1/sessions \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-user_7c1d-tos-2026-11-21" \
  -d '{
    "profile": "prof_signup_4f1a",
    "signer": {
      "external_id": "user_7c1d",
      "email": "dana@example.org",
      "name": "Dana Whitfield",
      "class": "consumer",
      "country": "US",
      "region": "US-CA"
    },
    "documents": [
      { "document": "doc_8Hq2", "version": "current" },
      { "document": "doc_Pv71", "version": "current" }
    ],
    "context": {
      "url": "http://localhost:3000/signup",
      "locale": "en-US",
      "purpose": "account_signup",
      "notes": "Signup A/B variant 7."
    },
    "metadata": { "plan": "pro" },
    "expires_in": 1800
  }'
```

**Example response**

`201 Created`

```json
{
  "object": "session",
  "id": "ses_5nWq",
  "status": "created",
  "livemode": false,
  "client_token": "esc_ct_...",
  "expires_at": "2026-11-21T15:32:11.000Z",
  "profile": { "id": "prof_signup_4f1a", "version": 1 },
  "assurance_level": "L1",
  "signature_method": "checkbox",
  "capture_mode": "direct",
  "minimal_capture": false,
  "required_steps": [
    "client.attached",
    "document.presented:dv_3kT9",
    "document.presented:dv_Lm02",
    "notice.captured",
    "intent.captured",
    "signature.applied"
  ],
  "documents": [
    {
      "document_id": "doc_8Hq2",
      "version_id": "dv_3kT9",
      "render_hash": "sha256:41ab...",
      "content_hash": "sha256:9f2c...",
      "title": "Terms of Service",
      "type": "terms",
      "language": "en",
      "format": "markdown"
    },
    {
      "document_id": "doc_Pv71",
      "version_id": "dv_Lm02",
      "render_hash": "sha256:77d0...",
      "content_hash": "sha256:c01e...",
      "title": "Privacy Notice",
      "type": "privacy_notice",
      "language": "en",
      "format": "text"
    }
  ],
  "applied_jurisdictions": [
    { "code": "US-FED", "version": "2026-11-21", "reason": "base" },
    { "code": "US-CA", "version": "2026-11-21", "reason": "signer_region" }
  ],
  "jurisdiction_mode": "auto",
  "rule_set_version": "2026.11.21",
  "rules_fired": ["US-01", "US-08", "US-09", "US-11"],
  "required_strings": [],
  "retention_floor": null,
  "guidance_release": "2026.11.3",
  "advisories": [],
  "warnings": [],
  "api_url": "https://esigncomply.com/v1"
}
```

**Response fields**

| Field | Description |
|---|---|
| `client_token` | Short-lived token (`esc_ct_...`) scoped to this session. Send only this to the browser. It is returned once, here. |
| `required_steps` | The authoritative list of steps for this session. Read it and satisfy each entry. Do not hard-code steps. |
| `documents[]` | The exact versions pinned. Save the `version_id` values in server-owned state: you compare them with the record at confirmation. |
| `applied_jurisdictions[]` | Each applied pack with `code`, `version` and `reason` (`base`, `signer_region`, `governing_law`, `organization_region`, `strictest`, `explicit`). |
| `rules_fired[]` | IDs of the pack rules that fired. |
| `required_strings[]` | Wording the applied packs ask the page to carry: `slot`, `block`, `rule`, `kind` (`verbatim` or `elements`), `text`, `translations`, `elements`, `statutory`, `label`, `check`. Render every `verbatim` string as given in the slot named. |
| `retention_floor` | The longest retention floor among applied packs, or null. |
| `minimal_capture` | `true` when optional markup, style, layout, network and device capture is off: the profile uses `eu_minimal`, or an `EU`, `UK` or `CH` pack applied. `notice.captured` is not a required step then. |
| `advisories[]` | Record conditions in the advise state that were not met or would add a step: `rule`, `finding`, `notice`. Never a reason for an error. |
| `warnings[]` | Non-blocking concerns. Open list. |
| `api_url` | The regional API base for this session. Pass it to the browser SDK as `apiUrl` when you serve EU-region domains. |

The same jurisdiction values are sealed in the record.

**Rules**

- **Declared URL.** `context.url` must fall within the registered domain in live mode, otherwise `403 domain_mismatch`. Live mode requires it.
- **Pack selection.** `signer.class`, `signer.country`, `signer.region` and the governing law select the packs within the profile. The full rules, including unknown location, are under [Jurisdictions](https://esigncomply.com/docs/api/jurisdictions.md).
- **Client token.** Short-lived, signed, scoped to one session.
- **Exclusion screen.** The union of the exclusion screens of every applied pack runs here, against `context.facts.document_category`. A blocked category returns `422 document_type_excluded` with the reason and the rule ID.
- **Customer-supplied context.** `context.notes`, `context.extra`, `context.facts` and `metadata` are sealed inside the record as asserted material and are printed apart from what Esign Comply observed.
- **Tolerant input.** Unknown top-level or nested fields are ignored and reported as `unknown_field:<path>`. Unknown fact keys are stored with `fact_unrecognized:<key>`. Neither is an error. A wrong type for a known field or a missing required field still returns `400`.
- **Advisories** never change the status code or `required_steps`.
- **Quota.** The plan's limit is checked here, never at completion. Past the limit, a new live session can be refused with `402` [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted). Sessions already created still complete. See [Free plan limits](https://esigncomply.com/docs/guides/test-mode.md#free-plan-limits) and [Starter limits](https://esigncomply.com/docs/guides/test-mode.md#starter-limits).

**Warnings**

Common values: `unknown_field:<path>`, `signer_class_unrecognized:<value>`, `signer_country_missing`, `signer_region_missing`, `signer_region_unrecognized`, `state_pack_unavailable:<code>`, `jurisdiction_not_enabled:<code>`, `governing_law_no_pack:<code>`, `fact_missing:<key>`, `fact_unrecognized:<key>`, `document_type_requires_review:<id>`, `record_conditions_pending_adoption`, `pack_version_stale`. Each is explained under [Jurisdictions](https://esigncomply.com/docs/api/jurisdictions.md).

**Errors**

| Code | When |
|---|---|
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | Malformed body, `signer.email` is not an email address, `metadata` has more than 50 keys, `context.extra` is over 16 KB, `context.url` missing in live mode, or `explicit` mode without `jurisdictions.packs`. |
| [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) | Unknown profile, document or version in this domain and environment. `param` names the field, for example `documents.0.document`. |
| [`version_not_published`](https://esigncomply.com/docs/api/errors.md#version_not_published) | A document has no published version, or none in effect yet. |
| [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch) | `context.url` is outside the registered domain (live) or the test allowlist (test). |
| [`domain_not_verified`](https://esigncomply.com/docs/api/errors.md#domain_not_verified) | Live key before domain verification, or verification lapsed more than 14 days ago. |
| [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) | Live session after the subscription was canceled, or for a domain in a region the plan does not include (the EU region on Free), or the profile's assurance level is not on the plan. |
| [`quota_exhausted`](https://esigncomply.com/docs/api/errors.md#quota_exhausted) | Live mode, on Free or Starter: the request came past the plan's limit and the new live signature was refused. The error carries `plan`, `limit`, `period`, `locked_since` and `upgrade_url`. Sessions already created still complete. |
| [`test_quota_exceeded`](https://esigncomply.com/docs/api/errors.md#test_quota_exceeded) | This month's test-mode allowance is used up. |
| [`jurisdiction_unknown`](https://esigncomply.com/docs/api/errors.md#jurisdiction_unknown), [`jurisdiction_not_enabled`](https://esigncomply.com/docs/api/errors.md#jurisdiction_not_enabled), [`signer_region_required`](https://esigncomply.com/docs/api/errors.md#signer_region_required), [`jurisdiction_fact_required`](https://esigncomply.com/docs/api/errors.md#jurisdiction_fact_required), [`document_type_excluded`](https://esigncomply.com/docs/api/errors.md#document_type_excluded) | Jurisdiction resolution refused the session. |
| [`idempotency_conflict`](https://esigncomply.com/docs/api/errors.md#idempotency_conflict) | The `Idempotency-Key` was reused with a different body. |

## Retrieve a session

`GET /v1/sessions/{id}`

Key: secret key with any permission, or the session's own client token.

Reading a session whose lifetime has passed marks it `expired` and sends the `session.expired` webhook.

The response depends on the caller.

| Caller | Fields |
|---|---|
| Client token | `object`, `id`, `status`, `livemode`, `expires_at`, `assurance_level`, `signature_method`, `capture_mode`, `minimal_capture`, `required_steps`, `completed_steps`, `remaining_steps`, `documents[]`, `required_strings[]`, `record_id`, `purpose`, `locale` |
| Secret key | All of the above, plus `profile`, `applied_jurisdictions[]`, `jurisdiction_mode`, `rule_set_version`, `rules_fired[]`, `retention_floor`, `guidance_release`, `advisories[]`, `warnings[]`, `signer` (`class`, `country`, `region`, `locality`, `actor_type`), `context` (`url`, `purpose`, `facts`), `metadata`, `created_at`, `completed_at` |

Neither view returns the client token again or the signer's name, email or phone. `record_id` is set once the session is completed. Use it to recover the record ID when a completion response was lost.

**Example request**

```bash
curl https://esigncomply.com/v1/sessions/ses_5nWq \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK` (client-token view)

```json
{
  "object": "session",
  "id": "ses_5nWq",
  "status": "in_progress",
  "livemode": false,
  "expires_at": "2026-11-21T15:32:11.000Z",
  "assurance_level": "L1",
  "signature_method": "checkbox",
  "capture_mode": "direct",
  "minimal_capture": false,
  "required_steps": ["client.attached", "document.presented:dv_3kT9", "document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied"],
  "completed_steps": ["session.created", "client.attached", "document.presented:dv_3kT9"],
  "remaining_steps": ["document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied"],
  "documents": [
    { "document_id": "doc_8Hq2", "version_id": "dv_3kT9", "render_hash": "sha256:41ab...", "content_hash": "sha256:9f2c...", "title": "Terms of Service", "type": "terms", "language": "en", "format": "markdown" },
    { "document_id": "doc_Pv71", "version_id": "dv_Lm02", "render_hash": "sha256:77d0...", "content_hash": "sha256:c01e...", "title": "Privacy Notice", "type": "privacy_notice", "language": "en", "format": "text" }
  ],
  "required_strings": [],
  "record_id": null,
  "purpose": "account_signup",
  "locale": "en-US"
}
```

**Errors**

[`not_found`](https://esigncomply.com/docs/api/errors.md#not_found), [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired), [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch).

## Append a ceremony event

`POST /v1/sessions/{id}/events`

Key: client token. A secret key is accepted only for a session created with `capture_mode: "server_only"`.

The browser SDK calls this for every step. Events are append-only, strictly ordered by `sequence`, and chained by hash. Each event is stored with Esign Comply's server receipt time. Any client-reported time is kept separately.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | Yes | One of the event types below. Any other value returns `400 invalid_request`. |
| `version_id` | string | For `document.presented` | The pinned version this event is about. |
| `client_time` | string | No | The browser's clock, RFC 3339 with offset. Reported, not verified. |
| `data` | object, up to 256 KB | No | Event payload. See "Event data". |

**Event types**

| `type` | Step it satisfies | Tag | SDK method |
|---|---|---|---|
| `client.attached` | `client.attached` | observed | `EsignComply.attach` |
| `disclosure.presented` | `disclosure.presented` | observed | `presentDisclosure` |
| `access.demonstrated` | `access.demonstrated` | observed | `demonstrateAccess` |
| `econsent.given` | `econsent.given` | observed | `giveEConsent` |
| `document.presented` | `document.presented:<version_id>` | observed | `presentDocument` |
| `notice.captured` | `notice.captured` | observed | `observeAssent` |
| `intent.captured` | `intent.captured` | observed | `observeAssent`, on the signer's action |
| `review.presented` | `review.presented` | observed | `reviewPresented` |
| `language.selected` | Optional event | observed | `languageSelected` |
| `renewal_terms.presented` | `renewal_terms.presented` | observed | `renewalTerms` |
| `renewal.consent_given` | `renewal_consent.captured` | observed | `renewalConsent` |
| `electronic_agreement.given` | `electronic_agreement.captured` | observed | `electronicAgreement` |
| `sensitive_capture.consent_given` | `sensitive_capture_consent.captured` | observed | `sensitiveCaptureConsent` |
| `acknowledgment.given` | `acknowledgment.captured` | observed | `acknowledge` |
| `signer.age_attested` | Optional event | asserted | `ageAttested` |
| `billing.confirm` | Optional event | asserted | `billingConfirm` |
| `withdrawal.submitted` | Optional event | asserted | Sent by your page |
| `copy.delivered` | Optional event | asserted | Sent by your page |

The four `asserted` types are statements, not observations, so they are tagged asserted even on the direct browser channel. In a `server_only` session every event is tagged asserted. `session.created`, `identity.verified` and `signature.applied` are produced by Esign Comply and are not accepted here.

**Order**

- In a `direct` session, `client.attached` must be recorded before anything else.
- `access.demonstrated` needs `disclosure.presented`. `econsent.given` needs both.
- `renewal.consent_given` needs `renewal_terms.presented`.
- `intent.captured` needs every step the session requires from this list: `client.attached`, `disclosure.presented`, `access.demonstrated`, `econsent.given`, each `document.presented:<version_id>`, `notice.captured`, `renewal_terms.presented`.

An out-of-order event returns [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) with `missing_steps`, the steps to record first.

**Event data**

`data` is an open object. These are the fields the conformance checks read. The SDK fills them from the elements you pass.

| Event | Fields in `data` |
|---|---|
| `client.attached` | `sdk_version`, `page_url`, `viewport { width, height }`, `language`, `timezone` |
| `document.presented` | `mode` (`hyperlink`, `inline`, `scrollbox`), `language`, `downloadable`, `printable`. For `hyperlink`: `link_text`, `link_href`, `link_href_within_domain`, `link_visible`, `link_opened`, `link_style { underlined, contrast_ratio, font_px }`, `link_target_render_hash`. For `inline` and `scrollbox`: `render_hash` of the text found in the container. |
| `notice.captured` | `text`, `html`, `styles { font_px, body_font_px, contrast_ratio }`, `layout { same_viewport, notice_above_action, notice_to_action_px, viewport }`, `controls { primary_buttons, competing_controls, checkbox { initial_checked, label_text }, typed { initial_empty }, submit { label } }`, `links[]`, `slots {}` (values for `required_strings` slots) |
| `intent.captured` | `control` (`checkbox`, `button`, `typed`, `drawn`), `label_text`, `button_text`, `initial_state` (`unchecked` or `empty`), `trusted` (the change came from a real user event), `typed_name` |
| `econsent.given`, `renewal.consent_given`, `electronic_agreement.given`, `sensitive_capture.consent_given`, `acknowledgment.given` | `control`, `label_text`, `initial_state`, `trusted`, `separate_from_terms` |
| `renewal_terms.presented` | `text`, `elements { renewal_term, price, cancellation_policy, cancel_path }`, `proximity_px`, `same_container`, `styles { font_px, surrounding_font_px, font_weight, contrast_ratio, set_off }` |
| `review.presented` | `text_hash`, `correctable` |
| `language.selected` | `language` |
| `access.demonstrated` | `code` (compared with the sample, then replaced by `matched: true`) |

What is stored:

- Keystrokes are never stored, only the submitted name.
- Drawn strokes are stored only when drawn capture is switched on for the domain.
- In minimal capture, `html`, `styles`, `layout`, `link_style`, `viewport`, `timezone` and other optional device fields are dropped, and the IP address and user agent are not kept.

**Example request**

```http
POST /v1/sessions/ses_5nWq/events
Authorization: Bearer esc_ct_...
Content-Type: application/json
Origin: http://localhost:3000

{
  "type": "document.presented",
  "version_id": "dv_3kT9",
  "client_time": "2026-11-21T10:03:01.120-05:00",
  "data": {
    "mode": "hyperlink",
    "link_text": "Terms of Service",
    "link_visible": true,
    "link_style": { "underlined": true, "contrast_ratio": 1.5, "font_px": 14 },
    "link_target_render_hash": "sha256:41ab...",
    "viewport": { "width": 390, "height": 844 }
  }
}
```

**Example response**

`201 Created`

```json
{
  "object": "event",
  "id": "evt_91xA",
  "type": "document.presented",
  "tag": "observed",
  "server_time": "2026-11-21T15:03:01.377Z",
  "sequence": 3,
  "conformance": {
    "status": "warn",
    "rules_version": "2026.11.2",
    "findings": [
      {
        "rule": "CR-08",
        "status": "pass",
        "state": "enforce",
        "message": "The link resolves to the registered version.",
        "measurement": { "mode": "hyperlink", "link_href": null, "link_target_render_hash": "sha256:41ab...", "render_hash_registered": "sha256:41ab...", "target_checked": true },
        "maps_to": ["US-02", "US-14"],
        "event_type": "document.presented",
        "version_id": "dv_3kT9"
      },
      {
        "rule": "CR-05",
        "status": "warn",
        "state": "enforce",
        "message": "Document link contrast against surrounding text is 1.5 to 1; at least 3 to 1 is expected, in addition to any underline.",
        "fix": "Give document links a colour that differs from the surrounding text by a contrast ratio of at least 3 to 1, and keep them underlined.",
        "measurement": { "contrast_ratio": 1.5, "underlined": true, "font_px": 14, "link_visible": true },
        "maps_to": ["US-11"],
        "event_type": "document.presented",
        "version_id": "dv_3kT9"
      }
    ]
  },
  "remaining_steps": ["document.presented:dv_Lm02", "notice.captured", "intent.captured", "signature.applied"],
  "session_status": "in_progress"
}
```

**Conformance result**

Every event returns a conformance result. `conformance.status` is the strongest status among the findings: `pass`, `warn` or `block`.

| Finding field | Description |
|---|---|
| `rule` | Conformance rule ID, `CR-01` to `CR-28`. See [Conformance](https://esigncomply.com/docs/conformance.md). |
| `status` | `pass`, `warn` or `block`. |
| `state` | `enforce`: the condition can refuse a live record. `advise`: measured and stored only. |
| `message`, `fix` | What was measured and a plain-language repair for the page. |
| `measurement` | The numbers and flags behind the result. Measurements are sealed in the record as facts. |
| `maps_to[]` | Pack rules that fired for this session and are implemented by this check. |

In test mode the response lists every finding, including passes, and nothing blocks. In live mode it lists only findings that did not pass, and a finding with `status: "block"` and `state: "enforce"` stops completion. Findings are advisory statements about measurable design facts. They are not a statement that a flow is lawful or enforceable.

**Errors**

| Code | When |
|---|---|
| [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) | A prerequisite step is missing. `missing_steps` lists it. |
| [`render_mismatch`](https://esigncomply.com/docs/api/errors.md#render_mismatch) | Live mode: the text on the page, or behind the link, does not match the registered version and CR-08 is enforced. The error carries `rule: "CR-08"`, `findings` and `event_id`. The event itself is kept as evidence of what the page presented. |
| [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) | `access.demonstrated` with a code that does not match the sample. |
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | Unknown `type`, `document.presented` without a `version_id` of this session, or `data` over 256 KB. Truncate a notice snapshot to the assent region. |
| [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active) | The session is completed or cancelled. |
| [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired) | The token or the session has expired. Create a new session and attach again. |
| [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) | A secret key was used on a `direct` session. |
| [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#domain_mismatch) | The `Origin` is outside the registered domain or the test allowlist. Live calls with no `Origin` are refused. |
| [`rate_limit_exceeded`](https://esigncomply.com/docs/api/errors.md#rate_limit_exceeded) | More than 240 client-token calls in a minute on this session. |

## Get the access sample

`GET /v1/sessions/{id}/access-sample`

Key: client token.

Returns the sample document for the access demonstration in the consumer consent flow: a short document in the delivery format, containing a six-digit code. The signer opens it and types the code back, which is then sent as an `access.demonstrated` event. The code is generated once per session. See the [consumer consent guide](https://esigncomply.com/docs/guides/consumer-econsent.md).

**Example request**

```http
GET /v1/sessions/ses_5nWq/access-sample
Authorization: Bearer esc_ct_...
Origin: http://localhost:3000
```

**Example response**

`200 OK`

```json
{
  "object": "access_sample",
  "session_id": "ses_5nWq",
  "format": "html",
  "instruction": "To confirm you can open the records we will send, open this sample and enter the code shown inside it.",
  "html": "<article data-esc-access-sample><h1>Sample record</h1><p>This sample is in the same format as the records you will receive electronically.</p><p>Your access code is <strong>418205</strong>.</p></article>"
}
```

`format` is `pdf` when any document in the session is a PDF, otherwise `html`.

**Errors**

[`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active), [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found).

## Start a verification

`POST /v1/sessions/{id}/verifications`

Key: client token.

Needed when `required_steps` contains `identity.verified` (L2 and L3) or `identity.verified:passkey` (L3). Esign Comply sends the message itself, from its own domain. The message names your organization and the document titles and states that Esign Comply is an independent record keeper. The destination comes from the session's signer object. The browser cannot change it.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `method` | string | Yes | `email_otp`, `email_link`, `sms_otp` or `passkey`. |

| Method | What happens |
|---|---|
| `email_otp` | A 6-digit code is emailed to `signer.email`. |
| `email_link` | A link is emailed to `signer.email`. Opening it confirms the verification. The page that waits can poll the session until `identity.verified` leaves `remaining_steps`. |
| `sms_otp` | A 6-digit code is sent to `signer.phone`. SMS has a yearly allowance per plan. Email verification is not limited. |
| `passkey` | Starts a WebAuthn ceremony. Needs a plan with L3 and a confirmed email or phone verification earlier in the same session. |

Limits: codes are valid for 10 minutes, each verification allows 5 attempts, and a session allows 3 messages.

**Example request**

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

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

**Example response**

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

Show the masked `destination` to the signer.

> **Test mode.** Test messages are delivered only to verified addresses of your organization's members. For any other address nothing is sent, `delivered` is `false`, and the response carries the code in `code` together with a `test_note`, so automated tests can continue. The reserved address `signer+ok@test.esigncomply.com` always uses the code `000000`, and `signer+wrongcode@test.esigncomply.com` never verifies. See [Test mode](https://esigncomply.com/docs/guides/test-mode.md).

**Passkey response**

For `passkey` the response has no `destination`. It carries a `phase` and WebAuthn `options` to pass to the browser's credential API.

```json
{
  "object": "verification",
  "id": "ver_2bQd",
  "method": "passkey",
  "status": "pending",
  "phase": "authenticate",
  "options": { "challenge": "...", "rpId": "example.com", "allowCredentials": [{ "id": "..." }], "userVerification": "required" },
  "expires_at": "2026-11-21T15:13:01.000Z",
  "attempts_remaining": 5
}
```

| `phase` | Meaning |
|---|---|
| `register` | The signer has no passkey for this domain yet. `options` are credential creation options. Confirm with `attestation`, then start a new `passkey` verification to authenticate. |
| `authenticate` | `options` are credential request options. The challenge is a one-use value bound to the frozen pre-signature payload: the session, the signer's external ID, the pinned document versions and hashes, the profile version and the purpose. Confirm with `assertion`. |

**Errors**

| Code | When |
|---|---|
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | Unknown `method`, or the session has no `signer.email` or `signer.phone` to verify. `param` names the missing field. |
| [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) | The limit of 3 messages for this session has been reached. Create a new session. |
| [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) | `passkey` before an email or phone verification was confirmed in this session. |
| [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable) | `passkey` on a plan without L3, or the plan's SMS allowance is used up. |
| [`service_unavailable`](https://esigncomply.com/docs/api/errors.md#service_unavailable) | The message could not be sent. Try again, or use `email_otp`. |
| [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active), [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired) | The session has ended. |

## Confirm a verification

`POST /v1/sessions/{id}/verifications/{ver_id}/confirm`

Key: client token.

**Request fields**

Send exactly one of these.

| Field | Type | For |
|---|---|---|
| `code` | string | `email_otp` and `sms_otp`: the 6 digits the signer received. |
| `token` | string | `email_link`: the token from the link, when your page handles the link itself. |
| `attestation` | object | `passkey`, phase `register`: the WebAuthn registration response as JSON. |
| `assertion` | object | `passkey`, phase `authenticate`: the WebAuthn authentication response as JSON. |

**Example request**

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

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

**Example response**

`200 OK`

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

| `status` | Meaning |
|---|---|
| `confirmed` | Verification succeeded. Esign Comply appended an `identity.verified` event, tagged observed, with the method, the masked destination and the attempt count. The step name is `identity.verified` for a code or link and `identity.verified:passkey` for a passkey. |
| `failed` | Wrong code or a response that did not verify. The call still returns `200`. `attempts_remaining` has gone down by one. |
| `registered` | Passkey registration succeeded. The response carries `next: "start_passkey_authentication"`: start a new `passkey` verification to authenticate with the new credential. |

The event name `identity.verified` is historical. A verified channel or passkey shows that someone controlling that mailbox, phone or credential took part. It does not establish legal identity, authority or sole control.

**Errors**

| Code | When |
|---|---|
| [`verification_failed`](https://esigncomply.com/docs/api/errors.md#verification_failed) | The fifth wrong attempt: the session is cancelled and `session.cancelled` is sent with `reason: "verification_failed"`. Also returned when the code has expired (`expired: true`): send a new one. |
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#invalid_request) | None of `code`, `token`, `attestation` or `assertion` was sent for the method. |
| [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found) | Unknown verification for this session. |
| [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active) | The session has ended. |

## Complete the ceremony

`POST /v1/sessions/{id}/complete`

Key: client token. A secret key is accepted only for a `server_only` session. Send an `Idempotency-Key`.

Applies the signing act. The API records the final `signature.applied` event, runs the whole-ceremony conformance checks, writes the record durably, signs the receipt, and returns both.

**Request fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `signature.method` | string | No | `click`, `checkbox`, `typed`, `drawn` or `passkey`. Defaults to the control recorded with `intent.captured`, then to the profile's method. |
| `signature.label_text` | string | No | Exact label of the assent control. Defaults to the recorded intent. |
| `signature.button_text` | string | No | Exact text of the action button. Defaults to the recorded intent or notice. |
| `signature.typed_name` | string | For typed-name signatures | The name the signer typed, when it was not already recorded with `intent.captured`. |
| `client_time` | string | No | The browser's clock. Reported, not verified. |

**Example request**

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

{
  "signature": {
    "method": "checkbox",
    "label_text": "I agree to the Terms of Service and Privacy Notice",
    "button_text": "Create account"
  },
  "client_time": "2026-11-21T10:03:20.004-05:00"
}
```

**Example response**

`201 Created`

```json
{
  "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", "email": "dana@example.org", "name": "Dana Whitfield" },
  "documents": [
    { "version_id": "dv_3kT9", "content_hash": "sha256:9f2c..." },
    { "version_id": "dv_Lm02", "content_hash": "sha256:c01e..." }
  ],
  "record_hash": "sha256:5be7...",
  "receipt": "eyJhbGciOiJFUzI1NiIs...",
  "verify_url": "https://esigncomply.com/verify/rec_Z4m8",
  "seal": { "ledger_seq": 18244, "timestamp": "pending", "anchor": "pending" },
  "guidance_release": "2026.11.3",
  "advisories": [],
  "quota_locked": false
}
```

| Field | Description |
|---|---|
| `status` | `recorded` when the receipt is signed. `pending_seal` in the rare case the signing key service could not be reached: the record is committed, `receipt` is null, and the receipt is signed within 60 seconds. |
| `signed_at` | Esign Comply's server receipt time of the final event. It is not an independently verified act time. |
| `signature_level` | `simple` for L1 to L3 signing. `not_applicable` where signing intent is not evidenced, for example a privacy-notice acknowledgment. |
| `receipt` | Compact signed token (JWS, ES256). Store it next to your own acceptance row. |
| `seal` | The external timestamp and the public anchor follow asynchronously. Watch `record.timestamped` and `record.anchored`, or read the record. |
| `advisories[]` | Record conditions in advise that were evaluated and not met. Never a reason to refuse sealing. |
| `quota_locked` | `true` only on a record that was locked under the earlier Starter quota rule. Records sealed now are not locked, so the value is `false`. |

**Rules**

- **Required steps.** Completion fails with `422 steps_incomplete` if any required step is absent. The error carries `missing_steps`, taken from the session's `required_steps`.
- **Durable before the response.** The record is written and the receipt is signed before the response returns, except for `pending_seal` as described above. `record.completed` fires only once the receipt exists. The external timestamp, the signed checkpoint and the public anchors complete asynchronously.
- **Do not trust this response on your server.** It is delivered to the browser. Before granting access, confirm through the `record.completed` webhook or `GET /v1/records/{id}` with a secret key: check that `status` is `recorded`, `timestamped` or `anchored`, that `livemode` is as expected, and that the signer and document versions match server-owned state. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md).
- **Quota never blocks completion** of a session that has been created.
- **Idempotent replay.** A repeat with the same `Idempotency-Key` and body returns the original record with the header `Idempotent-Replayed: true`. A second completion without the key returns `409 session_not_active` with the `record_id` of the existing record.

**Example errors**

A required step is missing:

```json
{
  "error": {
    "type": "ceremony_error",
    "code": "steps_incomplete",
    "message": "The ceremony is missing 1 required step: intent.captured.",
    "missing_steps": ["intent.captured"],
    "doc_url": "https://esigncomply.com/docs/api/errors#steps_incomplete",
    "request_id": "req_..."
  }
}
```

An enforced blocking rule failed, in live mode:

```json
{
  "error": {
    "type": "conformance_error",
    "code": "conformance_failed",
    "message": "CR-01: The checkbox control was checked when the page loaded.",
    "rule": "CR-01",
    "findings": [
      {
        "rule": "CR-01",
        "status": "block",
        "state": "enforce",
        "message": "The checkbox control was checked when the page loaded.",
        "fix": "Render every checkbox unchecked and every typed-name field empty. Never prefill or pre-check an assent control.",
        "measurement": { "control": "checkbox", "initial_state": "checked", "trusted": true },
        "maps_to": ["US-08"]
      }
    ],
    "doc_url": "https://esigncomply.com/docs/api/errors#conformance_failed",
    "request_id": "req_..."
  }
}
```

Show the message, keep the form, and do not retry automatically. Test mode never returns `conformance_failed`: it seals the record and reports every finding instead.

**Errors**

| Code | When |
|---|---|
| [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) | A required step is missing, or a typed-name signature has no typed name (`param: "signature.typed_name"`). |
| [`conformance_failed`](https://esigncomply.com/docs/api/errors.md#conformance_failed) | Live mode: an adopted blocking rule failed. `rule` names it and `findings` carry the measurement and the fix. |
| [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active) | The session is already completed (the error carries `record_id`) or cancelled. |
| [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired) | The token or the session has expired. Create a new session and attach again. |
| [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#insufficient_permission) | A secret key was used on a `direct` session. |
| [`internal_error`](https://esigncomply.com/docs/api/errors.md#internal_error), [`service_unavailable`](https://esigncomply.com/docs/api/errors.md#service_unavailable) | Retry with the same `Idempotency-Key`. Never proceed without a record. If the outcome is unknown, read `record_id` from `GET /v1/sessions/{id}` before asking the signer to act again. |

## Cancel a session

`POST /v1/sessions/{id}/cancel`

Key: secret key with `full_access` or `recording_access`, or the session's client token.

Use it for a "Decline" control (`ceremony.cancel()` in the SDK) or to end a ceremony from your server. No record is made. Cancelling an already cancelled session returns the same response. The `session.cancelled` webhook carries `cancelled_by`: `signer` for a client-token call, `customer` for a secret-key call, `system` for a verification lockout.

**Example request**

```bash
curl -X POST https://esigncomply.com/v1/sessions/ses_5nWq/cancel \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

**Example response**

`200 OK`

```json
{ "object": "session", "id": "ses_5nWq", "status": "cancelled", "livemode": false }
```

**Errors**

[`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active) when the session is already completed or expired. [`not_found`](https://esigncomply.com/docs/api/errors.md#not_found).

## Server-only sessions

Create a session with `capture_mode: "server_only"` when there is no browser channel, for example an API-to-API acceptance by an electronic agent. Your server then sends the events and the completion with the secret key.

- `client.attached` and `notice.captured` are not required steps.
- Every event, including the final act, is tagged `asserted`: Esign Comply did not observe the signer's device. The evidence report and any certificate say so.
- No IP address or user agent is kept.
- The record has `capture_mode: "server_only"`.
- [CR-01](https://esigncomply.com/docs/conformance.md#cr-01) does not block on a missing `trusted` flag: your server cannot observe a trusted user event. An `intent.captured` or consent event that reports a clear `initial_state` without `trusted` gets a Warn finding that says the control was reported by your server and not observed by Esign Comply. Reporting `initial_state: "checked"` or `trusted: false` is still a Block.

Prefer the direct browser channel wherever a person signs in a browser. It is what makes the record an independent observation.

## Related

- [Ceremony concepts](https://esigncomply.com/docs/concepts/ceremony.md): the steps and what each one captures.
- [Browser SDK](https://esigncomply.com/docs/sdk/browser.md): the methods that make these calls.
- [Records](https://esigncomply.com/docs/api/records.md): what completion produces.
- [Conformance rules](https://esigncomply.com/docs/conformance.md): every `CR-xx` check, with fixes.
