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
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_publishedwebhook. - With
material_change: true, sendssigner.reacceptance_requiredfor 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 latesteffective_atthat has already arrived. A version with a futureeffective_atis published but not yet current. A session that asks forcurrentbefore any version is in effect getsversion_not_published. - Translations. Publish one version per language under the same
version_label. When a session hascontext.locale,currentpicks the version in that language, thenen, then any language of the newest label. - Material change.
material_change: truemarks 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_idmay be an ID orcurrent(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.
Related
- Sessions: pin versions in a ceremony.
- Browser SDK:
presentDocumentcompares your page withrender_hash. - Next.js guide: document pages end to end.