# API conventions

> Base URLs, authentication, keys and permissions, idempotency, rate limits, pagination, versioning, CORS and the error envelope of the Esign Comply API.

Source: https://esigncomply.com/docs/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](https://esigncomply.com/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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/verification.md).

## Authentication

Send the credential in the `Authorization` header:

```http
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](https://esigncomply.com/docs/api/agent.md). |

A missing credential returns `401` [`missing_api_key`](https://esigncomply.com/docs/api/errors.md#missing_api_key). An unknown or revoked key returns `401` [`invalid_api_key`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#insufficient_permission).

> **Never.** Do not put a secret key in client code, in a `NEXT_PUBLIC_` or `VITE_` variable, in a repository, or in a chat with an AI tool. See [/auth.md](https://esigncomply.com/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`](https://esigncomply.com/docs/api/errors.md#domain_not_verified). See [Test mode](https://esigncomply.com/docs/guides/test-mode.md) and [Register a domain](https://esigncomply.com/docs/guides/domains.md).

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](https://esigncomply.com/docs/guides/server-confirmation.md); 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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#client_token_expired): create a new session.

## Idempotency

Every `POST` accepts an `Idempotency-Key` header of up to 255 characters.

```http
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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/agent.md) 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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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.

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/concepts/observed-and-asserted.md).

## 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](https://www.rfc-editor.org/rfc/rfc8785)). The record hash is the SHA-256 of a random 256-bit salt followed by those bytes. See [Evidence](https://esigncomply.com/docs/concepts/evidence.md).

## 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-21` to override the pinned version for one request.
- Every response carries `Esign-Comply-Version` with the version that was applied.
- An unknown version returns `400` `invalid_request` with `param` set to `Esign-Comply-Version`.
- A version that has a removal date answers with `Deprecation` and `Sunset` headers.

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](https://esigncomply.com/docs/concepts/compatibility.md).

## Tolerant input

Unknown request fields are ignored and reported in the response's `warnings[]` as `unknown_field:<path>`. They are not an error.

```json
{
  "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 `Origin` must be within the registered domain. A live browser call with no `Origin` is refused.
- In test mode the `Origin` must be `localhost`, `127.0.0.1`, the registered domain, or a preview host listed for the domain.

Anything else returns `403` [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#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:

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

```json
{
  "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](https://esigncomply.com/docs/api/errors.md). |
| `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:

```ts
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}`);
}
```
