# Node SDK

> The esigncomply server package for Node.js and TypeScript, with every method, the endpoint it calls and the data-and-error convention.

Source: https://esigncomply.com/docs/sdk/node

`esigncomply` is the server SDK. It wraps the REST API for the calls your server makes: registering documents, creating sessions, confirming records, sending supplements, requesting certificates, reading guidance and verifying webhooks. It holds your secret API key, so it runs on the server only. The same package carries the [CLI](https://esigncomply.com/docs/sdk/cli.md).

```bash
npm install esigncomply
```

Node.js 20.19 or later. The package is an ES module with type declarations. It depends on `esigncomply-verify` (used by the CLI) and lists `playwright` as an optional peer dependency that only the CLI's `check` and `demo --auto` commands load.

```ts
import { EsignComply, verifyWebhookSignature, baseUrlForKey, VERSION } from "esigncomply";
import type { EscError, Result, EsignComplyOptions, RequestOptions, BinaryResponse } from "esigncomply";
```

`EsignComply` is also the default export. Every request and response type on this page (`SessionCreateParams`, `EscRecord`, `Supplement` and the rest) is exported as a type.

## Create the client

Create one client in a server-only module and import it wherever you need it.

```ts
// lib/esigncomply.ts
import "server-only";
import { EsignComply } from "esigncomply";

export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!);
```

```ts
new EsignComply(apiKey?: string, options?: EsignComplyOptions)
```

- **The key is a secret.** `apiKey` defaults to the `ESIGNCOMPLY_API_KEY` environment variable. Store it as a server environment variable. Never use a `NEXT_PUBLIC_` name, never import this module from a file marked `"use client"`, never print or commit the key. The rules are in [/auth.md](https://esigncomply.com/auth.md).
- **The constructor refuses to run in a browser.** If `window` is defined it throws an `Error`. This is the only place the SDK throws. `import "server-only"` makes a Next.js build fail earlier, when a client component imports the module.
- **The region comes from the key.** A key starting with `esc_test_us_` or `esc_live_us_` uses `https://esigncomply.com/v1`. A key starting with `esc_test_eu_` or `esc_live_eu_` uses `https://api.eu.esigncomply.com/v1`. `esc.baseUrl` returns the base URL in use.
- **Test and live are separate.** A test key reads and writes test objects only. Use the test key in development and preview, and the live key in production.
- **A missing key does not throw.** Every call then resolves with the error `missing_api_key`.

| Option | Type | Default | Description |
|---|---|---|---|
| `baseUrl` | string | Host for the key's region | API base URL including `/v1`. The `ESIGNCOMPLY_API_URL` environment variable is used when the option is not set. An empty value counts as not set. A bare origin gets `/v1` appended. |
| `apiVersion` | string | The version the key is pinned to | Sent as `Esign-Comply-Version` on every request. |
| `fetch` | function | The global `fetch` | A fetch implementation. |
| `maxRetries` | number | `2` | Retries after the first attempt. See [Retries and timeouts](#retries-and-timeouts). |
| `timeoutMs` | number | `60000` | Timeout for each attempt, in milliseconds. |

```ts
const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY, { apiVersion: "2026-11-21", maxRetries: 3, timeoutMs: 20_000 });
```

Each request carries `Authorization: Bearer <key>`, `X-Esc-Sdk: node/<version>` and `User-Agent: esigncomply-node/<version>`. `VERSION` is the SDK version string.

## Data and error

Every method resolves to `{ data, error }` and does not throw or reject. Exactly one of the two is `null`. Check `error` every time. When `error` is set, do not use `data`.

```ts
type Result<T> = { data: T; error: null } | { data: null; error: EscError };
```

```ts
const { data: record, error } = await esc.records.get("rec_Z4m8");
if (error) {
  console.error(error.code, error.message, error.request_id);
  return;
}
console.log(record.status);
```

`error` is the `error` object of the [API error envelope](https://esigncomply.com/docs/api.md), plus two fields the SDK adds (`status` and `retry_after`):

| Field | Type | Description |
|---|---|---|
| `type` | string | One of `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `ceremony_error`, `conformance_error`, `quota_error`, `billing_error`, `rate_limit_error`, `api_error`. |
| `code` | string | Stable machine value, for example `domain_mismatch`. Every API code is listed in the [error reference](https://esigncomply.com/docs/api/errors.md). |
| `message` | string | What happened, why, and the fix. |
| `status` | number | HTTP status. `0` when no response was received or the SDK raised the error itself. Always present. |
| `param` | string | The request field that caused the error, when there is exactly one. |
| `missing_steps` | string[] | On `steps_incomplete` and `step_out_of_order`. |
| `rule` | string | The rule ID behind the error, when there is one. |
| `quote` | object | On `certificate_charge_unconfirmed`: what the request would cost. |
| `findings` | array | Conformance findings behind the error. |
| `doc_url` | string | A link to the code's documentation. |
| `request_id` | string | The value of `X-Request-Id`. Quote it to support. |
| `retry_after` | number | Seconds, from the `Retry-After` header, when the API sent one. |

Any further machine-readable detail the API attached to the envelope is kept on the object as well.

Branch on `type` first and treat a `code` you do not know as its `type`. New codes for new conditions can be added without a new API version.

Enumerations in the SDK types are open strings (`Open<...>`). Statuses, warning names, event types, supplement types and pack codes can gain new values at any time, so write a default branch. See [Compatibility](https://esigncomply.com/docs/concepts/compatibility.md).

### Errors the SDK raises itself

These codes never come from the API. All have `status: 0` unless noted.

| Code | Type | When |
|---|---|---|
| `missing_api_key` | `authentication_error` | No key was passed and `ESIGNCOMPLY_API_KEY` is not set. |
| `network_error` | `api_error` | The request failed, timed out or was aborted, no fetch implementation exists, or a response body could not be read (then `status` is the HTTP status). |
| `invalid_response` | `api_error` | The API answered `2xx` with a body that is not JSON (`status` is the HTTP status), or registered a file without returning an upload URL. |
| `invalid_request` | `invalid_request_error` | The base URL is not a valid URL (`param: "baseUrl"`), or `esc.files.upload` could not read the path or was given no name (`param: "file"` or `"name"`). |
| `service_unavailable` | `api_error` | The storage service refused a file upload or an evidence download. `status` is the status storage answered. |
| `webhook_signature_missing` | `invalid_request_error` | A delivery lacks `webhook-id`, `webhook-timestamp` or `webhook-signature`. |
| `webhook_timestamp_out_of_tolerance` | `invalid_request_error` | The delivery's timestamp is further from now than the tolerance. |
| `webhook_signature_invalid` | `invalid_request_error` | No secret was passed, or no signature in the header matches. |
| `webhook_payload_invalid` | `invalid_request_error` | The body is not a string or bytes, or the signature is valid but the body is not a JSON object. |

When an error response has no JSON envelope (for example from a proxy), the SDK builds the error from the status: `400` and `422` give `invalid_request`, `401` `invalid_api_key`, `402` `quota_exceeded`, `403` `insufficient_permission`, `404` `not_found`, `409` `idempotency_conflict`, `421` `region_mismatch`, `429` `rate_limit_exceeded`, `503` `service_unavailable` and any other `5xx` `internal_error`.

## Request options

Methods that create or change something take a last argument `options`:

| Option | Description |
|---|---|
| `idempotencyKey` | Sent as `Idempotency-Key`. The SDK sends it on `POST` requests only. |
| `apiVersion` | Overrides `Esign-Comply-Version` for this call. |
| `signal` | An `AbortSignal` that cancels the call. |

```ts
const { data: session, error } = await esc.sessions.create(body, { idempotencyKey: `signup-${signerId}` });
```

A repeat with the same key and the same body returns the original response and records nothing twice. The same key with a different body returns [`idempotency_conflict`](https://esigncomply.com/docs/api/errors.md#idempotency_conflict). Build the key from your own stable identifiers, not from a timestamp.

The methods with an `options` argument are marked `options?` in the tables below. Read methods, `esc.certificates.quote`, `esc.jurisdictions.resolve`, `esc.domains.verify`, `esc.files.upload` and the `PATCH`, `PUT` and `DELETE` methods take none.

### Retries and timeouts {#retries-and-timeouts}

The SDK repeats a call only when repeating it cannot act twice.

- A call is repeatable when it is a `GET`, or a `POST` that carries an `idempotencyKey`.
- A network failure or a timeout is retried for repeatable calls, unless your own `signal` aborted the call.
- A `429` answer is retried for every call. A `5xx` answer is retried for repeatable calls only.
- The wait is the `Retry-After` value when the API sent one, otherwise 500 ms doubling per attempt up to 8 seconds, with jitter. If `Retry-After` asks for more than 60 seconds, the SDK returns the error instead of waiting.
- At most `maxRetries` retries follow the first attempt (default 2). Each attempt has its own `timeoutMs` (default 60 seconds).

A `POST` without an idempotency key is therefore not retried after a network failure or a `5xx`. Pass a key on every call that must not be lost, then retry with the same key yourself if the final answer is still an error.

## Reading the reference tables

In each table the first column is the method with its real argument list, the second is the endpoint it calls, and the third is a one-line call. Every call resolves to `{ data, error }`: destructure it and check `error` as in the snippet under the table. `options?` is the [request options](#request-options) object. List methods resolve `data` to `{ object: "list", data, has_more }` and take `limit` (1 to 100, default 20), `after` and `before` where the table shows `params?` or `filters?`.

## Documents

| Method | Endpoint | Example |
|---|---|---|
| `esc.documents.create(body, options?)` | `POST /v1/documents` | `esc.documents.create({ name: "Terms of Service", type: "terms" })` |
| `esc.documents.list(params?)` | `GET /v1/documents` | `esc.documents.list({ type: "terms", limit: 50 })` |
| `esc.documents.get(id)` | `GET /v1/documents/{id}` | `esc.documents.get("doc_8Hq2")` |
| `esc.documents.versions.create(documentId, body, options?)` | `POST /v1/documents/{id}/versions` | `esc.documents.versions.create("doc_8Hq2", version)` |
| `esc.documents.versions.list(documentId)` | `GET /v1/documents/{id}/versions` | `esc.documents.versions.list("doc_8Hq2")` |
| `esc.documents.versions.get(documentId, versionId)` | `GET /v1/documents/{id}/versions/{version_id}` | `esc.documents.versions.get("doc_8Hq2", "dv_3kT9")` |
| `esc.documents.versions.getContent(documentId, versionId, params?)` | `GET /v1/documents/{id}/versions/{version_id}/content` | `esc.documents.versions.getContent("doc_8Hq2", "current", { locale: "en" })` |

- `documents.create` body: `name`, `type` (`terms`, `privacy_notice`, `nda`, `contract`, `consent`, `policy_ack`, `custom`), optional `metadata`. `documents.list` filters by `type`.
- `versions.create` body: `version_label`, `content`, and optionally `language`, `effective_at`, `material_change`, `summary_of_changes`. `content` is `{ format: "markdown" | "html" | "text", text }` or `{ format: "pdf", data_base64 }`.
- `versionId` is a version ID or `"current"`. `getContent` takes `{ locale }` to pick a translation when `"current"` is used. It resolves to the stored `text`, the sanitized `html`, or `data_base64` for a PDF, with `content_hash` and `render_hash`.

```ts
const { data: version, error } = await esc.documents.versions.create(
  "doc_8Hq2",
  {
    version_label: "2026-11-21",
    language: "en",
    content: { format: "markdown", text: "# Terms of Service\n..." },
    material_change: true,
    summary_of_changes: "Added arbitration clause in section 14.",
  },
  { idempotencyKey: "tos-2026-11-21-en" },
);
if (error) throw new Error(`${error.code}: ${error.message}`);
console.log(version.id, version.content_hash);
```

A published version is immutable. Fields and responses are in the [documents API](https://esigncomply.com/docs/api/documents.md).

## Profiles

| Method | Endpoint | Example |
|---|---|---|
| `esc.profiles.create(body, options?)` | `POST /v1/profiles` | `esc.profiles.create({ name: "Signup", jurisdictions: ["US-FED"] })` |
| `esc.profiles.list()` | `GET /v1/profiles` | `esc.profiles.list()` |
| `esc.profiles.get(id)` | `GET /v1/profiles/{id}` | `esc.profiles.get("prof_signup_4f1a")` |
| `esc.profiles.guidance(id)` | `GET /v1/profiles/{id}/guidance` | `esc.profiles.guidance("prof_signup_4f1a")` |
| `esc.profiles.adopt(id, body?, options?)` | `POST /v1/profiles/{id}/adopt` | `esc.profiles.adopt("prof_signup_4f1a", { note: "Reviewed update upd_7c1e." })` |
| `esc.profiles.rollback(id, options?)` | `POST /v1/profiles/{id}/rollback` | `esc.profiles.rollback("prof_signup_4f1a")` |

- `profiles.create` body: `name`, and optionally `jurisdictions`, `jurisdiction_mode`, `on_unknown_region`, `governing_law`, `allow_session_packs`, `strict_jurisdictions`, `pack_versions`, `signer_class`, `document_type`, `purpose`, `method`, `assurance_level`, `failure_mode`, `consumer_econsent`, `capture_mode`, `receipts_enabled`, `signer_certificates_enabled`, `change_note`.
- `profiles.guidance` resolves to `{ record_conditions, obligations, recommendations, reports }`: everything that applies to the profile now.
- `profiles.adopt` moves every pending record condition from advise to enforce and writes a new profile version. Body: `note` (optional, up to 500 characters). Adoption covers every pending condition: there is no list of rules to pass. It resolves to the profile at its new version, plus `adopted` and `baseline_detail`. `profiles.rollback` returns to the previous baseline, within 90 days of an adoption.
- The SDK has no method for updating a profile. Use `esc.request("POST", "/profiles/prof_signup_4f1a", { body })`: see [Any other endpoint](#any-other-endpoint).

```ts
const { data: profile, error } = await esc.profiles.create({
  name: "Signup",
  jurisdictions: ["US-FED", "US-CA", "US-NY"],
  jurisdiction_mode: "auto",
  on_unknown_region: "strictest",
});
if (error) throw new Error(`${error.code}: ${error.message}`);
```

See the [profiles API](https://esigncomply.com/docs/api/profiles.md) and [Guidance](https://esigncomply.com/docs/guides/guidance.md).

## Jurisdictions

| Method | Endpoint | Example |
|---|---|---|
| `esc.jurisdictions.list(params?)` | `GET /v1/jurisdictions` | `esc.jurisdictions.list({ limit: 100 })` |
| `esc.jurisdictions.get(code)` | `GET /v1/jurisdictions/{code}` | `esc.jurisdictions.get("US-CA")` |
| `esc.jurisdictions.versions(code)` | `GET /v1/jurisdictions/{code}/versions` | `esc.jurisdictions.versions("US-CA")` |
| `esc.jurisdictions.resolve(body)` | `POST /v1/jurisdictions/resolve` | `esc.jurisdictions.resolve({ profile: "prof_signup_4f1a", signer: { region: "US-CA" } })` |

`resolve` body: `profile`, and optionally `signer`, `jurisdictions` (`mode`, `packs`, `governing_law`), `documents`, `context` and `baseline` (`"current"` or `"latest"`).

```ts
// Dry run: which packs, rules, steps and strings would apply. Creates nothing and is not metered.
const { data: resolution, error } = await esc.jurisdictions.resolve({
  profile: "prof_signup_4f1a",
  signer: { class: "consumer", country: "US", region: "US-CA" },
  documents: [{ document: "doc_8Hq2", version: "current" }],
  context: { purpose: "account_signup" },
});
if (error) throw new Error(`${error.code}: ${error.message}`);
console.log(resolution.applied_jurisdictions, resolution.required_steps);
```

Read the catalogue from the API. Do not hard-code pack codes. See [Jurisdictions](https://esigncomply.com/docs/guides/jurisdictions.md).

## Sessions

| Method | Endpoint | Example |
|---|---|---|
| `esc.sessions.create(body, options?)` | `POST /v1/sessions` | `esc.sessions.create(body, { idempotencyKey })` |
| `esc.sessions.get(id)` | `GET /v1/sessions/{id}` | `esc.sessions.get("ses_5nWq")` |
| `esc.sessions.cancel(id, options?)` | `POST /v1/sessions/{id}/cancel` | `esc.sessions.cancel("ses_5nWq")` |

`sessions.create` body: `profile`, `signer` (`external_id` required; `email`, `name`, `phone`, `class`, `country`, `region`, `locality`, `actor_type`, `operator`, `authority_reference` optional), `documents` (1 to 10 of `{ document, version? }`), and optionally `jurisdictions`, `context` (`url`, `locale`, `purpose`, `facts`, `notes`, `extra`), `metadata`, `expires_in` (60 to 86,400 seconds) and `capture_mode` (`"direct"` or `"server_only"`).

```ts
const { data: session, error } = await esc.sessions.create(
  {
    profile: "prof_signup_4f1a",
    signer: { external_id: signerId, email, class: "consumer", country: "US", region: "US-CA" },
    documents: [
      { document: "doc_8Hq2", version: "current" },
      { document: "doc_Pv71", version: "current" },
    ],
    context: { url: `${origin}/signup`, locale: "en-US", purpose: "account_signup" },
  },
  { idempotencyKey: `signup-${signerId}` },
);
if (error) throw new Error(error.message);

// Send only these to the browser. Never the key, never the whole session.
return { clientToken: session.client_token, apiUrl: session.api_url, documents: session.documents };
```

`sessions.create` resolves to the session with `client_token` and `api_url`. `sessions.get` resolves to the session with `completed_steps`, `remaining_steps` and `record_id`, which is set once the ceremony completed. Read `required_steps`, `applied_jurisdictions`, `required_strings` and `warnings` from the response: see the [sessions API](https://esigncomply.com/docs/api/sessions.md).

The ceremony steps themselves (events, verifications, completion) are sent by the [browser SDK](https://esigncomply.com/docs/sdk/browser.md) with the client token. The server SDK has no named methods for them. A server that reports the steps of a `server_only` session calls those endpoints through [`esc.request`](#any-other-endpoint), and every event is then tagged `asserted`.

## Records

| Method | Endpoint | Example |
|---|---|---|
| `esc.records.list(filters?)` | `GET /v1/records` | `esc.records.list({ signer_external_id: "user_7c1d" })` |
| `esc.records.get(id)` | `GET /v1/records/{id}` | `esc.records.get("rec_Z4m8")` |
| `esc.records.report(id)` | `GET /v1/records/{id}/report` | `esc.records.report("rec_Z4m8")` |
| `esc.records.evidence(id, options?)` | `GET /v1/records/{id}/evidence` | `esc.records.evidence("rec_Z4m8", { inline: true })` |
| `esc.records.receipt(id)` | `GET /v1/records/{id}/receipt` | `esc.records.receipt("rec_Z4m8")` |
| `esc.records.annotate(id, body, options?)` | `POST /v1/records/{id}/annotations` | `esc.records.annotate("rec_Z4m8", { type: "legal_hold", data: { matter: "2026-0412" } })` |
| `esc.records.certify(id, body?, options?)` | `POST /v1/records/{id}/certificates` | `esc.records.certify("rec_Z4m8", { confirm_charge: true })` |
| `esc.records.submitDeferred(body, options?)` | `POST /v1/records/deferred` | `esc.records.submitDeferred(deferred, { idempotencyKey })` |

- `list` filters: `signer_external_id`, `email`, `document_id`, `version_id`, `created_after`, `created_before`, `status`, plus the list parameters.
- `report` resolves to a `BinaryResponse` with the evidence report PDF: `{ bytes, contentType, filename? }`.
- `evidence` options: `inline` and `supplements`. Without `inline` it resolves to a download link: `{ object: "evidence_package", record_id, url, expires_in, size, files, format }`. With `{ inline: true }` it resolves to a `BinaryResponse` with the ZIP archive. When the archive is too large to travel inline, the SDK follows the link and still returns the bytes. `{ supplements: false }` leaves out the customer-supplied folder. This option object is not the request options object.
- `receipt` resolves to `{ object: "receipt", record_id, receipt, kid, payload }`. `receipt` is the compact JWS.
- `annotate` body: `{ type, data?, note? }` with `type` one of `superseded`, `legal_hold`, `legal_hold_released`, `note`, `paper_copy_requested`. `note` is free text, up to 4,000 characters, stored as `data.note`. The earlier report types `notice.sent` and `cancellation.requested` are still accepted and are stored as supplements. New code sends those to `esc.supplements.create`.
- `certify` body: `type`, `wording`, `reference`, `include`, `share`, `confirm_charge`, `reissue_of`, all optional. With `share: { expires_in }` the certificate in the response carries the new link as `share: { id, url, expires_at, opens, last_opened_at }`. `share.url` holds the access secret after `#` and is returned only in this response; `share_url` and `share_expires_at` repeat `share.url` and `share.expires_at`. `seal.ledger` is the certificate's full ledger entry, which the [offline verifier](https://esigncomply.com/docs/sdk/verify.md) recomputes.
- `submitDeferred` is for profiles with `failure_mode: "fail_open_deferred"`: a signing act your own system captured while Esign Comply was unreachable. The record says the acceptance was reported, not observed. Body: `profile`, `signer` (`external_id`, and optionally `email`, `name`, `class`, `country`, `region`), `documents` (each `{ document, version }` with an exact version ID, not `"current"`), `signed_at`, `signature` (`method`, and optionally `label_text`, `button_text`), and optionally `context` (`url`, `locale`, `purpose`, `notes`), `reason` and `metadata`.

```ts
// Server confirmation: the only place access is granted.
const { data: record, error } = await esc.records.get(recordId);
const confirmed =
  !error &&
  ["recorded", "timestamped", "anchored"].includes(record.status) &&
  record.signer.external_id === expectedSignerId &&
  record.livemode === (process.env.VERCEL_ENV === "production");
```

```ts
import { writeFile } from "node:fs/promises";

const { data: pkg, error } = await esc.records.evidence("rec_Z4m8", { inline: true });
if (error) throw new Error(`${error.code}: ${error.message}`);
await writeFile(pkg.filename ?? "rec_Z4m8.zip", pkg.bytes);
```

Compare the record's document versions with the versions your server pinned for that session as well: the full check is in [Server confirmation](https://esigncomply.com/docs/guides/server-confirmation.md). A key with `recording_access` gets the status fields of a record, which is what confirmation needs. Evidence reports and packages need `full_access` or `read_only`. See the [records API](https://esigncomply.com/docs/api/records.md) and the [offline verifier](https://esigncomply.com/docs/sdk/verify.md).

## Certificates

| Method | Endpoint | Example |
|---|---|---|
| `esc.certificates.quote(body)` | `POST /v1/certificates/quote` | `esc.certificates.quote({ type: "contemporaneous_record", record_id: "rec_Z4m8" })` |
| `esc.certificates.create(body, options?)` | `POST /v1/certificates` | `esc.certificates.create({ type: "contemporaneous_record_set", filter, confirm_charge: true })` |
| `esc.certificates.list(filters?)` | `GET /v1/certificates` | `esc.certificates.list({ record_id: "rec_Z4m8" })` |
| `esc.certificates.get(id)` | `GET /v1/certificates/{id}` | `esc.certificates.get("crt_7Hd2")` |
| `esc.certificates.pdf(id)` | `GET /v1/certificates/{id}/pdf` | `esc.certificates.pdf("crt_7Hd2")` |
| `esc.certificates.share(id, body, options?)` | `POST /v1/certificates/{id}/share` | `esc.certificates.share("crt_7Hd2", { expires_in: 2592000 })` |
| `esc.certificates.revokeShare(id)` | `DELETE /v1/certificates/{id}/share` | `esc.certificates.revokeShare("crt_7Hd2")` |

- `create` issues one certificate over a set of records. Body: `type` and `filter` (`record_ids`, `signer_external_id`, `document_id`, `version_id`, `created_after`, `created_before`), plus the same optional fields as `records.certify`. It is asynchronous: the answer has `status: "processing"` and the `certificate.issued` webhook follows.
- `quote` takes the body of either request, with `record_id` for a single record. It issues nothing and charges nothing.
- `list` filters: `record_id`, `type`, `status`, `created_after`, `created_before`.
- `pdf` resolves to a `BinaryResponse`. `share` takes `expires_in` in seconds (90 days at most) and resolves to `{ object: "certificate_share", certificate_id, id, share_url, share_expires_at }`.

```ts
const request = { type: "contemporaneous_record", wording: "auto", reference: "Matter 2026-0412" };

// 1. Quote. Issues nothing and charges nothing.
const quoted = await esc.certificates.quote({ ...request, record_id: "rec_Z4m8" });
if (quoted.error) throw new Error(quoted.error.message);

// 2. Show quoted.data.amount to an administrator. Only after they confirm:
const { data: certificate, error } = await esc.records.certify("rec_Z4m8", { ...request, confirm_charge: true });
if (error) throw new Error(`${error.code}: ${error.message}`);
```

> **Never.** Do not build a certificate request that can run without a person confirming the charge. Without `confirm_charge: true` a request that would incur a charge returns [`certificate_charge_unconfirmed`](https://esigncomply.com/docs/api/errors.md#certificate_charge_unconfirmed) with a `quote` on the error and issues nothing.

See [Certificates](https://esigncomply.com/docs/guides/certificates.md) and the [certificates API](https://esigncomply.com/docs/api/certificates.md).

## Supplements and files

| Method | Endpoint | Example |
|---|---|---|
| `esc.supplements.create(body, options?)` | `POST /v1/supplements` | `esc.supplements.create({ subject: { record: "rec_Z4m8" }, type: "note", text: "Called the customer." })` |
| `esc.supplements.list(filters?)` | `GET /v1/supplements` | `esc.supplements.list({ subject: { record: "rec_Z4m8" } })` |
| `esc.supplements.get(id)` | `GET /v1/supplements/{id}` | `esc.supplements.get("sup_5Hc1")` |
| `esc.supplements.content(id)` | `GET /v1/supplements/{id}/content` | `esc.supplements.content("sup_5Hc1")` |
| `esc.supplements.withdraw(id)` | `DELETE /v1/supplements/{id}` | `esc.supplements.withdraw("sup_5Hc1")` |
| `esc.supplements.types()` | `GET /v1/supplement-types` | `esc.supplements.types()` |
| `esc.files.upload(pathOrBytes, options?)` | `POST /v1/files`, `PUT` to the upload URL, `GET /v1/files/{id}` | `esc.files.upload("./renewal-notice.eml", { contentType: "message/rfc822" })` |
| `esc.files.get(id)` | `GET /v1/files/{id}` | `esc.files.get("fil_9Qe2")` |

- `supplements.create` body: at least one of `text`, `data` or `files`. Optional: `subject` (exactly one of `record`, `session`, `signer`, `document_version`, `domain`; omit it to attach the supplement to the domain), `type`, `occurred_at`, `rule_ids`, `labels`, `supersedes`.
- `supplements.list` filters: `subject`, `type`, `rule_id`, `label`, `received_after`, `received_before`. Pass `subject` as an object with one key, as a bare ID string, or as `"domain"`. The SDK sends the ID.
- `supplements.content` resolves to `{ text, data, files }` as stored. `withdraw` marks the supplement withdrawn. It stays listed.
- `files.upload` takes a file path or the bytes (`Uint8Array` or `Buffer`). Its second argument is `{ name?, contentType? }`, not the request options object. `name` defaults to the base name of the path and is required for bytes. `contentType` defaults to `application/octet-stream`.

```ts
const uploaded = await esc.files.upload("./renewal-notice.eml", { contentType: "message/rfc822" });
if (uploaded.error) console.error("File not uploaded", uploaded.error.code);

const { data: supplement, error } = await esc.supplements.create(
  {
    subject: { record: "rec_Z4m8" },
    type: "notice.sent",
    occurred_at: "2027-01-04T15:02:11.000Z",
    rule_ids: ["NY-05"],
    text: "Annual renewal reminder emailed to the address on the account. Template v7.",
    data: { channel: "email", template: "renewal-v7" },
    files: uploaded.data ? [uploaded.data.id] : [],
  },
  { idempotencyKey: "renewal-notice-user_7c1d-2027-01" },
);
if (error) console.error("Supplement not filed", error.code); // never block the user's action on this
```

`esc.files.upload` performs the upload steps for you. It registers the file with its name, size, content type and SHA-256 hash, sends the bytes with `PUT` to the returned upload URL without the API key, then reads the file back so `status` reflects what the API saw. A file not referenced by a supplement within 7 days is deleted.

A supplement is the customer's own statement. Esign Comply seals it with its receipt time and does not verify its contents. See [Supplements](https://esigncomply.com/docs/guides/supplements.md) and the [supplements API](https://esigncomply.com/docs/api/supplements.md).

## Guidance

| Method | Endpoint | Example |
|---|---|---|
| `esc.guidance.notices.list(filters?)` | `GET /v1/guidance/notices` | `esc.guidance.notices.list({ severity: "action_required" })` |
| `esc.guidance.notices.get(id)` | `GET /v1/guidance/notices/{id}` | `esc.guidance.notices.get("ntc_2026_0931")` |
| `esc.guidance.notices.acknowledge(id, body, options?)` | `POST /v1/guidance/notices/{id}/acknowledge` | `esc.guidance.notices.acknowledge("ntc_2026_0931", { state: "read" })` |
| `esc.guidance.releases.list(params?)` | `GET /v1/guidance/releases` | `esc.guidance.releases.list({ limit: 10 })` |
| `esc.guidance.releases.get(id)` | `GET /v1/guidance/releases/{id}` | `esc.guidance.releases.get(releaseId)` |
| `esc.guidance.updates.get(id)` | `GET /v1/guidance/updates/{id}` | `esc.guidance.updates.get("upd_7c1e")` |

- `notices.list` filters: `jurisdiction`, `class`, `severity`, `kind`, `topic`, `since`, `affecting_profile`.
- `notices.acknowledge` body: `state` (`read`, `applied` or `not_applicable`) and an optional `note`.
- `updates.get` resolves to an object with the update prompt in `markdown`. The SDK accepts the endpoint's JSON form and its Markdown form.

```ts
const { data: notices, error } = await esc.guidance.notices.list({ since: "2026-11-21T00:00:00.000Z", severity: "action_required" });
if (error) throw new Error(`${error.code}: ${error.message}`);
for (const notice of notices.data) console.log(notice.id, notice.title, notice.what_changes.your_obligations);
```

Reading or acknowledging a notice never changes how your integration records. See [Guidance](https://esigncomply.com/docs/guides/guidance.md) and the [guidance API](https://esigncomply.com/docs/api/guidance.md).

## Signers

| Method | Endpoint | Example |
|---|---|---|
| `esc.signers.records(externalId, params?)` | `GET /v1/signers/{external_id}/records` | `esc.signers.records("user_7c1d", { limit: 50 })` |
| `esc.signers.status(externalId)` | `GET /v1/signers/{external_id}/status` | `esc.signers.status("user_7c1d")` |
| `esc.signers.withdrawConsent(externalId, body?, options?)` | `POST /v1/signers/{external_id}/consents/withdraw` | `esc.signers.withdrawConsent("user_7c1d", { note: "Requested by phone." })` |
| `esc.signers.requestErasure(externalId, body?, options?)` | `POST /v1/signers/{external_id}/erasure-requests` | `esc.signers.requestErasure("user_7c1d", { scope: "erasure" })` |

`externalId` is your own identifier for the signer, the value you sent as `signer.external_id`. The SDK percent-encodes it. `status` resolves to `{ object: "signer_status", signer, documents, outstanding }`. Each entry of `documents` has `document_id`, `name`, `type`, `current_version`, `accepted_version`, `outstanding`, `reason` and `summary_of_changes`. The top-level `outstanding` lists the documents that still have to be accepted.

`withdrawConsent` body (`ConsentWithdrawParams`): `record_id`, `scope` and `note`, all optional. It resolves to `{ object: "consent_withdrawal", signer, record_id, annotation_id, recorded_at }`. `requestErasure` body (`ErasureRequestParams`): `scope` (`"erasure"`, the default, or `"restriction"`) and `basis`, both optional. It resolves to `{ object: "erasure_request", id, signer, scope, status }` with `status` one of `completed`, `blocked_by_hold` or `rejected`, plus `erased`, `restricted` or `reason` as the outcome requires. See the [signers API](https://esigncomply.com/docs/api/signers.md).

```ts
// Gate: is any current document version outstanding for this signer?
const { data: status, error } = await esc.signers.status(signerId);
if (error) throw new Error(`${error.code}: ${error.message}`);
const mustAccept = status.documents.some((d) => d.outstanding);
```

See [Re-acceptance](https://esigncomply.com/docs/guides/reacceptance.md) and the [signers API](https://esigncomply.com/docs/api/signers.md).

## Webhooks

| Method | Endpoint | Example |
|---|---|---|
| `esc.webhooks.verify(rawBody, headers, secret, options?)` | None. Local check. | `esc.webhooks.verify(rawBody, request.headers, secret)` |
| `esc.webhooks.create(body, options?)` | `POST /v1/webhooks` | `esc.webhooks.create({ url: "https://example.com/api/esigncomply/webhook", events: ["record.completed"] })` |
| `esc.webhooks.list()` | `GET /v1/webhooks` | `esc.webhooks.list()` |
| `esc.webhooks.update(id, body)` | `PATCH /v1/webhooks/{id}` | `esc.webhooks.update("wh_6Tn3", { status: "disabled" })` |
| `esc.webhooks.delete(id)` | `DELETE /v1/webhooks/{id}` | `esc.webhooks.delete("wh_6Tn3")` |
| `esc.webhooks.listDeliveries(params?)` | `GET /v1/webhooks/deliveries` | `esc.webhooks.listDeliveries({ since: "2026-11-21T15:00:00.000Z", include: "payload" })` |

- `create` body: `url`, and optionally `events` (omit for all) and `description`. The response carries the signing `secret` (`whsec_...`) once. `update` body: `url`, `events`, `description`, `status` (`"enabled"` or `"disabled"`).
- `listDeliveries` takes `since`, `limit`, `include`, `endpoint` and `status`. It resolves to the delivery history with response codes: `id`, `endpoint_id`, `webhook_id` (the event ID, the value of the `webhook-id` header), `type`, `status`, `attempts`, `response_status`, `response_excerpt`, `created_at`, `delivered_at`, `last_attempt_at`. With `since` the list holds deliveries created after that time, oldest first. `include: "payload"` adds each event as `payload`. The CLI's `webhooks listen` command uses it.

### Verify a delivery

```ts
esc.webhooks.verify<T>(rawBody: string | Uint8Array, headers: HeadersLike, secret: string, options?: WebhookVerifyOptions): Promise<Result<WebhookEvent<T>>>
```

`verify` checks the signature and the timestamp of a delivery and resolves to the parsed event: `{ object: "event", id, type, api_version, livemode, created_at, data }`. It makes no network call.

```ts
// app/api/esigncomply/webhook/route.ts
import { esc } from "@/lib/esigncomply";

export const runtime = "nodejs";

export async function POST(request: Request) {
  const rawBody = await request.text(); // the raw body, before any JSON parsing
  const { data: event, error } = await esc.webhooks.verify(rawBody, request.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!);
  if (error) return new Response(error.code, { status: 400 });

  // Deliveries are at-least-once: handle each event.id once. It equals the webhook-id header.
  switch (event.type) {
    case "record.completed":
      // upsert your acceptance row for event.data.record_id
      break;
    default:
      break; // ignore event types you do not recognize
  }
  return new Response(null, { status: 200 });
}
```

- `rawBody` is the body exactly as received, as a string or bytes. A parsed object is refused with `webhook_payload_invalid`, because the signature covers the bytes.
- `headers` is a fetch `Headers` object or a plain record such as Node's `req.headers`. The check reads `webhook-id`, `webhook-timestamp` and `webhook-signature`.
- `secret` is the endpoint's `whsec_...` value.
- `options.toleranceSeconds` (default `300`) is how far the delivery's timestamp may be from now. `options.now` replaces the clock.
- The signature is HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>`. The header may carry several `v1,` signatures while a secret is rotated. One match is enough.

The four error codes are listed under [Errors the SDK raises itself](#errors-the-sdk-raises-itself). The exported function `verifyWebhookSignature(rawBody, headers, secret, options?)` is the same check without the promise: it returns the `{ data, error }` result synchronously.

```ts
import { verifyWebhookSignature } from "esigncomply";

const { data: event, error } = verifyWebhookSignature(rawBody, req.headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!);
```

Event types, payloads and the signature scheme are in [Webhooks](https://esigncomply.com/docs/api/webhooks.md).

## Usage and verification

| Method | Endpoint | Example |
|---|---|---|
| `esc.usage.get()` | `GET /v1/usage` | `esc.usage.get()` |
| `esc.verify(receiptOrIdOrHash)` | `POST /v1/verify` | `esc.verify(storedReceipt)` |

```ts
// Also the simplest way to check that a key works.
const { data: usage, error } = await esc.usage.get();
if (error) throw new Error(`${error.code}: ${error.message}`);

// Proof status for a signed receipt you stored.
const checked = await esc.verify(storedReceipt);
if (checked.error) throw new Error(checked.error.message);
console.log(checked.data.valid, checked.data.checks);
```

`esc.verify` takes one string and chooses the request field from its shape: a value with three dot-separated parts is sent as `receipt`, a value starting with `sha256:` (or 64 hexadecimal digits alone) as `record_hash`, and anything else as `record_id`. Anyone holding the full signed receipt may ask. A record ID or a record hash is answered only for a record in the domain and environment of your secret key; for any other record the answer is `valid: false` with `reason: "not_verifiable"`. See the [verification API](https://esigncomply.com/docs/api/verification.md). The result is `{ object: "verification_result", valid, reason?, livemode?, attestation?, status?, checks?, checked_at?, note? }`.

`esc.verify` reports whether the record matches its seal. It does not establish who signed or whether any agreement is valid or enforceable. For a check that does not involve Esign Comply's servers, use the [offline verifier](https://esigncomply.com/docs/sdk/verify.md).

## Conformance, prompts, domains and API keys

| Method | Endpoint | Example |
|---|---|---|
| `esc.conformance.run(body?, options?)` | `POST /v1/conformance/runs` | `esc.conformance.run({ session_ids: ["ses_5nWq"] })` |
| `esc.conformance.get(id)` | `GET /v1/conformance/runs/{id}` | `esc.conformance.get(runId)` |
| `esc.prompts.generate(body?, options?)` | `POST /v1/prompts/generate` | `esc.prompts.generate({ use_case: "signup_terms", jurisdictions: ["US-FED", "US-CA"] })` |
| `esc.prompts.list(params?)` | `GET /v1/prompts` | `esc.prompts.list({ limit: 20 })` |
| `esc.prompts.get(id)` | `GET /v1/prompts/{id}` | `esc.prompts.get("esc_prompt_8Hq2")` |
| `esc.domains.create(body, options?)` | `POST /v1/domains` | `esc.domains.create({ domain: "example.com", region: "us" })` |
| `esc.domains.get(id)` | `GET /v1/domains/{id}` | `esc.domains.get("dom_4Kx9")` |
| `esc.domains.verify(id)` | `POST /v1/domains/{id}/verify` | `esc.domains.verify("dom_4Kx9")` |
| `esc.domains.update(id, body)` | `PATCH /v1/domains/{id}` | `esc.domains.update("dom_4Kx9", { certificate_spend_limit: 5000 })` |
| `esc.domains.watchJurisdictions(id, jurisdictions)` | `PUT /v1/domains/{id}/watched-jurisdictions` | `esc.domains.watchJurisdictions("dom_4Kx9", ["US-IL", "FR"])` |
| `esc.apiKeys.create(body, options?)` | `POST /v1/api-keys` | `esc.apiKeys.create({ name: "CI", permission: "recording_access", mode: "test" })` |
| `esc.apiKeys.list()` | `GET /v1/api-keys` | `esc.apiKeys.list()` |
| `esc.apiKeys.delete(id)` | `DELETE /v1/api-keys/{id}` | `esc.apiKeys.delete("key_2bQ1")` |

- `conformance.run` body: `session_ids`, `since` (default: the last 24 hours), `url` and `limit` (1 to 500 sessions), all optional. It resolves to a run with `status`, `rules_version`, `summary`, `findings` and `markdown`. Each finding is one rule's result across the sessions of the run: `rule`, `status`, `state`, `counts`, `message`, `measurement`, `fix`, `pages`. Findings are advisory statements about measurable design facts.
- `prompts.generate` body (`PromptGenerateParams`): the wizard selections, all optional. `use_case` or `use_cases` (each a use case ID such as `signup_terms`, `checkout`, `free_trial`, `auto_renewal`, `nda` or `contract`, or `{ use_case, assurance_level?, method?, profile?, documents? }`), `company`, `profile`, `signers`, `jurisdictions`, `jurisdiction_mode`, `on_unknown_region`, `governing_law`, `facts`, `consumer_econsent`, `failure_mode`, `stack` (a framework ID or `{ framework, hosting, database, language }`), `tool` and `options` (`receipts`, `confirmation`, `mobile`, `languages`, `certificate_action`, `reports`, `guidance_updates`). It creates or reuses the profiles the prompt names, stores the prompt and resolves to the `prompt` object: `id`, `title`, `markdown`, `content_hash`, `word_count`, `guidance_release`, `jurisdictions`, `pack_versions`, `block_versions`, `profiles`, `documents`, `env`, `files`, `fact_keys`, `selections`, `warnings`, `status`, `regenerated_from`, `created_by`, `created_at`. Each default that was applied is named in `warnings`. It needs a `full_access` key.
- `prompts.list` takes the list parameters and resolves to the stored prompts of the domain and environment, newest first, without `markdown`, `files`, `fact_keys` and `selections`. `prompts.get` resolves to one prompt with its text. `status.state` is `current` or `update_available`: whether a block or a pack the prompt was built from has a newer version.
- `domains.update` takes a settings object, for example `certificate_spend_limit`. `watchJurisdictions` takes the full list of codes to watch, sends it as `{ jurisdictions }` and resolves to `{ object: "watched_jurisdictions", domain_id, jurisdictions }`: the list as stored, in upper case and without duplicates.
- `apiKeys.create` body: `name`, and optionally `permission` (`full_access`, `recording_access`, `read_only`) and `mode` (`test`, `live`). The full key is in the response once, as `key`.

```ts
const { data: created, error } = await esc.apiKeys.create({ name: "CI", permission: "recording_access", mode: "test" });
if (error) throw new Error(`${error.code}: ${error.message}`);
// Store created.key in your secret manager now. It is not shown again. Never log it.
```

Fields and responses are in the [account API](https://esigncomply.com/docs/api/account.md).

## Any other endpoint {#any-other-endpoint}

```ts
esc.request<T>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, params?: {
  query?: object;
  body?: unknown;
  idempotencyKey?: string;
  apiVersion?: string;
  token?: string;
  signal?: AbortSignal;
}): Promise<Result<T>>
```

`esc.request` calls an endpoint this SDK version has no method for. It follows the same contract as every other method: it resolves to `{ data, error }` and does not throw. `path` is relative to the base URL, for example `/profiles/prof_signup_4f1a`. A `POST` without a `body` sends `{}`. `token` authenticates the call with a session client token in place of the API key.

```ts
import type { Profile } from "esigncomply";

// Update a profile: writes a new profile version.
const { data: updated, error } = await esc.request<Profile>("POST", "/profiles/prof_signup_4f1a", {
  body: { jurisdictions: ["US-FED", "US-CA"], change_note: "Added California." },
  idempotencyKey: "profile-signup-add-ca",
});
if (error) throw new Error(`${error.code}: ${error.message}`);
```

Endpoints without a named method today include updating a profile, updating a document, listing domains, listing conformance runs, sending a test webhook event and the ceremony endpoints of a session (`/sessions/{id}/events`, `/sessions/{id}/complete`).

## Exported helpers

| Export | Signature | Purpose |
|---|---|---|
| `baseUrlForKey` | `(apiKey: string) => string` | The API base URL for a key. The two-letter region in `esc_test_<region>_` or `esc_live_<region>_` selects the host. Anything else gives the US host. |
| `verifyWebhookSignature` | `(rawBody, headers, secret, options?) => Result<WebhookEvent<T>>` | The synchronous core of `esc.webhooks.verify`. |
| `VERSION` | `string` | The SDK version, sent as `X-Esc-Sdk: node/<version>`. |

```ts
baseUrlForKey("esc_test_eu_..."); // "https://api.eu.esigncomply.com/v1"
```

## Other languages (Planned)

> **Planned.** Server SDKs for Python, Go, Ruby and PHP, generated from the OpenAPI document, are not available yet. Until then call the REST API directly. The machine-readable description is at [/openapi.json](https://esigncomply.com/openapi.json).
