Skip to content

Node SDK

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

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.

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.

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.

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

export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!);
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.
  • 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.
timeoutMs number 60000 Timeout for each attempt, in milliseconds.
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.

type Result<T> = { data: T; error: null } | { data: null; error: EscError };
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, 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.
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.

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

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

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

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

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

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

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.

The ceremony steps themselves (events, verifications, completion) are sent by the browser SDK 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, 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 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.
// 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");
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. 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 and the offline verifier.

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 }.
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 with a quote on the error and issues nothing.

See Certificates and the certificates API.

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.
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 and the supplements API.

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.
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 and the guidance API.

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.

// 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 and the signers API.

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

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.

// 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. The exported function verifyWebhookSignature(rawBody, headers, secret, options?) is the same check without the promise: it returns the { data, error } result synchronously.

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.

Usage and verification

Method Endpoint Example
esc.usage.get() GET /v1/usage esc.usage.get()
esc.verify(receiptOrIdOrHash) POST /v1/verify esc.verify(storedReceipt)
// 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. 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.

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

Any other endpoint

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.

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