Skip to content

Documents

Create documents, publish immutable versions, and fetch the registered content your pages render.

A document is a named agreement, for example "Terms of Service" or "Mutual NDA". A document version is an immutable snapshot of its content with a SHA-256 hash, a language, a version label and an effective date. Sessions pin exact versions, and every record names the hashes of the versions it covers.

All endpoints on this page need a secret key and are called from your server, except the content endpoint, which also accepts a session client token. Conventions for authentication, pagination and errors are in the API conventions.

Method and path Key Purpose
POST /v1/documents Secret (full_access, recording_access) Create a document.
GET /v1/documents Secret (any permission) List documents.
GET /v1/documents/{id} Secret (any permission) Retrieve one document with version counts.
PATCH /v1/documents/{id} Secret (full_access, recording_access) Rename, archive, or change metadata.
POST /v1/documents/{id}/versions Secret (full_access, recording_access) Publish an immutable version.
GET /v1/documents/{id}/versions Secret (any permission) List versions.
GET /v1/documents/{id}/versions/{version_id} Secret (any permission) Retrieve one version, or current.
GET /v1/documents/{id}/versions/{version_id}/content Secret (any permission) or client token Fetch the registered content to render.

Document types

type is an open string. These values are recognized. Any other value is stored as sent and treated like custom.

Type Examples Usual ceremony
terms Terms of service, end-user license, acceptable-use policy Checkbox acceptance, L1
privacy_notice Privacy notice acknowledgment Acknowledgment, L1
nda Mutual or one-way NDA Typed-name signature, L2
contract Order form, master services agreement, statement of work Typed-name signature, L2
consent Consent to electronic records, marketing consent Explicit consent, L1 or L2
policy_ack Employee handbook, security policy, code of conduct Acknowledgment, L2
custom Anything else that passes the exclusion screen Chosen on the profile

The type feeds rule scope during jurisdiction resolution. A session that includes a document of type nda, contract or order_form is treated as a signature ceremony: the notice is checked for the electronic-signing statement (CR-12) and the method is expected to be a typed name or stronger (CR-09). A session that covers only privacy_notice or policy_ack documents with a click or checkbox is recorded with signature_level: "not_applicable": it is a recorded acknowledgment, not a signature.

Create a document

POST /v1/documents

Key: secret key with full_access or recording_access. Idempotent with Idempotency-Key.

Request fields

Field Type Required Description
name string, 1 to 200 characters Yes The title signers see. The notice text in your assent region must contain it (CR-02).
type string, 1 to 40 characters Yes A value from the table above.
metadata object No Your own key-value pairs.

Example request

curl https://esigncomply.com/v1/documents \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Terms of Service", "type": "terms" }'

Example response

201 Created

{
  "object": "document",
  "id": "doc_8Hq2",
  "livemode": false,
  "name": "Terms of Service",
  "type": "terms",
  "metadata": {},
  "archived": false,
  "created_at": "2026-11-21T15:00:02.118Z",
  "warnings": []
}

warnings lists request fields the API did not recognize, as unknown_field:<path>. They are ignored, not rejected.

Errors

invalid_request when name or type is missing or the wrong type. insufficient_permission for a read_only key.

List documents

GET /v1/documents

Key: secret key with any permission.

Query parameters

Parameter Type Description
type string Return only documents of this type.
limit integer, 1 to 100 Page size. Default 20.
after document ID Return documents created before this one (next page).
before document ID Return documents created after this one (previous page). Do not send with after.

Documents are returned newest first.

Example request

curl "https://esigncomply.com/v1/documents?type=terms&limit=20" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "doc_8Hq2",
      "livemode": false,
      "name": "Terms of Service",
      "type": "terms",
      "metadata": {},
      "archived": false,
      "created_at": "2026-11-21T15:00:02.118Z"
    }
  ],
  "has_more": false
}

Errors

invalid_request when limit is out of range, when both after and before are sent, or when the cursor does not exist.

Retrieve a document

GET /v1/documents/{id}

Key: secret key with any permission.

Returns the document with three extra fields.

Field Type Description
current_version string or null ID of the version that "current" resolves to now (default locale). Null when no version is in effect.
versions integer Number of published versions, all languages.
signers_by_version object Count of distinct signers with a record on each version ID.

Example request

curl https://esigncomply.com/v1/documents/doc_8Hq2 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "document",
  "id": "doc_8Hq2",
  "livemode": false,
  "name": "Terms of Service",
  "type": "terms",
  "metadata": {},
  "archived": false,
  "created_at": "2026-11-21T15:00:02.118Z",
  "current_version": "dv_3kT9",
  "versions": 1,
  "signers_by_version": { "dv_3kT9": 42 }
}

