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.
apiKeydefaults to theESIGNCOMPLY_API_KEYenvironment variable. Store it as a server environment variable. Never use aNEXT_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
windowis defined it throws anError. 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_oresc_live_us_useshttps://esigncomply.com/v1. A key starting withesc_test_eu_oresc_live_eu_useshttps://api.eu.esigncomply.com/v1.esc.baseUrlreturns 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 aPOSTthat carries anidempotencyKey. - A network failure or a timeout is retried for repeatable calls, unless your own
signalaborted the call. - A
429answer is retried for every call. A5xxanswer is retried for repeatable calls only. - The wait is the
Retry-Aftervalue when the API sent one, otherwise 500 ms doubling per attempt up to 8 seconds, with jitter. IfRetry-Afterasks for more than 60 seconds, the SDK returns the error instead of waiting. - At most
maxRetriesretries follow the first attempt (default 2). Each attempt has its owntimeoutMs(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.createbody:name,type(terms,privacy_notice,nda,contract,consent,policy_ack,custom), optionalmetadata.documents.listfilters bytype.versions.createbody:version_label,content, and optionallylanguage,effective_at,material_change,summary_of_changes.contentis{ format: "markdown" | "html" | "text", text }or{ format: "pdf", data_base64 }.versionIdis a version ID or"current".getContenttakes{ locale }to pick a translation when"current"is used. It resolves to the storedtext, the sanitizedhtml, ordata_base64for a PDF, withcontent_hashandrender_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.createbody:name, and optionallyjurisdictions,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.guidanceresolves to{ record_conditions, obligations, recommendations, reports }: everything that applies to the profile now.profiles.adoptmoves 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, plusadoptedandbaseline_detail.profiles.rollbackreturns 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 }) |
listfilters:signer_external_id,email,document_id,version_id,created_after,created_before,status, plus the list parameters.reportresolves to aBinaryResponsewith the evidence report PDF:{ bytes, contentType, filename? }.evidenceoptions:inlineandsupplements. Withoutinlineit resolves to a download link:{ object: "evidence_package", record_id, url, expires_in, size, files, format }. With{ inline: true }it resolves to aBinaryResponsewith 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.receiptresolves to{ object: "receipt", record_id, receipt, kid, payload }.receiptis the compact JWS.annotatebody:{ type, data?, note? }withtypeone ofsuperseded,legal_hold,legal_hold_released,note,paper_copy_requested.noteis free text, up to 4,000 characters, stored asdata.note. The earlier report typesnotice.sentandcancellation.requestedare still accepted and are stored as supplements. New code sends those toesc.supplements.create.certifybody:type,wording,reference,include,share,confirm_charge,reissue_of, all optional. Withshare: { expires_in }the certificate in the response carries the new link asshare: { id, url, expires_at, opens, last_opened_at }.share.urlholds the access secret after#and is returned only in this response;share_urlandshare_expires_atrepeatshare.urlandshare.expires_at.seal.ledgeris the certificate's full ledger entry, which the offline verifier recomputes.submitDeferredis for profiles withfailure_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 optionallyemail,name,class,country,region),documents(each{ document, version }with an exact version ID, not"current"),signed_at,signature(method, and optionallylabel_text,button_text), and optionallycontext(url,locale,purpose,notes),reasonandmetadata.
// 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") |
createissues one certificate over a set of records. Body:typeandfilter(record_ids,signer_external_id,document_id,version_id,created_after,created_before), plus the same optional fields asrecords.certify. It is asynchronous: the answer hasstatus: "processing"and thecertificate.issuedwebhook follows.quotetakes the body of either request, withrecord_idfor a single record. It issues nothing and charges nothing.listfilters:record_id,type,status,created_after,created_before.pdfresolves to aBinaryResponse.sharetakesexpires_inin 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: truea request that would incur a charge returnscertificate_charge_unconfirmedwith aquoteon 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.createbody: at least one oftext,dataorfiles. Optional:subject(exactly one ofrecord,session,signer,document_version,domain; omit it to attach the supplement to the domain),type,occurred_at,rule_ids,labels,supersedes.supplements.listfilters:subject,type,rule_id,label,received_after,received_before. Passsubjectas an object with one key, as a bare ID string, or as"domain". The SDK sends the ID.supplements.contentresolves to{ text, data, files }as stored.withdrawmarks the supplement withdrawn. It stays listed.files.uploadtakes a file path or the bytes (Uint8ArrayorBuffer). Its second argument is{ name?, contentType? }, not the request options object.namedefaults to the base name of the path and is required for bytes.contentTypedefaults toapplication/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.listfilters:jurisdiction,class,severity,kind,topic,since,affecting_profile.notices.acknowledgebody:state(read,appliedornot_applicable) and an optionalnote.updates.getresolves to an object with the update prompt inmarkdown. 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" }) |
createbody:url, and optionallyevents(omit for all) anddescription. The response carries the signingsecret(whsec_...) once.updatebody:url,events,description,status("enabled"or"disabled").listDeliveriestakessince,limit,include,endpointandstatus. It resolves to the delivery history with response codes:id,endpoint_id,webhook_id(the event ID, the value of thewebhook-idheader),type,status,attempts,response_status,response_excerpt,created_at,delivered_at,last_attempt_at. Withsincethe list holds deliveries created after that time, oldest first.include: "payload"adds each event aspayload. The CLI'swebhooks listencommand 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 });
}
rawBodyis the body exactly as received, as a string or bytes. A parsed object is refused withwebhook_payload_invalid, because the signature covers the bytes.headersis a fetchHeadersobject or a plain record such as Node'sreq.headers. The check readswebhook-id,webhook-timestampandwebhook-signature.secretis the endpoint'swhsec_...value.options.toleranceSeconds(default300) is how far the delivery's timestamp may be from now.options.nowreplaces the clock.- The signature is HMAC-SHA256 over
<webhook-id>.<webhook-timestamp>.<raw body>. The header may carry severalv1,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.runbody:session_ids,since(default: the last 24 hours),urlandlimit(1 to 500 sessions), all optional. It resolves to a run withstatus,rules_version,summary,findingsandmarkdown. 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.generatebody (PromptGenerateParams): the wizard selections, all optional.use_caseoruse_cases(each a use case ID such assignup_terms,checkout,free_trial,auto_renewal,ndaorcontract, 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 }),toolandoptions(receipts,confirmation,mobile,languages,certificate_action,reports,guidance_updates). It creates or reuses the profiles the prompt names, stores the prompt and resolves to thepromptobject: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 inwarnings. It needs afull_accesskey.prompts.listtakes the list parameters and resolves to the stored prompts of the domain and environment, newest first, withoutmarkdown,files,fact_keysandselections.prompts.getresolves to one prompt with its text.status.stateiscurrentorupdate_available: whether a block or a pack the prompt was built from has a newer version.domains.updatetakes a settings object, for examplecertificate_spend_limit.watchJurisdictionstakes 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.createbody:name, and optionallypermission(full_access,recording_access,read_only) andmode(test,live). The full key is in the response once, askey.
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.