# Documents

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

Source: https://esigncomply.com/docs/api/documents

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](https://esigncomply.com/docs/api.md).

| 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](https://esigncomply.com/docs/api/jurisdictions.md). 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](https://esigncomply.com/docs/conformance.md#cr-12)) and the method is expected to be a typed name or stronger ([CR-09](https://esigncomply.com/docs/conformance.md#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](https://esigncomply.com/docs/conformance.md#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**

```bash
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`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#invalid_request) when `name` or `type` is missing or the wrong type. [`insufficient_permission`](https://esigncomply.com/docs/api/errors.md#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**

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

**Example response**

`200 OK`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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**

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

**Example response**

`200 OK`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#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**

```bash
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`

```json
{
  "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`](https://esigncomply.com/docs/api/errors.md#not_found), [`invalid_request`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/guides/reacceptance.md)). |
| `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**

```http
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`

```json
{
  "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](https://esigncomply.com/docs/api/webhooks.md).

**Errors**

| Code | When |
|---|---|
| [`invalid_request`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#file_too_large) | Text over 4 MB or a PDF over 10 MB. |
| [`idempotency_conflict`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#render_mismatch) ([CR-08](https://esigncomply.com/docs/conformance.md#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`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/signers.md).

## 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**

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

**Example response**

`200 OK`

```json
{
  "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**

```bash
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`](https://esigncomply.com/docs/api/errors.md#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`](https://esigncomply.com/docs/api/errors.md#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**

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

**Example response**

`200 OK`

```json
{
  "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**

```tsx
// 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`](https://esigncomply.com/docs/api/errors.md#not_found), [`client_token_expired`](https://esigncomply.com/docs/api/errors.md#client_token_expired), [`domain_mismatch`](https://esigncomply.com/docs/api/errors.md#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](https://esigncomply.com/docs/api/sessions.md): pin versions in a ceremony.
- [Browser SDK](https://esigncomply.com/docs/sdk/browser.md): `presentDocument` compares your page with `render_hash`.
- [Next.js guide](https://esigncomply.com/docs/guides/nextjs.md): document pages end to end.
