# eDocInk API 1.7.0 — reference

Generated from the [OpenAPI contract](/openapi.json).

Server: `https://esign-sandbox.runmast.com` (Sandbox), `https://esign.runmast.com` (Production)

## Overview

Server-to-server API for preparing plain-text or template documents, collecting one or more required signatures through hosted signing pages, and retrieving verifiable evidence.

**Read first:** the integration requirements, [integration requirements](/guides/integration-requirements).

### Authentication and tenancy
Every call sends `Authorization: Bearer <app key>` and `X-Tenant-ID: <tenant uuid>`. Keys are issued per app and environment, scoped (see `x-required-scopes` on each operation) and expire. Keys are server-side secrets: never send them to a browser or mobile client.

### Idempotency
Every POST requires `Idempotency-Key` (1-128 characters). Save the key in your own database **before** sending. Retrying with the same key and the same body returns the original result; the same key with a different body returns 409. After a timeout or 5xx, recover with the matching GET (most take the original key in an `X-Original-*-Key` header) or retry with the same key. Never invent a new key to retry an operation whose outcome is unknown.

### Concurrency
Cancel and withdraw require `If-Match: "<resource_version>"` from the latest read (428 without it, 412 when stale: re-read and decide again). Requests also return the version as `ETag`; envelopes return it only in the body as `resource_version`.

### Errors
Errors use the `Error` schema: `code` (`http_<status>`, `invalid_request` or `service_unavailable`), a human-readable `message` that may change, and `request_id` (also in `X-Request-ID`). Branch on the HTTP status, not on `message`. 409 means the resource is not in a state that allows the action yet or any more (for example a signing link is requested before the document has finished preparing): re-read, and retry only if the state can still change. 429 and 503 carry `Retry-After`.

### Limits
- Signing-link issuance: 5 per signing request in any rolling hour (the 6th returns 429). A request has one signer.
- Active preparations: 100 unexpired document preparations and 100 unexpired envelope preparations per app and tenant; a preparation expires 10 minutes after it is created.
- Signing links live 72 hours and never beyond the request.
- Requests and envelopes: `expires_in` 60 s to 30 days.
- Page size: `limit` 1-100 on `/requests` and `/events`.
- Request bodies: at most 1 MiB (413); 2 MiB for text and envelope preparations. JSON bodies must be sent as `application/json` (415).
- Plain-text documents: title up to 200 characters; the whole document (title, two newlines, body) up to 200,000 UTF-8 bytes (413 above that: send a PDF).

### Versioning
Paths under `/api/v1` change only additively: new operations, new optional request fields, new response fields and new event types. Clients must ignore unknown response fields and event types. Removing or changing the meaning of anything requires `/api/v2`; v1 then stays available for at least 6 months after v2 is published, and the change is announced in the service changelog. The `info.version` of this document follows semantic versioning for the documentation itself.

### Webhooks
Optional, configured by the service operator per app and tenant (a destination URL and a signing key). See `webhooks.signingEvent`. The event feed (`GET /api/v1/events`) carries the same events and is always available.

### Notices and compatibility
When something changes that affects your app, the service publishes a notice. While your app has an unacknowledged notice, every successful API response carries `eDocInk-Notices: <count>; latest="<id>"`. `GET /api/v1/notices` lists the notices that apply to your app, `POST /api/v1/notices/{notice_id}/acknowledge` records that you have dealt with one, and `GET /api/v1/compatibility` says whether your SDK is current. SDK 0.32 and later send `User-Agent: edocink-sdk/<version>`, so notices about older SDKs stop applying once you upgrade. While an operation you call, or the SDK version you report, is being retired, responses also carry `Deprecation` (RFC 9745, the date it was announced), `Sunset` (RFC 8594, the date it stops working) and `Link` to the changelog, until that date. Acknowledging the notice does not remove them.

## Operations

## Signing policies

### GET `/api/v1/signing-policies`

`listSigningPolicies` — Creator-selectable published immutable authentication policies

- **Scopes:** `documents:submit`
- **Headers:** `X-Tenant-ID`
- **200:** The tenant's published signing policies (name, version, signing method and consent version) → [`SigningPolicyCatalog`](#schema-signingpolicycatalog)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

## Single-signer requests

### POST `/api/v1/text-document-preparations`

`prepareTextDocument` — Prepare first-class plain text under explicit tenant policy

