API conventions
Base URLs, authentication, keys and permissions, idempotency, rate limits, pagination, versioning, CORS and the error envelope of the Esign Comply API.
The Esign Comply API is a JSON API over HTTPS. Your server calls it with a secret key. The signer's browser calls a small set of ceremony endpoints with a short-lived session client token. This page states the rules every endpoint follows. A machine-readable description is at /openapi.json.
Base URLs
| Region | Base URL |
|---|---|
| US | https://esigncomply.com/v1 |
| EU | https://api.eu.esigncomply.com/v1 |
A key works only against the region of its domain. The region is chosen when the domain is registered and is fixed afterwards. A request sent to the other region returns 421 region_mismatch, and the error object names the correct host.
Transport is HTTPS with TLS 1.2 or later. Request and response bodies are JSON in UTF-8. Send Content-Type: application/json on every request that has a body.
The public sealing keys are served from the site root, not under /v1: GET https://esigncomply.com/.well-known/jwks.json. See Verification and public log.
Authentication
Send the credential in the Authorization header:
GET /v1/usage HTTP/1.1
Host: esigncomply.com
Authorization: Bearer esc_test_us_...
There are three kinds of credential. There are no publishable keys.
| Credential | Format | Who holds it | What it can do |
|---|---|---|---|
| Secret API key | esc_test_us_..., esc_live_us_..., esc_test_eu_..., esc_live_eu_... |
Your server only | Everything its permission allows, for one domain and one environment |
| Session client token | esc_ct_... |
The signer's browser, in memory | The ceremony endpoints of the one session it was issued for |
| Agent token | esc_agent_... |
An AI agent working for the account owner | The account endpoints under /v1/agent, and a dashboard session at /agent-login. See the agent account API. |
A missing credential returns 401 missing_api_key. An unknown or revoked key returns 401 invalid_api_key. Sending a secret key to a browser-only endpoint, or a client token to a server-only endpoint, returns 403 insufficient_permission.
Never. Do not put a secret key in client code, in a
NEXT_PUBLIC_orVITE_variable, in a repository, or in a chat with an AI tool. See /auth.md.
Key formats
A secret key is esc_, the environment (test or live), the region (us or eu), and a random part of 24 to 64 letters and digits. The region code lets an SDK choose the host. A key is shown once, when it is created. Esign Comply stores only a prefix and a SHA-256 hash, so a lost key cannot be recovered: revoke it and create another.
Test keys work without a verified domain. Live keys work only after the domain is verified; before that they return 403 domain_not_verified. See Test mode and Register a domain.
Every object carries livemode: true for the live environment and false for test. The two environments share nothing. A test key cannot read a live record and a live key cannot read a test record.
Key permissions
Each key has one permission and is bound to one domain.
| Permission | Intended for | Can | Cannot |
|---|---|---|---|
full_access |
Administration and trusted back-office jobs | Call every endpoint | |
recording_access |
Your application server | Create and read sessions; submit deferred records; read a record's status view and receipt for server confirmation; create and read documents and versions; read profiles; create supplements and upload files; read signer status; run the jurisdiction dry run; read guidance, usage and conformance runs, and start a run | List records or read a full record; download evidence reports or evidence packages; any certificate call; create or change profiles; manage domains, keys or webhooks; adopt or roll back |
read_only |
Reporting and audit tools | Read documents, profiles, sessions, records (full view and list), evidence reports and packages, certificates and quotes, supplements, signer status, guidance, usage and conformance runs | Create or change anything |
recording_access is the default for a new key. A leaked application key cannot export stored evidence and can never incur a certificate charge.
A request the key's permission does not allow returns 403 insufficient_permission. The message names the permission and the capability that was needed.
Session client tokens
POST /v1/sessions returns client_token. It is a signed token scoped to that one session and it expires when the session does (30 minutes by default, 24 hours at most). Send only this token to the browser. It cannot read other sessions, records or account data. After expiry the API returns 401 client_token_expired: create a new session.
Idempotency
Every POST accepts an Idempotency-Key header of up to 255 characters.
POST /v1/sessions HTTP/1.1
Host: esigncomply.com
Authorization: Bearer esc_test_us_...
Content-Type: application/json
Idempotency-Key: signup-user_7c1d-1
| Case | Result |
|---|---|
| Same key, same path, same body | The original response is returned again with the header Idempotent-Replayed: true. Nothing is created twice. |
| Same key, same path, different body | 409 idempotency_conflict |
| Same key while the first request is still running | 409 idempotency_conflict with Retry-After: 1 |
First request ended in a 5xx |
The key is released. Retry with the same key. |
Keys are kept for 24 hours and are scoped to the domain, the environment, the method and the path. Use a key that names the business action, for example signup-user_7c1d-1, and change it when you intend a new action, for example a new session after the first one expired.
Responses that show a secret once, such as a new API key or webhook secret, are not stored for replay.
Request IDs
Every response carries X-Request-Id. Error bodies repeat it as request_id. Log it, and quote it when you contact support.
Rate limits
Secret-key requests are limited per key, by plan. The window is one second.
| Plan | Requests per second per key |
|---|---|
| Free | 2 |
| Starter | 10 |
| Unlimited | 50 |
| Enterprise | 100, or as contracted |
Ceremony calls from a browser are limited per session, not per key: 240 requests per minute for each session. One busy signup page cannot use up the account limit.
The agent account API is limited per agent token: 60 requests per minute for each token, and 120 per minute for each address.
Responses to authenticated requests carry these headers:
| Header | Meaning |
|---|---|
RateLimit-Limit |
Requests allowed in the window |
RateLimit-Remaining |
Requests left in the window |
RateLimit-Reset |
Seconds until the window resets |
Retry-After |
On 429 and on some 409 and 503 responses: seconds to wait before retrying |
Over the limit the API returns 429 rate_limit_exceeded. Wait for Retry-After and retry. Public catalogue reads (jurisdictions, supplement types, guidance, the log) are not counted against a key.
Test mode also has a monthly allowance of test events per plan. When it is used up, session creation returns 429 test_quota_exceeded.
Pagination
List endpoints are cursor-based.
| Parameter | Meaning |
|---|---|
limit |
Items per page, 1 to 100. Default 20. |
after |
Return items after this object ID (the next page, older items). |
before |
Return items before this object ID (the previous page). |
Send after or before, not both. Lists are ordered newest first.
{
"object": "list",
"data": [{ "object": "record", "id": "rec_Z4m8" }],
"has_more": true
}
When has_more is true, pass the id of the last item as after to get the next page. A cursor that does not exist returns 400 invalid_request with param set to after or before. A few short lists (profiles, document versions) are returned whole with has_more: false.
Timestamps
Timestamps are RFC 3339 in UTC with millisecond precision, for example 2026-11-21T15:03:20.291Z. Request fields accept any RFC 3339 timestamp with an offset.
A record keeps three kinds of time apart: the time the signer's browser reported (client_time, reported and not verified), the time Esign Comply's server received each event (server_time), and the time in the external timestamp token. See Observed and asserted.
Hashes
Hashes are SHA-256 in lower-case hexadecimal with the prefix sha256:, for example sha256:9f2c....
Canonical form
Before a record is hashed and sealed it is serialized with the JSON Canonicalization Scheme (RFC 8785). The record hash is the SHA-256 of a random 256-bit salt followed by those bytes. See Evidence.
Versioning
The path stays /v1. Breaking changes ship only under a new dated version. The current version is 2026-11-21.
- Each API key is pinned to the version that was current when the key was created.
- Send
Esign-Comply-Version: 2026-11-21to override the pinned version for one request. - Every response carries
Esign-Comply-Versionwith the version that was applied. - An unknown version returns
400invalid_requestwithparamset toEsign-Comply-Version. - A version that has a removal date answers with
DeprecationandSunsetheaders.
Additive changes ship without a new version: new endpoints, new optional request fields, new response fields, new enumeration values, new webhook event types, new entries in warnings[] and advisories[]. Write clients that ignore fields they do not know and tolerate enumeration values they do not know.
Rules, obligations, recommendations and notices are versioned separately as guidance releases. A guidance release never changes an endpoint, a schema or the meaning of an error code. The full contract is on Compatibility contract.
Tolerant input
Unknown request fields are ignored and reported in the response's warnings[] as unknown_field:<path>. They are not an error.
{
"object": "profile",
"id": "prof_signup_4f1a",
"warnings": ["unknown_field:unexpected"]
}
Structural problems still return 400 invalid_request: a body that is not valid JSON, a wrong type for a known field, or a missing required field. The error's param names the field.
Request bodies are limited to 1 MB. Publishing a document version accepts up to 4.4 MB, and a ceremony event carries at most 256 KB of data.
CORS
Browser endpoints (the session read, events, verifications, completion, cancel, the access sample and document content) answer cross-origin requests that carry a client token.
- In live mode the
Originmust be within the registered domain. A live browser call with noOriginis refused. - In test mode the
Originmust belocalhost,127.0.0.1, the registered domain, or a preview host listed for the domain.
Anything else returns 403 domain_mismatch. All other endpoints are server-only and send no CORS headers.
If your site sets a Content Security Policy, allow the API hosts:
connect-src https://esigncomply.com https://api.eu.esigncomply.com
Status codes
| Status | Meaning |
|---|---|
200 |
Success |
201 |
Created: documents, versions, profiles, sessions, events, verifications, records, supplements, certificates |
202 |
Accepted: a set certificate or a custodian request is being prepared |
400 |
The request is malformed |
401 |
No valid credential |
402 |
Quota or billing condition |
403 |
The credential is not allowed to do this |
404 |
No such object in this domain and environment |
409 |
Conflict with the current state |
421 |
The key belongs to the other region |
422 |
A ceremony or conformance rule was not met |
429 |
Rate limit or test allowance |
500, 503 |
Esign Comply error. Retry with the same idempotency key. |
Errors
Every error has the same envelope.
{
"error": {
"type": "ceremony_error",
"code": "steps_incomplete",
"message": "The ceremony is missing 2 required steps: notice.captured, intent.captured.",
"missing_steps": ["notice.captured", "intent.captured"],
"doc_url": "https://esigncomply.com/docs/api/errors#steps_incomplete",
"request_id": "req_8Yb2kQ0x"
}
}
| Field | Present | Meaning |
|---|---|---|
type |
Always | The class of error. The list is closed within an API version. |
code |
Always | The stable machine value. Listed on Errors. |
message |
Always | What happened, why, and the fix, for a person or an AI tool to read. Do not parse it. |
param |
When one request field caused the error | The field path, for example signer.email |
missing_steps |
On steps_incomplete and step_out_of_order |
Step names from the session's required_steps |
rule |
When a rule produced the error | The rule ID, for example CR-08 or US-23. It matches the rule IDs in a generated prompt. |
findings |
On conformance_failed and render_mismatch |
The conformance findings that blocked |
quote |
On certificate billing errors | The charge the request would incur |
doc_url |
Always | A link to the code on the errors page |
request_id |
Always | The same value as X-Request-Id |
Some codes add their own fields to the error object, for example host and region on region_mismatch, record_id on a second completion, or limit, period and locked_since on quota_exhausted.
Branch on type first, then on code:
type |
Typical status | What to do |
|---|---|---|
invalid_request_error |
400, 404, 421, 422 | Fix the request. Do not retry unchanged. |
authentication_error |
401 | Fix the credential, or create a new session for an expired client token. |
permission_error |
403 | Use a key with the needed permission, a verified domain, an allowed origin, or a plan that has the feature. |
conflict_error |
409 | Read the current state, then decide. Retry only when the error says so. |
ceremony_error |
422 | A required step or ceremony rule is not met. Fix the interface or the input. |
conformance_error |
422 | A blocking conformance rule failed in live mode. Fix the interface. |
quota_error |
402 | Pay to continue. On the Free plan, upgrade to a paid plan. On Starter, upgrade to Unlimited, add an event pack, or renew. Do not retry unchanged: a locked account does not unlock on its own. |
billing_error |
402 | Confirm the charge, raise the spend limit, or add a payment method. |
rate_limit_error |
429 | Wait for Retry-After. |
api_error |
500, 503 | Retry with the same Idempotency-Key, with backoff. |
New codes may be added for new conditions. Treat a code you do not know as its type.
With the server SDK, errors arrive in the error half of { data, error } and nothing throws:
import { esc } from "@/lib/esigncomply";
const { data: record, error } = await esc.records.get("rec_Z4m8");
if (error) {
if (error.type === "rate_limit_error" || error.type === "api_error") {
// Safe to retry later.
}
throw new Error(`${error.code}: ${error.message}`);
}