Skip to content

The ceremony

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

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. Calls on a completed or cancelled session return 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.

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.

{
  "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.
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.

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 (409) with missing_steps. Completing while a required step is absent returns 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. 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. 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.

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

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.

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.