- **Scopes:** `documents:prepare`, `documents:submit`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`PlainTextSubmission`](#schema-plaintextsubmission)
- **201:** Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → [`DocumentPreparation`](#schema-documentpreparation)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### POST `/api/v1/document-uploads`

`uploadDocument` — Upload a PDF to sign; returns its SHA-256

Send the raw PDF bytes (at most 10 MiB) with `Content-Type: application/pdf`. The engine checks only the `%PDF-` header and `%%EOF` trailer; it never parses or changes the file, and the signer reviews exactly these bytes. Uploading the same bytes again returns the same `sha256`, so no idempotency key is needed. An upload expires after 24 hours; at most 200 live uploads per app and tenant.

- **Scopes:** `documents:submit`
- **Headers:** `X-Tenant-ID`
- **201:** Stored, or the same bytes already stored → [`DocumentUpload`](#schema-documentupload)
- **Errors:** 400, 401, 403, 413, 415, 429, 503 (see [Errors](#errors))

### POST `/api/v1/document-conversions`

`convertDocument` — Convert a Word, OpenDocument, RTF, HTML, text or image file to PDF

Send the raw file (at most 10 MiB) with its `Content-Type`. The service converts it in a sandbox, with no network and no access to other files, and stores the PDF as an ordinary upload. Poll `getDocumentConversion`; when `ready`, download the PDF with `getConvertedPdf` and **check how it looks before sending it**, because layout can differ from the program that made the file. Then prepare it with `preparePdfDocument` using `pdf.sha256`. Sending the same bytes and type again returns the same conversion, so no idempotency key is needed. At most 50 conversions per app and tenant per hour. Answers 503 when the operator has not enabled conversion.

- **Scopes:** `documents:submit`
- **Headers:** `X-Tenant-ID`
- **202:** Queued, or the same file already converting or converted → [`DocumentConversion`](#schema-documentconversion)
- **Errors:** 400, 401, 403, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/document-conversions/{conversion_id}`

`getDocumentConversion` — Read a conversion's status

- **Scopes:** `documents:submit`
- **Path:** `conversion_id`
- **Headers:** `X-Tenant-ID`
- **200:** Current status → [`DocumentConversion`](#schema-documentconversion)
- **Errors:** 400, 401, 403, 404, 503 (see [Errors](#errors))

### GET `/api/v1/document-conversions/{conversion_id}/pdf`

`getConvertedPdf` — Download the converted PDF to check it before sending

- **Scopes:** `documents:submit`
- **Path:** `conversion_id`
- **Headers:** `X-Tenant-ID`
- **200:** The PDF bytes
- **Errors:** 400, 401, 403, 404, 409, 503 (see [Errors](#errors))

### POST `/api/v1/pdf-document-preparations`

`preparePdfDocument` — Prepare an uploaded PDF under explicit tenant policy

Same rules as `prepareTextDocument`: an immutable ten-minute snapshot consumed by `createPreparedRequest`. The same signing policy governs text and PDF documents. The document is bound by `original_sha256`, the upload's hash.

- **Scopes:** `documents:prepare`, `documents:submit`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`PdfSubmission`](#schema-pdfsubmission)
- **201:** Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → [`PdfDocumentPreparation`](#schema-pdfdocumentpreparation)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### POST `/api/v1/document-preparations`

`prepareDocument` — Prepare exact template text and full immutable intent without creating or inviting

- **Scopes:** `documents:prepare`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`CreateRequest`](#schema-createrequest)
- **201:** Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → [`DocumentPreparation`](#schema-documentpreparation)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### POST `/api/v1/document-preparations/{preparation_id}/requests`

`createPreparedRequest` — Atomically create one request from a previously reviewed preparation

- **Scopes:** `requests:create`
- **Path:** `preparation_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** empty object `{}`
- **202:** Single request created from exact prepared intent; original-key replay recovers committed request even after preparation expiry. Another key conflicts → [`SigningRequest`](#schema-signingrequest) · headers `ETag`, `Location`
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/document-preparations/{preparation_id}/requests`

`observePreparedRequest` — Read-only snapshot lookup of original prepared-create binding; absence is inconclusive

- **Scopes:** `requests:read`
- **Path:** `preparation_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Create-Key`
- **200:** Bound current resource or no binding visible in this statement snapshot. Neither renews authority nor permits resend → [`PreparedRequestObservation`](#schema-preparedrequestobservation)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### POST `/api/v1/requests`

`createRequest` — Freeze a request and queue original preparation

- **Scopes:** `requests:create`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`CreateRequest`](#schema-createrequest)
- **202:** New request accepted, or same-key replay returning the existing current resource, possibly already terminal. No additional render job is queued on replay → [`SigningRequest`](#schema-signingrequest) · headers `ETag`, `Location`
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}`

`getRequest` — Read current request state

- **Scopes:** `requests:read`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`
- **200:** Success → [`SigningRequest`](#schema-signingrequest) · headers `ETag`
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests`

`listRequests` — Rebuild scope-local state using a paginated scan and replay watermark

- **Scopes:** `requests:read`
- **Headers:** `X-Tenant-ID`
- **Query:** `cursor` (optional), `limit` (optional)
- **200:** Request page → [`RequestPage`](#schema-requestpage)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### POST `/api/v1/requests/{request_id}/cancel`

`cancelRequest` — Cancel an unsigned request

- **Scopes:** `requests:cancel`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`, `If-Match`
- **200:** Success → [`SigningRequest`](#schema-signingrequest) · headers `ETag`
- **Errors:** 400, 401, 403, 404, 409, 412, 413, 415, 428, 429, 503 (see [Errors](#errors))

## Signing links (app-owned delivery)

### POST `/api/v1/requests/{request_id}/invitations`

`sendInvitation` — Issue invitation idempotently; delivery channel configured by service, ACK is not email delivery

- **Scopes:** `invitations:create`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** empty object `{}`
- **202:** Success → [`Invitation`](#schema-invitation)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}/invitations`

`observeInvitation` — Read-only snapshot of original invitation queue receipt; absence is inconclusive

- **Scopes:** `requests:read`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Invite-Key`
- **200:** Original queued ACK or inconclusive absence; no provider delivery status or resend authority → [`InvitationObservation`](#schema-invitationobservation)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}/invitation-handoff`

`getAppInvitationHandoff` — Recover original live signing capabilities for app-owned delivery; never mint, renew or send

- **Scopes:** `invitations:create`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Invite-Key`
- **200:** The app's own handoff for the current signing link created with this original invitation key: `signing_url`, recipient and expiry. Never stored by the service in readable form; re-derived on each call → [`AppInvitationHandoff`](#schema-appinvitationhandoff)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

## Multi-signer envelopes

### POST `/api/v1/envelope-preparations`

`prepareEnvelope` — Prepare one exact common document and immutable N-member plan; never creates or sends

- **Scopes:** `documents:prepare`, `documents:submit`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`EnvelopeSubmission`](#schema-envelopesubmission)
- **201:** Success → [`EnvelopePreparation`](#schema-envelopepreparation)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/envelope-preparations/{preparation_id}`

`getEnvelopePreparation` — Recover original immutable preview/plan without new preparation

- **Scopes:** `documents:prepare`, `documents:submit`
- **Path:** `preparation_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Prepare-Key`
- **200:** Success → [`EnvelopePreparation`](#schema-envelopepreparation)
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

### POST `/api/v1/envelope-preparations/{preparation_id}/envelope`

`createPreparedEnvelope` — Atomically enroll all original planned members from an immutable reviewed preparation

- **Scopes:** `requests:create`, `documents:submit`
- **Path:** `preparation_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** empty object `{}`
- **201:** Success → [`SigningEnvelope`](#schema-signingenvelope)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### POST `/api/v1/signing-envelopes`

`createSigningEnvelope` — Freeze N required ready unsigned requests into an immutable signing envelope; never invites

- **Scopes:** `requests:create`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** [`EnvelopeCreate`](#schema-envelopecreate)
- **201:** Immutable N-required-signer envelope → [`SigningEnvelope`](#schema-signingenvelope)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/signing-envelopes/{envelope_id}`

`getSigningEnvelope` — Read immutable roster and aggregate all-required signing/completion status

- **Scopes:** `requests:read`
- **Path:** `envelope_id`
- **Headers:** `X-Tenant-ID`
- **200:** Success → [`SigningEnvelope`](#schema-signingenvelope)
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

### POST `/api/v1/signing-envelopes/{envelope_id}/invitations`

`inviteEnvelope` — Explicitly queue the original N roster atomically; never implicit resend

- **Scopes:** `invitations:create`
- **Path:** `envelope_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`
- **Body:** empty object `{}`
- **202:** Success → [`EnvelopeInvitationBatch`](#schema-envelopeinvitationbatch)
- **Errors:** 400, 401, 403, 404, 409, 413, 415, 429, 503 (see [Errors](#errors))

### GET `/api/v1/signing-envelopes/{envelope_id}/invitations`

`observeEnvelopeInvitations` — Read original batch ACK or inconclusive absence; never POST

- **Scopes:** `requests:read`
- **Path:** `envelope_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Invite-Key`
- **200:** Success → [`EnvelopeInvitationObservation`](#schema-envelopeinvitationobservation)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### GET `/api/v1/signing-envelopes/{envelope_id}/invitation-handoff`

`getAppEnvelopeInvitationHandoff` — Recover original live signing capabilities for app-owned delivery; never mint, renew or send

- **Scopes:** `invitations:create`
- **Path:** `envelope_id`
- **Headers:** `X-Tenant-ID`, `X-Original-Invite-Key`
- **200:** The app's own handoff for the current envelope signing link created with this original invitation key: `signing_url`, recipient and expiry. Re-derived on each call → [`AppEnvelopeInvitationHandoff`](#schema-appenvelopeinvitationhandoff)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### POST `/api/v1/signing-envelopes/{envelope_id}/withdraw`

`withdrawSigningEnvelope` — Irreversibly stop new invitations/reviews/signatures for a partially accepted envelope; retain signatures

- **Scopes:** `requests:cancel`
- **Path:** `envelope_id`
- **Headers:** `X-Tenant-ID`, `Idempotency-Key`, `If-Match`
- **200:** Success → [`SigningEnvelope`](#schema-signingenvelope)
- **Errors:** 400, 401, 403, 404, 409, 412, 413, 415, 428, 429, 503 (see [Errors](#errors))

## Status, events and evidence

### GET `/api/v1/events`

`listEvents` — Recover events in committed stream order

- **Scopes:** `events:read`
- **Headers:** `X-Tenant-ID`
- **Query:** `after` (optional), `limit` (optional)
- **200:** Success → [`EventPage`](#schema-eventpage)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}/original`

`getOriginal` — Download the exact original the signer reviewed

Returns the original's bytes (`application/pdf` or `text/plain; charset=utf-8`), whose SHA-256 is `original_sha256` in the request and the evidence. 409 until the original is prepared. A PDF original is not embedded in the evidence; use this to re-check its hash.

- **Scopes:** `requests:read`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`
- **200:** The original bytes
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}/evidence`

`getEvidence` — Retrieve completed evidence; 409 while unavailable

- **Scopes:** `evidence:read`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`
- **200:** Success → [`Evidence`](#schema-evidence)
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

### GET `/api/v1/requests/{request_id}/evidence/timestamp`

`getEvidenceTimestamp` — Retrieve the independent RFC 3161 timestamp over the evidence; 409 until one exists

An outside Time Stamp Authority signs the SHA-256 of the exact evidence bytes returned by `getEvidence`, proving those bytes existed no later than `gen_time`. It is obtained after completion and never delays it: expect 409 for a short time after evidence is ready, or longer if the authority is unavailable. Only the hash is sent to the authority. Verify `response` (base64 DER TimeStampResp) against the evidence bytes and the authority's root certificate, pinned in your configuration (never taken from the response): for example base64-decode `response` to `timestamp.tsr` and run `openssl ts -verify -data evidence.json -in timestamp.tsr -CAfile tsa-root.pem`.

- **Scopes:** `evidence:read`
- **Path:** `request_id`
- **Headers:** `X-Tenant-ID`
- **200:** Success → [`EvidenceTimestamp`](#schema-evidencetimestamp)
- **Errors:** 400, 401, 403, 404, 409, 429, 503 (see [Errors](#errors))

## Account sign-in

### GET `/api/v1/signer-authentication-context`

`getAppAuthenticationContext` — Authenticated app-server lookup of original pending browser authentication context

- **Scopes:** `requests:read`
- **Headers:** `X-Tenant-ID`, `X-Signer-Auth-State`
- **200:** The authentication context for the account sign-in started with `X-Signer-Auth-State` → [`AppAuthenticationContext`](#schema-appauthenticationcontext)
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

## Notices and compatibility

### GET `/api/v1/notices`

`listNotices` — Notices that apply to this app

Any live key granted this tenant may call this, whatever its scopes.

- **Scopes:** none
- **Headers:** `X-Tenant-ID`, `User-Agent` (optional)
- **200:** The notices that apply to this app (published, and for an SDK older than the one reported), acknowledged or not, oldest first, with the reported SDK's status → [`NoticeList`](#schema-noticelist) · headers `eDocInk-Notices`
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### POST `/api/v1/notices/{notice_id}/acknowledge`

`acknowledgeNotice` — Record that this app has dealt with a notice

Any live key granted this tenant may call this, whatever its scopes.

- **Scopes:** none
- **Path:** `notice_id`
- **Headers:** `X-Tenant-ID`
- **200:** The notice, acknowledged. Acknowledging again changes nothing. An acknowledged notice no longer counts in eDocInk-Notices → [`Notice`](#schema-notice) · headers `eDocInk-Notices`
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

### GET `/api/v1/compatibility`

`getCompatibility` — Whether this app's SDK is current, and its open notices

Any live key granted this tenant may call this, whatever its scopes.

- **Scopes:** none
- **Headers:** `X-Tenant-ID`, `User-Agent` (optional)
- **200:** The API version, the reported SDK's status against the latest and minimum supported SDK, and the unacknowledged notices → [`Compatibility`](#schema-compatibility) · headers `eDocInk-Notices`
- **Errors:** 400, 401, 403, 404, 409, 410, 429, 503 (see [Errors](#errors))

## Webhooks

### `signingEvent`

Sent when a request changes state. The body is the same `Event` document as the event feed. Verify before trusting: compute HMAC-SHA256 with the key named by `Esign-Key-ID` over the bytes `<Esign-Timestamp>.<Esign-Delivery-ID>.<raw body>` and compare it in constant time with `Esign-Signature` (lowercase hex). Reject timestamps more than 300 seconds from now. Record `Esign-Event-ID` before acting and ignore repeats: a delivery can arrive more than once. Respond 2xx within 10 seconds; anything else is retried with exponential backoff (about 5 seconds doubling, at most 1 hour apart) for up to 72 hours or 100 attempts. Order is not guaranteed; use `stream_version` and `resource_version`, or re-read the request. The SDK's `receiveWebhookOnce` implements all of this.

- **Headers:** `Esign-Event-ID`, `Esign-Delivery-ID`, `Esign-Timestamp`, `Esign-Key-ID`, `Esign-Signature`
- **Body:** [`Event`](#schema-event)

## <a id="errors"></a>Errors

| Status | Meaning | What the app should do |
| --- | --- | --- |
| 400 | Invalid input | Fix the request; do not retry unchanged |
| 401 | Unknown, expired or revoked key | Check the key; rotate if expired |
| 403 | Key lacks the operation's scope | Ask the operator for the scope |
| 404 | Not visible to this app and tenant (or never existed) | Treat as unknown, not as proof of absence after a timeout |
| 409 | Same key with different input, or the resource's state does not allow this yet / any more | Re-read; retry only if the state can still change |
| 410 | A list or event-feed cursor expired, or the service history was restored | Restart the scan from the beginning; reconcile against your own records |
| 412 | `If-Match` is stale | Re-read, decide again, send the current version |
| 413 | Body over 1 MiB | Shorten the document |
| 415 | Body not `application/json` | Send JSON |
| 428 | `If-Match` missing | Read the resource first |
| 429 | Rate or capacity limit | Wait for `Retry-After`; retry with the same key |
| 503 | Temporarily unavailable | Wait for `Retry-After`; retry with the same key or recover by GET |

## Schemas

### <a id="schema-error"></a>Error

Problem document for every 4xx/5xx. Branch on the HTTP status; `message` is for people and may change.

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |
| `message` | string | yes |
| `request_id` | string (format uuid) | yes |

No other fields are accepted.

### <a id="schema-definition"></a>Definition

| Field | Type | Required |
| --- | --- | --- |
| `name` | string (pattern ^[A-Za-z0-9_-]{1,80}$) | yes |
| `version` | integer (minimum 1) | yes |

No other fields are accepted.

### <a id="schema-recipient"></a>Recipient

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (format email, maxLength 254) | yes |
| `display_name` | string (minLength 1, maxLength 200) | yes |

No other fields are accepted.

### <a id="schema-createrequest"></a>CreateRequest

| Field | Type | Required |
| --- | --- | --- |
| `definition` | [`Definition`](#schema-definition) | yes |
| `recipient` | [`Recipient`](#schema-recipient) | yes |
| `data` | object | yes |
| `expires_in` | integer (minimum 60, maximum 2592000) | yes |
| `business_reference` | string (maxLength 200) |  |

No other fields are accepted.

### <a id="schema-signingrequest"></a>SigningRequest

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `definition` | [`Definition`](#schema-definition) | yes |
| `status` | `preparing` \| `pending` \| `signed` \| `cancelled` \| `expired` \| `failed` | yes |
| `completion_status` | `not_started` \| `building` \| `ready` \| `failed` | yes |
| `resource_version` | integer (minimum 1) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |
| `signed_at` | string or null (format date-time) | yes |
| `original_sha256` | string (pattern ^[a-f0-9]{64}$) or null | yes |
| `links` | object | yes |

No other fields are accepted.

### <a id="schema-invitation"></a>Invitation

| Field | Type | Required |
| --- | --- | --- |
| `delivery_id` | string (format uuid) | yes |
| `request_id` | string (format uuid) | yes |
| `status` | `queued` | yes |

No other fields are accepted.

### <a id="schema-event"></a>Event

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `type` | `request.created` \| `request.ready` \| `request.signed` \| `request.cancelled` \| `request.expired` \| `request.failed` \| `request.completed` \| `completion.failed` \| `completion.retried` | yes |
| `stream_version` | integer (minimum 1) | yes |
| `resource_version` | integer (minimum 1) | yes |
| `request_id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `occurred_at` | string (format date-time) | yes |
| `status` | `preparing` \| `pending` \| `signed` \| `cancelled` \| `expired` \| `failed` | yes |
| `completion_status` | `not_started` \| `building` \| `ready` \| `failed` | yes |

No other fields are accepted.

### <a id="schema-eventpage"></a>EventPage

| Field | Type | Required |
| --- | --- | --- |
| `events` | array of [`Event`](#schema-event) | yes |
| `next_cursor` | string (minLength 1) | yes |
| `has_more` | boolean | yes |

No other fields are accepted.

### <a id="schema-evidence"></a>Evidence

See the contract for this schema.

### <a id="schema-requestpage"></a>RequestPage

| Field | Type | Required |
| --- | --- | --- |
| `requests` | array of [`SigningRequest`](#schema-signingrequest) | yes |
| `next_cursor` | string or null | yes |
| `reconciliation_cursor` | string (minLength 1) | yes |

No other fields are accepted.

### <a id="schema-documentpreparation"></a>DocumentPreparation

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `kind` | `template` \| `plain_text` | yes |
| `request` | [`CreateRequest`](#schema-createrequest) or [`PlainTextSubmission`](#schema-plaintextsubmission) | yes |
| `renderer_version` | `"text-v1"` | yes |
| `text` | string (minLength 1, maxLength 200000) | yes |
| `byte_length` | integer (minimum 1, maximum 200000) | yes |
| `original_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `intent_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `source_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `schema_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `policy_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |

No other fields are accepted.

### <a id="schema-plaintextsubmission"></a>PlainTextSubmission

| Field | Type | Required |
| --- | --- | --- |
| `recipient` | [`Recipient`](#schema-recipient) | yes |
| `expires_in` | integer (minimum 60, maximum 2592000) | yes |
| `business_reference` | string (maxLength 200) |  |
| `policy` | [`Definition`](#schema-definition) | yes |
| `document` | object | yes |

No other fields are accepted.

### <a id="schema-preparedrequestobservation"></a>PreparedRequestObservation

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-prepared-request-observation-v1"` | yes |
| `preparation_id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `kind` | `template` \| `plain_text` | yes |
| `recovery_epoch` | string (format uuid) | yes |
| `observed_at` | string (format date-time) | yes |
| `state` | `bound` \| `not_bound_in_snapshot` | yes |
| `request` | [`SigningRequest`](#schema-signingrequest) or null | yes |
| `missing_binding_is_inconclusive` | `true` | yes |
| `no_release_authority` | `true` | yes |
| `intent_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `original_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `create_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |

No other fields are accepted.

### <a id="schema-invitationobservation"></a>InvitationObservation

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-invitation-observation-v1"` | yes |
| `tenant_id` | string (format uuid) | yes |
| `request_id` | string (format uuid) | yes |
| `invite_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `recovery_epoch` | string (format uuid) | yes |
| `observed_at` | string (format date-time) | yes |
| `state` | `queued` \| `not_queued_in_snapshot` | yes |
| `receipt` | [`Invitation`](#schema-invitation) or null | yes |
| `missing_queue_is_inconclusive` | `true` | yes |
| `no_release_authority` | `true` | yes |

No other fields are accepted.

### <a id="schema-envelopemanifest"></a>EnvelopeManifest

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-envelope-manifest-v1"` | yes |
| `id` | string (format uuid) | yes |
| `document_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `signers` | array of object | yes |

No other fields are accepted.

### <a id="schema-envelopecreate"></a>EnvelopeCreate

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `document_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `signers` | array of object | yes |

No other fields are accepted.

### <a id="schema-signingenvelope"></a>SigningEnvelope

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `manifest` | [`EnvelopeManifest`](#schema-envelopemanifest) | yes |
| `manifest_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |
| `resource_version` | integer (minimum 1) | yes |
| `status` | `pending` \| `partially_signed` \| `signed` \| `withdrawn` \| `expired` \| `incomplete` | yes |
| `completion_status` | `not_ready` \| `building` \| `failed` \| `ready` | yes |
| `complete` | boolean | yes |
| `required_count` | integer (minimum 2) | yes |
| `signed_count` | integer (minimum 0) | yes |
| `ready_count` | integer (minimum 0) | yes |
| `members` | array of object | yes |

No other fields are accepted.

### <a id="schema-envelopesubmission"></a>EnvelopeSubmission

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `policy` | [`Definition`](#schema-definition) | yes |
| `document` | object or object | yes |
| `signers` | array of object | yes |
| `expires_in` | integer (minimum 60, maximum 2592000) | yes |

No other fields are accepted.

### <a id="schema-envelopepreparation"></a>EnvelopePreparation

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-envelope-preparation-v1"` | yes |
| `id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `request` | [`EnvelopeSubmission`](#schema-envelopesubmission) | yes |
| `manifest` | [`EnvelopeManifest`](#schema-envelopemanifest) | yes |
| `manifest_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `planned_members` | array of object | yes |
| `plan_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `text` | string (minLength 1, maxLength 200000) |  |
| `byte_length` | integer (minimum 1, maximum 10485760) | yes |
| `original_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `prepare_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `intent_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `source_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `schema_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `policy_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |
| `media_type` | `"application/pdf"` |  |

No other fields are accepted.

### <a id="schema-envelopeinvitationbatch"></a>EnvelopeInvitationBatch

| Field | Type | Required |
| --- | --- | --- |
| `envelope_id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `manifest_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `state` | `"queued"` | yes |
| `invitations` | array of object | yes |

No other fields are accepted.

### <a id="schema-envelopeinvitationobservation"></a>EnvelopeInvitationObservation

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-envelope-invitation-observation-v1"` | yes |
| `envelope_id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `manifest_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `invite_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `state` | `queued` \| `not_queued_in_snapshot` | yes |
| `batch` | [`EnvelopeInvitationBatch`](#schema-envelopeinvitationbatch) or null | yes |
| `recovery_epoch` | string (format uuid) | yes |
| `observed_at` | string (format date-time) | yes |
| `missing_queue_is_inconclusive` | `true` | yes |
| `no_release_authority` | `true` | yes |

No other fields are accepted.

### <a id="schema-appinvitationhandoff"></a>AppInvitationHandoff

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-app-invitation-handoff-v1"` | yes |
| `tenant_id` | string (format uuid) | yes |
| `request_id` | string (format uuid) | yes |
| `delivery_id` | string (format uuid) | yes |
| `recipient` | [`Recipient`](#schema-recipient) | yes |
| `signing_url` | string (format uri, maxLength 2048) | yes |
| `expires_at` | string (format date-time) | yes |
| `email_delivery` | `"app_owned"` | yes |
| `invite_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `recovery_epoch` | string (format uuid) | yes |
| `state` | `"ready"` | yes |

No other fields are accepted.

### <a id="schema-appenvelopeinvitationhandoff"></a>AppEnvelopeInvitationHandoff

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-app-envelope-invitation-handoff-v1"` | yes |
| `tenant_id` | string (format uuid) | yes |
| `envelope_id` | string (format uuid) | yes |
| `manifest_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `invitations` | array of object | yes |
| `email_delivery` | `"app_owned"` | yes |
| `invite_key_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `recovery_epoch` | string (format uuid) | yes |

No other fields are accepted.

### <a id="schema-appauthenticationcontext"></a>AppAuthenticationContext

| Field | Type | Required |
| --- | --- | --- |
| `profile` | `"esign-app-auth-context-v1"` | yes |
| `app_id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `request_id` | string (format uuid) | yes |
| `session_id` | string (format uuid) | yes |
| `challenge_id` | string (format uuid) | yes |
| `binding_id` | string (format uuid) | yes |
| `expected_subject` | string (minLength 1, maxLength 200) | yes |
| `issuer` | string (format uri) | yes |
| `redirect_uri` | string (format uri) | yes |
| `client_id` | string (minLength 1, maxLength 200) | yes |
| `state_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `nonce_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `request_input_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `recipient_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `context_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `code_challenge` | string (pattern ^[A-Za-z0-9_-]{43}$) | yes |
| `code_challenge_method` | `"S256"` | yes |
| `expires_at` | string (format date-time) | yes |
| `max_auth_age_seconds` | integer (minimum 1, maximum 300) | yes |

No other fields are accepted.

### <a id="schema-signingpolicycatalog"></a>SigningPolicyCatalog

| Field | Type | Required |
| --- | --- | --- |
| `policies` | array of object | yes |
| `security_selection` | `"immutable-policy-version"` | yes |
| `email_delivery` | `"app_owned"` | yes |

No other fields are accepted.

### <a id="schema-evidencetimestamp"></a>EvidenceTimestamp

esign-timestamp-v1: an RFC 3161 timestamp over the SHA-256 of the exact evidence bytes.

| Field | Type | Required |
| --- | --- | --- |
| `schema_version` | `"esign-timestamp-v1"` | yes |
| `request_id` | string (format uuid) | yes |
| `evidence_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `authority` | string (pattern ^[a-z0-9][a-z0-9-]{0,39}$) | yes |
| `gen_time` | string (format date-time) | yes |
| `response` | string | yes |

No other fields are accepted.

### <a id="schema-documentupload"></a>DocumentUpload

Parked PDF bytes, named by SHA-256. Not a signing request.

| Field | Type | Required |
| --- | --- | --- |
| `sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `byte_length` | integer (minimum 1, maximum 10485760) | yes |
| `media_type` | `"application/pdf"` | yes |
| `expires_at` | string (format date-time) | yes |

No other fields are accepted.

### <a id="schema-pdfsubmission"></a>PdfSubmission

| Field | Type | Required |
| --- | --- | --- |
| `recipient` | [`Recipient`](#schema-recipient) | yes |
| `expires_in` | integer (minimum 60, maximum 2592000) | yes |
| `business_reference` | string (maxLength 200) |  |
| `policy` | [`Definition`](#schema-definition) | yes |
| `document` | object | yes |

No other fields are accepted.

### <a id="schema-pdfdocumentpreparation"></a>PdfDocumentPreparation

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `tenant_id` | string (format uuid) | yes |
| `kind` | `"pdf"` | yes |
| `request` | [`PdfSubmission`](#schema-pdfsubmission) | yes |
| `renderer_version` | `"pdf-v1"` | yes |
| `media_type` | `"application/pdf"` | yes |
| `title` | string (minLength 1, maxLength 200) | yes |
| `byte_length` | integer (minimum 1, maximum 10485760) | yes |
| `original_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `intent_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `source_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `schema_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `policy_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |

No other fields are accepted.

### <a id="schema-documentconversion"></a>DocumentConversion

A source file being turned into a PDF. When ready, `pdf.sha256` names an ordinary upload for `preparePdfDocument`.

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (format uuid) | yes |
| `status` | `converting` \| `ready` \| `failed` | yes |
| `source_sha256` | string (pattern ^[a-f0-9]{64}$) | yes |
| `source_media_type` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` \| `application/msword` \| `application/vnd.oasis.opendocument.text` \| `application/rtf` \| `text/html` \| `text/plain` \| `image/png` \| `image/jpeg` | yes |
| `source_byte_length` | integer (minimum 1, maximum 10485760) | yes |
| `created_at` | string (format date-time) | yes |
| `expires_at` | string (format date-time) | yes |
| `pdf` | [`DocumentUpload`](#schema-documentupload) |  |
| `reason` | `unsupported` \| `invalid` \| `timeout` \| `too_large` \| `converter_unavailable` \| `storage_unavailable` \| `worker_error` |  |

No other fields are accepted.

### <a id="schema-notice"></a>Notice

| Field | Type | Required |
| --- | --- | --- |
| `id` | string (pattern ^[a-z0-9][a-z0-9-]{2,79}$) | yes |
| `kind` | `added` \| `needs_upgrade` \| `breaking` \| `deprecated` \| `security` | yes |
| `published` | string (format date) | yes |
| `deadline` | string (format date) |  |
| `title` | string (minLength 1, maxLength 200) | yes |
| `what` | string (minLength 1, maxLength 4000) | yes |
| `who` | string (minLength 1, maxLength 1000) | yes |
| `action` | string (minLength 1, maxLength 2000) | yes |
| `minimum_sdk` | string (pattern ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}(-[0-9A-Za-z.]{1,40})?$) |  |
| `acknowledged` | boolean | yes |

No other fields are accepted.

### <a id="schema-sdkstatus"></a>SdkStatus

| Field | Type | Required |
| --- | --- | --- |
| `reported` | string (pattern ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}(-[0-9A-Za-z.]{1,40})?$) or null | yes |
| `latest` | string (pattern ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}(-[0-9A-Za-z.]{1,40})?$) | yes |
| `minimum_supported` | string (pattern ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}(-[0-9A-Za-z.]{1,40})?$) | yes |
| `status` | `current` \| `supported` \| `unsupported` \| `unknown` | yes |

No other fields are accepted.

### <a id="schema-noticelist"></a>NoticeList

| Field | Type | Required |
| --- | --- | --- |
| `sdk` | [`SdkStatus`](#schema-sdkstatus) | yes |
| `notices` | array of [`Notice`](#schema-notice) | yes |

No other fields are accepted.

### <a id="schema-compatibility"></a>Compatibility

| Field | Type | Required |
| --- | --- | --- |
| `api_version` | string (pattern ^[0-9]+\.[0-9]+\.[0-9]+$) | yes |
| `sdk` | [`SdkStatus`](#schema-sdkstatus) | yes |
| `notices` | object | yes |

No other fields are accepted.
