# The ceremony

> The session state machine, the ceremony steps and their order, assurance levels, signature methods, failure modes and capture modes.

Source: https://esigncomply.com/docs/concepts/ceremony

A ceremony is the ordered set of steps one signer completes for one bundle of document versions. You build the interface for each step. The browser SDK reports each step directly to Esign Comply, and the API refuses to seal a record until every step the session requires has been recorded in a valid order.

One ceremony is one session (`ses_...`). A completed session produces one record (`rec_...`), which is the unit Esign Comply seals and meters.

## Session states

| State | Entered when | Next states |
|---|---|---|
| `created` | Your server calls `POST /v1/sessions` | `in_progress`, `awaiting_verification`, `expired`, `cancelled` |
| `in_progress` | The first ceremony event arrives | `awaiting_verification`, `ready`, `expired`, `cancelled` |
| `awaiting_verification` | A code was sent, or verification is the only step left before the signing act | `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 was reached | Terminal |
| `cancelled` | Your server or the signer cancelled, or verification was locked out | Terminal |

A session lives for `expires_in` seconds: 1,800 by default, from 60 to 86,400. Calls on an expired session return [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired). Calls on a completed or cancelled session return [`session_not_active`](https://esigncomply.com/docs/api/errors.md#session_not_active). Create a new session in both cases. Sessions that expire or are cancelled are not signature events.

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

## Ceremony steps

| Step | Event type | Required when | Tag |
|---|---|---|---|
| S1 Session start | `session.created` | Always. Written by Esign Comply when your server creates the session. | Asserted |
| S2 Client attach | `client.attached` | Always, except `server_only` capture | Observed |
| S3 Electronic-records disclosure | `disclosure.presented` | Profiles with `consumer_econsent` and a consumer signer | Observed |
| S4 Access demonstration | `access.demonstrated` | Same as S3 | Observed |
| S5 Electronic-records consent | `econsent.given` | Same as S3 | Observed |
| S6 Document presentation | `document.presented` | Always, once per document version | Observed |
| S7 Notice snapshot | `notice.captured` | Always, except EU minimal capture and `server_only` capture | Observed |
| S8 Channel or credential verification | `identity.verified` | L2 and L3. Written by Esign Comply when it confirms a code or a passkey. | Observed |
| S9 Intent | `intent.captured` | Always | Observed |
| S10 Final act | `signature.applied` | Always. Written by `POST /v1/sessions/{id}/complete`. | Observed |
| S11 Copy delivery | `copy.delivered` | When a copy is sent | Observed if sent by Esign Comply, asserted otherwise |
| S12 Sealing | Record states `recorded`, `timestamped`, `anchored` | Always | Observed |

Two event names are older than the product's vocabulary. `identity.verified` records control of an email address, phone number or passkey. It does not establish legal identity. `signature.applied` records the final act. It does not turn an acknowledgment into a signature.

Viewing is recorded as measured events only: link opened, time visible, scroll depth. Esign Comply never reports that a signer "read" a document.

## Required steps

`required_steps` on the session is the authoritative list for that ceremony. The SDK and your code read it. Neither hard-codes steps.

```json
{
  "required_steps": [
    "client.attached",
    "document.presented:dv_3kT9",
    "document.presented:dv_Lm02",
    "notice.captured",
    "intent.captured",
    "signature.applied"
  ]
}
```

| Step name | Added when |
|---|---|
| `client.attached` | Direct capture |
| `document.presented:<version_id>` | Once per document version in the session |
| `notice.captured` | Unless the session runs under EU minimal capture or `server_only` |
| `identity.verified` | Assurance level L2 or L3 |
| `identity.verified:passkey` | Assurance level L3 |
| `intent.captured`, `signature.applied` | Always |
| `disclosure.presented`, `access.demonstrated`, `econsent.given` | The consumer consent flow applies. See [Consumer e-consent](https://esigncomply.com/docs/guides/consumer-econsent.md). |
| `renewal_terms.presented`, `renewal_consent.captured` | An adopted pack rule for a renewing or trial flow |
| `electronic_agreement.captured`, `sensitive_capture_consent.captured`, `acknowledgment.captured`, `review.presented` | An adopted pack rule that asks for its own control or step |

Only an adopted Block condition can add a step. A record condition in advise never adds one. See [Guidance and adoption](https://esigncomply.com/docs/guides/guidance.md).

Some event types satisfy a step with a different name:

| Event type sent | Step satisfied |
|---|---|
| `renewal.consent_given` | `renewal_consent.captured` |
| `electronic_agreement.given` | `electronic_agreement.captured` |
| `sensitive_capture.consent_given` | `sensitive_capture_consent.captured` |
| `acknowledgment.given` | `acknowledgment.captured` |

`ceremony.remainingSteps()` in the browser, and `remaining_steps` in every event response, tell you what is still outstanding. Keep the action control disabled until only `signature.applied` is left.

## Order

Events are append-only and strictly ordered by `sequence`. Each event's hash chains to the one before it. The API checks these prerequisites, counting only steps the session requires:

| Step | Must already be recorded |
|---|---|
| Any step (direct capture) | `client.attached` |
| `access.demonstrated` | `disclosure.presented` |
| `econsent.given` | `disclosure.presented`, `access.demonstrated` |
| `renewal_consent.captured` | `renewal_terms.presented` |
| `intent.captured` | `client.attached`, the consumer consent steps, every `document.presented:<version_id>`, `notice.captured`, `renewal_terms.presented` |
| A passkey verification | A confirmed email or phone verification in the same session |

An event that arrives too early returns [`step_out_of_order`](https://esigncomply.com/docs/api/errors.md#step_out_of_order) (409) with `missing_steps`. Completing while a required step is absent returns [`steps_incomplete`](https://esigncomply.com/docs/api/errors.md#steps_incomplete) (422), also with `missing_steps`.

Other events the browser may send are optional and never required on their own: `review.presented`, `language.selected`, `signer.age_attested`, `billing.confirm`, `withdrawal.submitted`. Statements such as `signer.age_attested` and `billing.confirm` are tagged asserted even though they arrive on the direct channel.

## Assurance levels

L1 to L3 are simple electronic signatures or recorded acceptances. The level says how the signer is tied to the act. It does not change what kind of signature the record holds.

| Level | Name | How the signer is tied to the act | Plans |
|---|---|---|---|
| L1 | Recorded | You assert the signer's identity from your own authenticated session. Esign Comply observes the act directly from the signer's device and sends a receipt if an email is supplied. | All |
| L2 | Verified | Esign Comply verifies control of an email address or phone number with a one-time code or link inside the ceremony, then sends the receipt to that address. See [L2 verification](https://esigncomply.com/docs/guides/l2-verification.md). | All. The Free plan verifies by email: SMS codes need a paid plan. |
| L3 | Bound | L2 plus authentication of a WebAuthn credential over a one-use challenge bound to the frozen pre-signature payload. See [L3 passkeys](https://esigncomply.com/docs/guides/l3-passkeys.md). | Unlimited and above |

No level establishes legal identity, authority or sole control. A passkey may sync or be recovered. A level your plan does not include returns [`plan_feature_unavailable`](https://esigncomply.com/docs/api/errors.md#plan_feature_unavailable).

## Signature methods

The profile's `method` sets what your interface builds.

| Method | API value | Interface you build | Notes |
|---|---|---|---|
| Button acceptance | `click` | Notice text with links directly beside a clearly labeled button | Records assent or acknowledgment |
| Checkbox plus button | `checkbox` | Unchecked checkbox with an explicit statement, then a button | Default. Used for consumer, purchase, trial and renewal contexts ([CR-09](https://esigncomply.com/docs/conformance.md#cr-09)). |
| Typed name | `typed` | Empty text field for the full legal name plus a signing button | Default for `nda` and `contract`. Never prefilled. Only the submitted name is stored, never keystrokes. |
| Drawn signature | `drawn` | Canvas capturing strokes | Stored as vector points only where drawn capture is switched on. Treated as evidence of intent, not biometric identification. |
| Passkey | `passkey` | Platform passkey prompt | Requires L3. Combined with a typed name. |

Every checkbox starts unchecked and every typed-name field starts empty ([CR-01](https://esigncomply.com/docs/conformance.md#cr-01)).

## Signature level

Each record carries `signature_level`, Esign Comply's classification of the act:

| Value | When |
|---|---|
| `simple` | An explicit signing or acceptance act at L1, L2 or L3 |
| `not_applicable` | Signing intent is not evidenced: every document is a `privacy_notice` or `policy_ack` and the profile is not a signature profile. A privacy-notice click is recorded as an acknowledgment. |

The enumeration also holds `advanced` and `qualified` for partner routes. The base product never assigns them.

A profile is a **signature profile** when its method is `typed`, `drawn` or `passkey`, or when a document in the session has type `nda`, `contract` or `order_form`. Otherwise it is an **acceptance profile**. The evidence report is titled "Electronic Signature Evidence Report" or "Electronic Acceptance Evidence Report" accordingly.

## Failure modes

What happens when Esign Comply cannot be reached at signing time:

| Mode | Behavior | Available for |
|---|---|---|
| `fail_closed` (default) | The SDK reports failure. Your interface must not treat the agreement as signed. | Every profile |
| `fail_open_deferred` | Your server stores the acceptance and submits it later through `POST /v1/records/deferred`. The record is sealed with `capture_mode: "deferred"`, every ceremony field is tagged asserted, and the evidence report says so. | `terms` acceptances at L1 only |

A deferred submission names the exact document versions that were shown (not `current`) and the time you say the act occurred. The record's `signed_at` is the time Esign Comply received your report. Your time is kept beside it as `asserted_signed_at`. A profile that is `fail_closed` refuses deferred submissions.

On a network failure or a `5xx`, show "We could not confirm whether your acceptance was recorded. Please wait while we check." Reconcile the same session before asking for another act. Never proceed without a record. See [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md).

## Capture modes

`capture_mode` on the record says how the events reached Esign Comply.

| Mode | Meaning | Tags |
|---|---|---|
| `direct` | Events came from the signer's browser session over the direct channel, as they occurred | Observed |
| `server_only` | Your server sent the events with a secret key, for a session created with `capture_mode: "server_only"`. `client.attached` and `notice.captured` are not required. | Asserted |
| `deferred` | You reported the act after it occurred, under `fail_open_deferred` | Asserted |
| `imported` | A historical acceptance you supplied. See the note below. | Asserted |

> **Planned.** `imported` records come from `POST /v1/records/import`, which is not part of the current API.

Only `direct` capture produces the independent browser observations the product is built around. Reports and certificates state the capture mode in plain words.

## EU minimal capture

A session runs under minimal capture (`minimal_capture: true`) when the profile sets `capture_mode: "eu_minimal"`, or when an `EU`, `UK` or `CH` pack applies.

- `notice.captured` is not a required step. The record points at the registered artifact instead of a live snapshot of the assent region.
- Optional presentation fields are dropped from event data before storage: markup, styles, layout, link style, viewport, user agent, time zone, screen and referrer.
- IP address and user agent are not stored, and the record has no `network` object.
- The warning `signer_region_network_mismatch` is never produced.

Refusing optional capture preserves the minimal flow: the ceremony still records the expressly submitted inputs and the necessary session data.

## More than one signer (Planned)

> **Planned.** Multi-signer documents with one combined evidence report are not part of the current API.

A session has exactly one signer. When two people sign the same document today, create one session per signer over the same document version. Each session resolves its packs for its own signer, and each produces its own record and its own signature event. Your application keeps the link between the records, for example with the same value in `metadata`.

## Purpose

`context.purpose` tells the rules what kind of act this is: `account_signup`, `one_time_purchase`, `free_trial`, `auto_renewal`, `contract_signature`, `nda`, `policy_update` or `other`. It selects method checks and, with the applied packs, renewal and payment steps. The list is open.

## Related

- [Sessions API](https://esigncomply.com/docs/api/sessions.md) for every endpoint in the ceremony.
- [Browser SDK](https://esigncomply.com/docs/sdk/browser.md) for the calls that record each step.
- [Observed and asserted](https://esigncomply.com/docs/concepts/observed-and-asserted.md) for what the tags mean.
