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.urlmust fall within the registered domain in live mode, otherwise403 domain_mismatch. Live mode requires it. - Pack selection.
signer.class,signer.country,signer.regionand 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 returns422 document_type_excludedwith the reason and the rule ID. - Customer-supplied context.
context.notes,context.extra,context.factsandmetadataare 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 withfact_unrecognized:<key>. Neither is an error. A wrong type for a known field or a missing required field still returns400. - 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
402quota_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
directsession,client.attachedmust be recorded before anything else. access.demonstratedneedsdisclosure.presented.econsent.givenneeds both.renewal.consent_givenneedsrenewal_terms.presented.intent.capturedneeds every step the session requires from this list:client.attached,disclosure.presented,access.demonstrated,econsent.given, eachdocument.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,timezoneand 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,
deliveredisfalse, and the response carries the code incodetogether with atest_note, so automated tests can continue. The reserved addresssigner+ok@test.esigncomply.comalways uses the code000000, andsigner+wrongcode@test.esigncomply.comnever 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_incompleteif any required step is absent. The error carriesmissing_steps, taken from the session'srequired_steps. - Durable before the response. The record is written and the receipt is signed before the response returns, except for
pending_sealas described above.record.completedfires 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.completedwebhook orGET /v1/records/{id}with a secret key: check thatstatusisrecorded,timestampedoranchored, thatlivemodeis 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-Keyand body returns the original record with the headerIdempotent-Replayed: true. A second completion without the key returns409 session_not_activewith therecord_idof 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.attachedandnotice.capturedare 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
trustedflag: your server cannot observe a trusted user event. Anintent.capturedor consent event that reports a clearinitial_statewithouttrustedgets a Warn finding that says the control was reported by your server and not observed by Esign Comply. Reportinginitial_state: "checked"ortrusted: falseis 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: the steps and what each one captures.
- Browser SDK: the methods that make these calls.
- Records: what completion produces.
- Conformance rules: every
CR-xxcheck, with fixes.