Errors

not_found when the document does not exist in this domain and environment. Test and live documents are separate.

Update a document

PATCH /v1/documents/{id}

Key: secret key with full_access or recording_access.

Changes metadata only. Published versions are never changed by this call.

Request fields

Field Type Required Description
name string, 1 to 200 characters No New title. Existing records keep the title that was sealed in them.
metadata object No Replaces the stored metadata.
archived boolean No true archives the document, false restores it.

Example request

curl -X PATCH https://esigncomply.com/v1/documents/doc_8Hq2 \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "owner": "legal" } }'

Example response

200 OK

{
  "object": "document",
  "id": "doc_8Hq2",
  "livemode": false,
  "name": "Terms of Service",
  "type": "terms",
  "metadata": { "owner": "legal" },
  "archived": false,
  "created_at": "2026-11-21T15:00:02.118Z"
}

Errors

not_found, invalid_request.

Publish a version

POST /v1/documents/{id}/versions

Key: secret key with full_access or recording_access. Idempotent with Idempotency-Key.

Publishes an immutable version and returns its hashes. Publish when the text is final: there is no endpoint that edits or deletes a version. To change the text, publish a new version_label.

Request fields

Field Type Required Description
version_label string, 1 to 64 characters Yes Your label for the version, for example a date. One version per label and language.
language string, 2 to 16 characters No Language code. Default en. Stored in lower case.
effective_at RFC 3339 timestamp No When the version starts to resolve as current. Default: now.
content object Yes See "Content formats" below.
material_change boolean No Default false. true leaves earlier acceptances outstanding (see Re-acceptance).
summary_of_changes string, up to 2,000 characters No Plain summary you can show on a re-acceptance screen.

Content formats

content.format Other fields Notes
markdown text Rendered to sanitized HTML with GitHub-flavored Markdown.
html text Sanitized on receipt. If anything was removed, the response carries the warning html_sanitized and the hashes cover the sanitized text.
text text Plain text. Blank lines become paragraphs.
pdf data_base64 The file, base64-encoded. It must start with %PDF-. render_hash is null for PDFs.

Size limits: text content up to 4 MB, PDF files up to 10 MB, and the whole request body up to 4.4 MB. Because the PDF travels base64-encoded inside the JSON body, a PDF of roughly 3.3 MB is the practical limit in one request.

Example request

POST /v1/documents/doc_8Hq2/versions
Authorization: Bearer esc_test_us_...
Content-Type: application/json
Idempotency-Key: tos-2026-11-21

{
  "version_label": "2026-11-21",
  "language": "en",
  "effective_at": "2026-12-01T00:00:00Z",
  "content": { "format": "markdown", "text": "# Terms of Service\n\nThese are the terms.\n\n- One\n- Two" },
  "material_change": true,
  "summary_of_changes": "Added arbitration clause in section 14."
}

Example response

201 Created

{
  "object": "document_version",
  "id": "dv_3kT9",
  "document_id": "doc_8Hq2",
  "livemode": false,
  "version_label": "2026-11-21",
  "language": "en",
  "format": "markdown",
  "content_hash": "sha256:9f2c...",
  "render_hash": "sha256:41ab...",
  "size": 53,
  "material_change": true,
  "summary_of_changes": "Added arbitration clause in section 14.",
  "effective_at": "2026-12-01T00:00:00.000Z",
  "published_at": "2026-11-21T15:02:11.482Z",
  "warnings": []
}

What publishing does

  • Stores the exact bytes and computes both hashes (see "Hashes" below).
  • Sends the document.version_published webhook.
  • With material_change: true, sends signer.reacceptance_required for each signer who has a record on an earlier version of the document. See Webhooks.

Errors

Code When
invalid_request A required field is missing, content.text is empty, effective_at is not a timestamp, or data_base64 is not a PDF. param names the field.
file_too_large Text over 4 MB or a PDF over 10 MB.
idempotency_conflict A version with this version_label and language already exists for the document (param: "version_label"), or the Idempotency-Key was reused with a different body.
not_found The document does not exist in this domain and environment.

Hashes

Every version has two hashes. Both are SHA-256, lower-case hexadecimal, prefixed sha256:.

Hash Covers Used for
content_hash The exact bytes stored (after sanitizing, for html). The record names it. Anyone holding the file can hash it and compare.
render_hash The visible text of the rendered version: Unicode NFC, with all whitespace and zero-width characters removed. The browser SDK computes the same value over the text it finds on your page and reports it. A difference is a render_mismatch (CR-08).

