Skip to content

Sessions

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

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

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

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

{
  "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.
  • 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. Sessions already created still complete. See Free plan limits and 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.

Errors

Code When
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 Unknown profile, document or version in this domain and environment. param names the field, for example documents.0.document.
version_not_published A document has no published version, or none in effect yet.
domain_mismatch context.url is outside the registered domain (live) or the test allowlist (test).
domain_not_verified Live key before domain verification, or verification lapsed more than 14 days ago.
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 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 This month's test-mode allowance is used up.
jurisdiction_unknown, jurisdiction_not_enabled, signer_region_required, jurisdiction_fact_required, document_type_excluded Jurisdiction resolution refused the session.
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

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

Example response

200 OK (client-token view)

{
  "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, client_token_expired, 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 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

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

{
  "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.
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 A prerequisite step is missing. missing_steps lists it.
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 access.demonstrated with a code that does not match the sample.
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 The session is completed or cancelled.
client_token_expired The token or the session has expired. Create a new session and attach again.
insufficient_permission A secret key was used on a direct session.
domain_mismatch The Origin is outside the registered domain or the test allowlist. Live calls with no Origin are refused.
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.

Example request

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

Example response

200 OK

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

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

{ "method": "email_otp" }

Example response

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
}

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.

Passkey response

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

{
  "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 Unknown method, or the session has no signer.email or signer.phone to verify. param names the missing field.
verification_failed The limit of 3 messages for this session has been reached. Create a new session.
step_out_of_order passkey before an email or phone verification was confirmed in this session.
plan_feature_unavailable passkey on a plan without L3, or the plan's SMS allowance is used up.
service_unavailable The message could not be sent. Try again, or use email_otp.
session_not_active, 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

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

{ "code": "418205" }

Example response

200 OK

{
  "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 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 None of code, token, attestation or assertion was sent for the method.
not_found Unknown verification for this session.
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

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

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

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

{
  "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 A required step is missing, or a typed-name signature has no typed name (param: "signature.typed_name").
conformance_failed Live mode: an adopted blocking rule failed. rule names it and findings carry the measurement and the fix.
session_not_active The session is already completed (the error carries record_id) or cancelled.
client_token_expired The token or the session has expired. Create a new session and attach again.
insufficient_permission A secret key was used on a direct session.
internal_error, 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

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

Example response

200 OK

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

Errors

session_not_active when the session is already completed or expired. 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 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.