To make the text on your page match render_hash, fetch the version from the content endpoint and inject the returned html unmodified into the container you pass to the SDK. Do not copy document text into your repository, re-render the Markdown with your own library, or add text nodes inside the container. Styling with CSS is fine: the hash covers text, not markup or styles.

Versions and languages

  • Immutable. A published version cannot be edited, and there is no delete endpoint. Records keep pointing at the version they pinned.
  • Current. "current" resolves to the version with the latest effective_at that has already arrived. A version with a future effective_at is published but not yet current. A session that asks for current before any version is in effect gets version_not_published.
  • Translations. Publish one version per language under the same version_label. When a session has context.locale, current picks the version in that language, then en, then any language of the newest label.
  • Material change. material_change: true marks earlier acceptances as outstanding in the signer status endpoint. Earlier records stay on file. See Signers.

List versions

GET /v1/documents/{id}/versions

Key: secret key with any permission.

Returns every version of the document, latest effective_at first. The list is not paginated: has_more is always false.

Example request

curl https://esigncomply.com/v1/documents/doc_8Hq2/versions \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "document_version",
      "id": "dv_3kT9",
      "document_id": "doc_8Hq2",
      "livemode": false,
      "version_label": "2026-11-21",
      "language": "en",
      "format": "markdown",
      "content_hash": "sha256:9f2c...",
      "render_hash": "sha256:41ab...",
      "size": 53,
      "material_change": true,
      "summary_of_changes": "Added arbitration clause in section 14.",
      "effective_at": "2026-12-01T00:00:00.000Z",
      "published_at": "2026-11-21T15:02:11.482Z"
    }
  ],
  "has_more": false
}

Retrieve a version

GET /v1/documents/{id}/versions/{version_id}

Key: secret key with any permission.

version_id is a version ID or the word current. With current, the optional query parameter locale (for example de-DE) selects the translation, as a session would.

Example request

curl "https://esigncomply.com/v1/documents/doc_8Hq2/versions/current?locale=en-US" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK. The body is the document_version object shown under "Publish a version", without warnings.

Errors

not_found when the version does not exist, belongs to another document, or no version is in effect for current.

Fetch version content

GET /v1/documents/{id}/versions/{version_id}/content

Key: secret key with any permission, or a session client token (esc_ct_...).

Returns the registered content to render. Use the version ID your session pinned, not current, so that the page shows exactly what the record will name.

  • With a secret key, version_id may be an ID or current (with optional ?locale=).
  • With a client token, only the versions pinned on that token's own session can be read, by ID. Anything else returns not_found. The call must come from an allowed origin, as for every browser endpoint.

The response is cacheable privately for one hour (Cache-Control: private, max-age=3600, immutable). Versions never change, so you can cache by version ID for as long as you like.

Example request

curl https://esigncomply.com/v1/documents/doc_8Hq2/versions/dv_3kT9/content \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"

Example response

200 OK

{
  "object": "document_version_content",
  "version_id": "dv_3kT9",
  "document_id": "doc_8Hq2",
  "format": "markdown",
  "language": "en",
  "content_hash": "sha256:9f2c...",
  "render_hash": "sha256:41ab...",
  "text": "# Terms of Service\n\nThese are the terms.\n\n- One\n- Two",
  "html": "<h1>Terms of Service</h1>\n<p>These are the terms.</p>\n<ul>\n<li>One</li>\n<li>Two</li>\n</ul>\n"
}
Format Fields returned
markdown, html, text text (the stored source) and html (sanitized HTML to inject).
pdf data_base64 and content_type: "application/pdf". No text or html.

Rendering in Next.js

// app/legal/[versionId]/page.tsx (server component)
import { esc } from "@/lib/esigncomply";
import { notFound } from "next/navigation";

export default async function LegalPage({ params }: { params: Promise<{ versionId: string }> }) {
  const { versionId } = await params;
  const { data, error } = await esc.documents.versions.getContent("doc_8Hq2", versionId);
  if (error || !data.html) notFound();
  // Inject the registered HTML unmodified so the page text matches render_hash.
  return <article data-esc-document dangerouslySetInnerHTML={{ __html: data.html }} />;
}

Errors

not_found, client_token_expired, domain_mismatch for a client token used from an origin outside the registered domain or the test allowlist.

Hash-only registration (Planned)

Planned. Hash-only registration is scheduled for a later release. It is not part of the supported API yet, and the field names below may change.

content: { "format": "hash_only", "sha256": "...", "render_sha256": "..." } will register a version without uploading its text. Esign Comply then seals the hash but holds no copy: it cannot display, deliver or retain the document, so your team keeps the copy and carries the retention duty. The evidence report says so, the version response carries the warning hash_only_customer_keeps_copy, and hash-only versions are refused for consumer signers.