# eDocInk: all guides Source: https://edocink.com. Operated by runMast LLC. The OpenAPI contract is at https://edocink.com/openapi.json. # eDocInk eDocInk is a signing API for applications. Your app decides what is signed and who signs it. eDocInk freezes the document, hosts the signing pages, records consent and hands back signed evidence that your app can verify on its own. eDocInk is run by runMast LLC. It is in pilot: the sandbox is open by request, and production access follows a short go-live review. ## At a glance | | | | --- | --- | | **Cost** | The sandbox is free. Production is free for pilot customers; pricing will be published before general availability. | | **Getting a key** | Request sandbox access at [/access](/access) and confirm by email. Guest-signing credentials usually arrive within a few minutes. Agents can ask for their developer through `POST /api/access`. | | **Smallest integration** | Four calls to send a document, one to check it, one to verify it. See the [quick start](/agents#quick-start-the-smallest-safe-integration). | | **What you get that others don't** | Evidence your app can verify on its own, with keys it pins, that anyone else can check against our [published keys](/evidence-keys.json) (which means trusting us for the key list), plus an independent timestamp that needs no trust in us. | ## How it works 1. **Prepare.** Your server sends the document text. eDocInk returns the exact text that will be signed and its SHA-256. 2. **Create and invite.** Your server creates a signing request and gets a single-use signing link for each signer. 3. **Deliver.** Your app sends the link, by email or in-app, under your own name. eDocInk sends no email. 4. **Sign.** The signer reviews the document on a hosted page (which can carry the business's name, logo and colour if you send them to us), agrees to the consent text and signs. 5. **Verify.** Your app learns the outcome by webhook or event feed, fetches the evidence and verifies it against public keys it has pinned. ## What eDocInk does, and what your app does | eDocInk | Your application | | --- | --- | | Freezes the exact document text and its SHA-256 | Decides what the document says and who may send it | | Hosts review, consent and signature pages | Decides who signs, and delivers each signing link | | Shows the business's branding on the signing pages, once the operator has set it | Sends the email or in-app message | | Records consent and how the link was used | Updates its own records when something is signed | | Signs evidence for every signature (Ed25519) | Verifies the evidence and keeps it | | Isolates every app and business from every other | Keeps its API key on its server only | ## Good to know - **Server to server.** Every call is HTTPS with a bearer key and a tenant id. Keys never go to a browser or phone. - **Safe retries.** Every POST takes an idempotency key, so a timeout never creates a duplicate. - **Several signers.** Envelopes collect every required signature on one document. - **Documents:** plain text up to 200,000 bytes (about 30,000 words), PDFs up to 10 MiB, or operator-published templates. Word, OpenDocument, RTF, HTML, text and image files convert to PDF first. - **Independent timestamps.** An outside timestamp authority (DigiCert) timestamps the evidence for every signature. That fixes when the evidence existed, from a source independent of your app and of us. Live in the sandbox and production. - **Staying current.** Your app reads what changed from the API itself (notices and a compatibility check), and the [changelog](/changelog) lists every release. - **Not yet:** identity proofing of guest signers. A guest email link proves control of the link, nothing more. ## Get started - [Get access](/access): request sandbox credentials. - [Guides](/guides): integration requirements, API reference, OpenAPI file, changelog. - [For AI agents](/agents): a step-by-step guide an agent can follow to connect an app. - [Demo](/demo/): a working app built on eDocInk (passcode required). - [Feedback](/feedback): tell us what was unclear, broken or missing. --- # eDocInk agent guide: connect an application This guide is written for AI coding agents (and the developers working with them). Follow it step by step to add document signing to an application through the eDocInk API. It summarises the [integration requirements](https://edocink.com/guides/integration-requirements.md) and the [API reference](https://edocink.com/guides/api-reference.md); where they differ, those two documents win. The machine-readable contract is [openapi.json](https://edocink.com/openapi.json). ## Quick start: the smallest safe integration For a small app with one signer per document, this is all you need. Everything after it in this guide adds robustness (webhooks, several signers, full recovery) you can grow into. 1. **Store three things** in your database: each POST's idempotency key (written before you send), the `original_sha256` of the prepared document, and the SHA-256 of each signing link's `invitation` parameter. 2. **Send:** prepare the text, create the request, create an invitation and read its hand-off (section 4, steps 2 to 4). You get a `signing_url`. 3. **Deliver** the link yourself: an email from your app, or a button on your own page. 4. **Check:** when the signer comes back to your app, or on a timer, call `GET /api/v1/requests/{id}` until it is `signed` and its completion is `ready`. No webhook endpoint is needed. 5. **Verify:** fetch the evidence and verify it (section 7). In Node, that is one call to the SDK's `verifyGuestPlainTextEvidence`. Only then mark the document signed. You can skip webhooks, the event feed, envelopes and templates. Do not skip idempotency keys or evidence verification: they are what make the result trustworthy. ## 0. Rules you must not break - The API key is a **server-side secret**. Never put it in browser or mobile code, logs, test snapshots, commits or prompts. Load it from the app's secret store. - **Save every idempotency key before sending its POST.** After a timeout, recover with the same key. Never invent a new key to "try again". - **Do not treat a document as signed until its evidence verifies** against pinned public keys and the app's own records. - Signing links grant access to sign. Store them only as long as needed to deliver them, and never log them. - eDocInk sends **no email**. The application delivers each signing link itself. ## 1. Ask the human for these (do not guess them) If the developer has no credentials yet, request them on their behalf with `POST https://edocink.com/api/access` (see [Get access](https://edocink.com/access.md)), using **their** email address, and tell them to open the confirmation email. Guest-signing credentials then arrive in their inbox, usually within a few minutes; they are shown to them once and you never see them unless they put them in configuration. Keep building against the contract meanwhile. Ask the developer for the values they received, and store them as server-side configuration: | Setting | Example | Secret? | | --- | --- | --- | | `EDOCINK_ORIGIN` | the sandbox base URL they were given | no | | `EDOCINK_APP_ID` | uuid | no | | `EDOCINK_TENANT_ID` | uuid, sent as `X-Tenant-ID` | no | | `EDOCINK_API_KEY` | bearer key | **yes** | | `EDOCINK_POLICY` | `guest@1` (name and version) | no | | `EDOCINK_EVIDENCE_PUBLIC_KEYS` | JSON map of key id → Ed25519 public key | no, but pinned | | `EDOCINK_WEBHOOK_KEYS` | key id → secret, only if webhooks are configured | **yes** | Also ask: who signs (one person, or several who must all sign), how the app will reach signers (its email provider or an in-app inbox), and whether the app has a public HTTPS endpoint for webhooks. If you cannot get credentials, build against the contract and leave the integration switched off. ## 2. Choose a client - **Node 24+:** use the SDK `@esign/integration-hooks` (an archive; email info@edocink.com for it, it is not in the credentials email). It implements idempotent calls, recovery, webhook verification (`receiveWebhookOnce`) and evidence verification (`verifyGuestPlainTextEvidence`, `verifyGuestEnvelopeEvidence`, `verifyPdfEvidence`). Prefer it. Call `checkCompatibility()` at startup and log what it says; the SDK also logs each new notice from eDocInk once. - **Any other language:** call the HTTPS API directly from [openapi.json](https://edocink.com/openapi.json), and implement evidence verification with an Ed25519 and SHA-256 library, following section 9 of the integration requirements. Every call sends: ``` Authorization: Bearer $EDOCINK_API_KEY X-Tenant-ID: $EDOCINK_TENANT_ID Content-Type: application/json (on POST) Idempotency-Key: (on every POST) ``` ## 3. Add storage first Create these records in the application's own database (names are suggestions): - `signature_requests`: app record id, eDocInk preparation id, request id, status, `original_sha256` and the exact inputs sent, latest `resource_version`. - `signature_operations`: one row per POST with its idempotency key, written **before** the POST is sent, and its outcome after. - `signature_links`: request id, signer, invitation key, the **SHA-256 of the link's `invitation` query parameter**, expiry. Keep every digest ever issued for a signer. - `signature_events`: processed webhook `Esign-Event-ID`s, or the event-feed cursor. - `signature_evidence`: the verified evidence bundle. ## 4. Send a document to one signer 1. `GET /api/v1/signing-policies` and check the configured policy is listed. 2. `POST /api/v1/text-document-preparations` with: ```json { "policy": {"name": "guest", "version": 1}, "document": {"title": "Service agreement", "body": "The full text to be signed."}, "recipient": {"email": "pat@example.com", "display_name": "Pat Example"}, "expires_in": 604800 } ``` Optional: `business_reference` (up to 200 characters) to link it to your record. The response's `text` is exactly what will be signed and `original_sha256` is its hash. Store both. A preparation expires after 10 minutes. 3. `POST /api/v1/document-preparations/{preparation_id}/requests` with body `{}`. The request starts `preparing` and becomes `pending` within a second or two. 4. `POST /api/v1/requests/{request_id}/invitations` with body `{}` and a new invitation key. Then `GET /api/v1/requests/{request_id}/invitation-handoff` with header `X-Original-Invite-Key: `. The response has `signing_url` and `expires_at`. A **409** means the request is still preparing: wait briefly and repeat the same GET. 5. Record the SHA-256 of the `invitation` query parameter of `signing_url`, then deliver the link to the signer. Links last 72 hours (never beyond the request) and work once; opening one starts a 15-minute signing session. ## 5. Several signers who must all sign `POST /api/v1/envelope-preparations` with the document and 2 or more signers (each with `slot_id`, `role` and `recipient`), then `POST /api/v1/envelope-preparations/{id}/envelope`, then `POST /api/v1/signing-envelopes/{id}/invitations` and its `invitation-handoff` for one link per signer. Track with `GET /api/v1/signing-envelopes/{id}` and verify the evidence for every member request once it is complete. ## 6. Learn what happened - **Event feed (always available):** `GET /api/v1/events?after=&limit=100`. Save the cursor after each page. - **Webhooks (optional):** verify `Esign-Signature` as HMAC-SHA256 over `..` in constant time, reject timestamps more than 5 minutes off, skip event ids already processed, answer 2xx within 10 seconds. Treat each event as a prompt to re-read the request (`GET /api/v1/requests/{id}`) and act on its current state. ## 7. Verify evidence before marking anything signed When the request is `signed` and its completion is `ready`, call `GET /api/v1/requests/{id}/evidence` and verify: - the Ed25519 signature against the **pinned** public keys (never keys from the bundle); - the document hash against the stored `original_sha256`; - the policy and consent against what the app chose; - for guest links, `credential_digest` against **one of the link digests the app recorded** for that signer. Only then mark the document signed and store the bundle. If anything fails, do not mark it signed; flag it for a person. ## 8. Handle errors by status code | Status | Do this | | --- | --- | | 400, 413, 415 | Fix the request; do not retry unchanged | | 401 | Key unknown, expired or revoked: stop and tell the human | | 403 | Key lacks a scope: tell the human | | 404 after a timeout | Inconclusive: recover with the original key | | 409 | Not ready or not allowed in this state: re-read, then retry only if it can change | | 410 | Cursor expired: restart the scan and reconcile | | 412, 428 | Re-read and send the current `If-Match` | | 429, 503 | Wait for `Retry-After`, retry with the same key | ## 9. Prove it works in the sandbox Write tests (against the sandbox, never production) that show: 1. A document is prepared, sent, signed by following the link, and its evidence verifies. 2. A simulated timeout on each POST recovers the original result with no duplicate. 3. Reissuing a link makes the old link fail and the new one sign. 4. A tampered evidence bundle is refused. 5. The sixth link in an hour (429) and a still-preparing request (409) are handled. 6. Cancelling (`POST /api/v1/requests/{id}/cancel`) sends a fresh `If-Match: ""` from the latest read. Then work through the go-live checklist in section 12 of the integration requirements and hand the results to the human, who sends them to runMast for production access. ## 10. Tell us what went wrong If a guide was unclear, wrong or missing something, or the API did not behave as described, report it so the guides can be fixed for the next agent. Ask the human first if your environment requires approval for outbound requests. ``` POST https://edocink.com/api/feedback Content-Type: application/json { "kind": "unclear", "page": "/agents#4-send-a-document-to-one-signer", "message": "What you expected, what happened, and what would have helped.", "contact": "", "agent": "the agent or tool name" } ``` `kind` is one of `unclear`, `api`, `missing`, `agent` or `other`. `contact` is an optional email for a reply. The answer is `202 {"status":"received"}`. **Never include API keys, signing links, evidence bundles or real personal data.** People can use the form at https://edocink.com/feedback. ## Where to find more - Overview: https://edocink.com/index.md - Access: https://edocink.com/access.md - Integration requirements: https://edocink.com/guides/integration-requirements.md - API reference: https://edocink.com/guides/api-reference.md - OpenAPI 3.1 contract: https://edocink.com/openapi.json - Changelog: https://edocink.com/changelog.md (feed: https://edocink.com/changelog.atom) - Everything in one file: https://edocink.com/llms-full.txt - Feedback: https://edocink.com/feedback --- # Getting access to eDocInk Every application starts in the **sandbox**, a separate copy of the service with its own keys and data. Nothing signed there is binding. The sandbox is free, and production is free for pilot customers. Sandbox credentials for guest signing are created automatically, usually within a few minutes of confirming your email. Production credentials follow once the go-live checklist passes in the sandbox. ## 1. Request sandbox access Use the form at https://edocink.com/access. We email you a confirmation link that works for one hour. Once you confirm, guest-signing credentials are created automatically and we email you a link to view them **once**, usually within a few minutes. Requests for account sign-in through your own identity provider are set up by a person, usually within two working days. The request asks for: - your name, email and company; - the application's name and what it will use signatures for; - the signing method: **guest email link** (anyone with the link), or **account sign-in** through your own identity provider; - expected volume per month; - the consent wording signers should agree to, if you have it; - a webhook URL, if you want push notifications (optional; the event feed always works). ### For AI agents: request access for your developer An agent can send the same request as JSON. Use the email of the person you work for: they must open the confirmation link, and the credentials go to them, never to you. ``` POST https://edocink.com/api/access Content-Type: application/json { "name": "Pat Example", "email": "pat@example.com", "company": "Example Walks", "app_name": "Example Walks booking", "use_case": "Clients sign our service agreement before their first walk.", "methods": ["guest"], "agent": "the agent or tool name" } ``` The answer is `202 {"status":"confirmation_sent"}`, or `400`/`409`/`429` with `{"errors": [...]}`. Requests need a real, permanent email address, plain words (no links or HTML), and are limited per network and per email domain each day. You can also email [info@edocink.com](mailto:info@edocink.com). ## 2. What you receive, privately | Item | Use | | --- | --- | | `origin` | Sandbox base URL: `https://esign-sandbox.runmast.com` | | `app_id`, `tenant_id` | Your app and tenant. Send the tenant as `X-Tenant-ID` on every call. | | API key, scopes, expiry | `Authorization: Bearer …`. Server-side only. Sandbox keys last 30 days; ask for a new one before then. | | Signing policy name and version | Chosen per document, e.g. `{"name":"guest","version":1}` | | Evidence public keys | Pin these in configuration to verify evidence. They are also published at [/evidence-keys.json](/evidence-keys.json) | | SDK archive (`@esign/integration-hooks`) | Optional Node 24+ client with the evidence and webhook verifiers. Email info@edocink.com for it. | | Webhook key id and secret | Only if you gave a webhook URL | Branding (the business's display name, colour and logo on the signing pages) is optional and set by the operator for each tenant; without it the pages carry a neutral "Document signing" heading. Send a PNG, JPEG or WebP logo up to 64 KiB. ## 3. Build and test in the sandbox Follow the [integration requirements](/guides/integration-requirements) and the [API reference](/guides/api-reference). Coding agents can follow the [agent guide](/agents). ## 4. Go live Complete the go-live checklist (section 12 of the integration requirements) in the sandbox and email info@edocink.com. After a review you receive production credentials: a new origin, keys, policy and evidence keys. Sandbox evidence keys are **not** production's. --- # Integration requirements What an application needs, and must do, to use the eDocInk service. Read this before the [API reference](/guides/api-reference). It describes eDocInk API v1 (the OpenAPI contract's `info.version` versions this documentation; the API itself is `/api/v1`). Some headers and schema names still say `esign`/`Esign` from the product's earlier name; they are part of v1 and will not change. ## 1. What the service does, and what your app does | The eDocInk service | Your application | | --- | --- | | Freezes the exact document text and its SHA-256 | Decides what the document says, and that the person sending it may send it | | Hosts the signing pages: review, consent, signature | Decides who must sign, and gets each signing link to the right person | | Shows each business's name, logo and colour on the signing pages (set by the operator) | Sends the operator the business's display name, accent colour and logo | | Checks the signer's link (or account sign-in) and records consent | Sends the email or in-app message with the link (the service sends no email) | | Tells you what happened: event feed and signed webhooks | Updates its own records when a document is signed, expires or is withdrawn | | Produces signed evidence for each signature | Verifies that evidence against its own records and keeps it | | Isolates every app and tenant from every other | Keeps its own keys secret and its own copies under its own retention rules | The service never sees your database and you never see its database. Everything goes through the HTTPS API. **What the service does not do today:** - send email; - produce PDFs or rich layouts (documents are plain text or simple templates); - send the signer back to your app after signing (the last page says they can close the tab; learn the outcome by webhook or event feed, see section 8); - prove a guest signer's identity (an email link proves control of the link, nothing more). ## 2. Prerequisites 1. **A server-side component** that can make HTTPS calls and hold secrets. The API key must never reach a browser, mobile app or log. 2. **Durable storage** you control: a database table or two (see section 6). 3. **A way to reach signers**: an email provider or an in-app inbox. 4. **Either** the SDK (`@esign/integration-hooks`, Node 24+; it includes the evidence and webhook verifiers) **or** your own HTTPS client plus an Ed25519/SHA-256 library. The SDK is strongly recommended. It implements sections 6–9 for you. It is supplied as an archive on request (it is not part of the credentials); without it, section 9 gives the exact verification steps. 5. **Optional:** a public HTTPS endpoint for webhooks. Without one, poll the event feed. ## 3. Getting access Ask the service operator for access with: app name, owner contact, expected volume, the signing methods you need (guest email link, or account sign-in with your identity provider), the consent wording, and your webhook URL if any. You receive, privately, **per environment** (sandbox first, then production): | Item | Use | | --- | --- | | `origin` | Base URL: `https://esign-sandbox.runmast.com` for the sandbox; production's is given with production access | | `app_id`, `tenant_id` | Your app and tenant. Send the tenant as `X-Tenant-ID` on every call. | | API key, its scopes and expiry | `Authorization: Bearer …`. Keys expire (at most 366 days). Rotate before expiry: the operator issues the new key, you deploy it, then the old one is revoked. | | Signing policy name and version | Chosen per document, e.g. `{"name":"guest","version":1}`. The operator publishes it with the consent wording you agreed and the signing method. Policies are immutable; changes get a new version. | | Evidence public keys | A map of key id to Ed25519 public key (unpadded base64url of the raw 32 bytes). Pin them in configuration; never fetch them from the evidence itself. | | Webhook key id and secret (optional) | Verifies webhook signatures | Scopes, by what you do: `documents:prepare` and `documents:submit` (prepare documents and read policies), `requests:create`, `requests:read`, `invitations:create` (signing links), `evidence:read`, `requests:cancel` (cancel/withdraw), `events:read` (event feed). ## 4. The calls, in order ### One signer 1. `GET /api/v1/signing-policies`: confirm the policy you will use is published. 2. `POST /api/v1/text-document-preparations` (or `/document-preparations` for a template): the service returns the **exact rendered text** and its `original_sha256`. Show this text to the person sending it if your workflow needs a review. What they see is byte-for-byte what will be signed. A preparation expires after 10 minutes. 3. `POST /api/v1/document-preparations/{id}/requests`: creates the signing request. It starts `preparing` and becomes `pending` once the service has frozen the document (normally a second or two). 4. `POST /api/v1/requests/{id}/invitations`: issue a signing link. Then `GET /api/v1/requests/{id}/invitation-handoff` with `X-Original-Invite-Key` returns the `signing_url`. A 409 here usually means the request is still `preparing`: wait briefly and retry the same GET. 5. Deliver the link (section 7). 6. Learn the outcome by webhook or `GET /api/v1/events` (section 8). 7. When the request is `signed` and its completion is `ready`: call `GET /api/v1/requests/{id}/evidence` and verify it (section 9). Cancel with `POST /api/v1/requests/{id}/cancel` and `If-Match: ""` from a fresh read. ### Several signers who must all sign (envelope) 1. `POST /api/v1/envelope-preparations` with the document and 2 to 20 signers (each with a `slot_id`, `role` and recipient). 2. `POST /api/v1/envelope-preparations/{id}/envelope`: creates one request per signer. 3. `POST /api/v1/signing-envelopes/{id}/invitations`, then `GET …/invitation-handoff`: one signing link per signer. 4. Track with `GET /api/v1/signing-envelopes/{id}` (`signed_count`, `complete`) or events. Fetch and verify evidence for each member request once complete. 5. To replace **one** signer's link, call the single-request `POST /api/v1/requests/{member_request_id}/invitations` with a new key. That revokes only that signer's earlier link. 6. Withdraw the whole envelope with `POST /api/v1/signing-envelopes/{id}/withdraw` and `If-Match: ""` (the version is in the body; envelopes send no ETag). `POST /api/v1/signing-envelopes` (building an envelope from requests you already created) is a low-level path. Each member request must have been created with `business_reference` = `env::`. Use the prepared flow above unless you have a specific reason not to. ### A PDF document A PDF follows the same steps; only the preparation differs. 1. `POST /api/v1/document-uploads` with the raw PDF as the body, `Content-Type: application/pdf`, up to 10 MiB (scope `documents:submit`). The service checks only that it looks like a PDF (`%PDF-` header, `%%EOF` trailer) and returns `{sha256, byte_length, media_type, expires_at}`. Uploading the same bytes again returns the same answer, so this call takes no `Idempotency-Key`; on a timeout, just upload again. An upload lasts 24 hours; at most 200 live uploads per app and tenant. 2. Check that `sha256` is the SHA-256 of the bytes you sent, and store it. 3. `POST /api/v1/pdf-document-preparations` with the same body as a plain-text preparation, except `document` is `{title, sha256}`. The response has `media_type`, `byte_length` and `original_sha256` (equal to the upload's `sha256`) and no `text`. For several signers, send `document: {title, sha256}` to `POST /api/v1/envelope-preparations` instead. 4. Continue at step 3 of the one-signer flow (or step 2 of the envelope flow). The signer sees the PDF in their browser's own viewer on the signing page, with an "Open the PDF in a new tab" link that works everywhere, including Android. They accept the whole document; phase 1 has no signature boxes or form fields, and the service does not stamp or sign the PDF itself. Your signing policies cover PDFs with no change. `GET /api/v1/requests/{id}/original` (scope `requests:read`) returns the exact bytes the signer reviewed, for text or PDF. ### Word, HTML, text or an image: convert it to PDF first 1. `POST /api/v1/document-conversions` with the raw file and its `Content-Type`: `.docx`, `.doc`, `.odt`, `.rtf`, `text/html`, `text/plain`, `image/png` or `image/jpeg`, up to 10 MiB (scope `documents:submit`). The answer is `202` with an `id` and `status: "converting"`. Sending the same file again returns the same conversion, so this call takes no `Idempotency-Key`. At most 50 conversions per hour per app and tenant. 2. Poll `GET /api/v1/document-conversions/{id}` every second or two (a conversion normally takes under 10 seconds) until `status` is `ready` or `failed` (`reason` says why). 3. `GET /api/v1/document-conversions/{id}/pdf` and **look at the PDF before sending it**. It is what the signer will see and sign. Fonts and page breaks can differ from the program that made the file. 4. Prepare it as a PDF: `document: {title, sha256}` with the conversion's `pdf.sha256`, then continue as for any PDF. The service converts in a sandbox with no network access, so remote images in HTML are not loaded; embed images or use a PDF you render yourself. The evidence binds the PDF only; keep your source file if you need it, linked by the conversion's `source_sha256`. Conversion is off unless the operator enables it; until then the first call answers 503. ## 5. Idempotency and recovery (required) - Every POST takes an `Idempotency-Key`. **Write the key to your database before you send the request.** If you crash or time out, you will know which key to recover with. - Same key and same body: you get the original result, never a duplicate. Same key and a different body: 409. - **Unknown outcome** (timeout, connection reset, 5xx): first ask with the matching read, which takes the original key: `GET …/document-preparations/{id}/requests` with `X-Original-Create-Key`, `GET …/invitations` with `X-Original-Invite-Key`, or `GET …/envelope-preparations/{id}` with `X-Original-Prepare-Key`. If nothing is found, retry the POST with the **same** key. Never mint a new key to "try again". - A new signing link is the one case where you *want* a new key: each new invitation key issues a new link and revokes the previous one for that request. ## 6. What your app must store | Record | Why | | --- | --- | | Each idempotency key, saved before its POST | Recovery without duplicates (section 5) | | Request and envelope ids; for envelopes, the slot → request id map | Every later call | | The prepared text's `original_sha256` and the inputs you sent | Evidence verification compares against these | | **Every signing-link digest you issue, per signer** (SHA-256 of the link's `invitation` token) | Evidence records the digest of the link actually used. After a reissue it may be any of them. Verify against your own recorded set, never against a value taken from the evidence. | | The latest `resource_version` you read | `If-Match` for cancel and withdraw | | Processed webhook `Esign-Event-ID`s, or your event-feed cursor | Deduplication; resuming the feed | | The verified evidence bundle | Your record of the signature | Store signing links themselves only as long as you need to deliver them; they grant access to sign. ## 7. Delivering signing links - A link lives **72 hours** and never longer than the request. It works once: opening it starts a 15-minute signing session. - **Optional "Continue" pattern:** email a link to *your* app. On GET, show a Continue button and change nothing, because email scanners open links. On POST, reuse the current link if the handoff still returns it; otherwise issue a new one with a new key and redirect to its `signing_url`. - At most **5 links per signing request in any rolling hour** (the 6th is 429). A request has one signer, so this is also per signer. Each new link revokes the last one, and any open signing session with it. - Tell signers who is asking and why. The signing page shows the document title, who requested it (tenant and app; with branding set, the tenant's name, colour and logo, otherwise a neutral "Document signing" heading), who the link was sent to, the document and the consent text. ## 8. Knowing what happened - **Webhooks** (optional): POSTed to your HTTPS endpoint with `Esign-Event-ID`, `Esign-Delivery-ID`, `Esign-Timestamp`, `Esign-Key-ID` and `Esign-Signature`. To verify one: - Compute HMAC-SHA256 over `..`. - Compare it with the signature in constant time. - Reject timestamps more than 5 minutes off. - Ignore event ids you have already processed. - Answer 2xx within 10 seconds. Failed deliveries are retried for up to 72 hours. Order is not guaranteed. The SDK's `receiveWebhookOnce` does all of this. - **Event feed**: `GET /api/v1/events?after=&limit=100`, oldest first. Keep the cursor. It's always available, and is the fallback if webhooks are missed. - There is no return URL: after signing, the signer is told they can close the tab. If your page waits for them, poll `GET /api/v1/requests/{id}` (every 5-10 seconds while they are signing, never faster) or listen for the webhook. - Either way, treat an event as a prompt to re-read the request or envelope. Act on its current state. ## 9. Verifying evidence (required before you rely on a signature) Evidence is a JSON bundle signed by the service with Ed25519. Before treating a document as signed, verify the bundle with the SDK (`verifyGuestPlainTextEvidence`, `verifyPlainTextEvidence`, or `verifyGuestPlainTextEnvelopeEvidence` for envelopes): - its signature, against your **pinned** public keys; - the document hash, against the `original_sha256` you stored; - the policy and consent text, against what you chose; - for guest links, `credential_digest` against **one of the link digests you recorded** for that signer. For a PDF, use `verifyPdfEvidence(raw, expected, keys, pdfBytes)` with `expected.document` set to `{title, sha256, byte_length}`; passing the PDF bytes makes it check their hash too. For a guest PDF envelope, `verifyGuestEnvelopeEvidence({record, envelope, invitationDigests, bundles, original: pdfBytes}, keys)` checks every member the same way (SDK 0.33.0-alpha.1 or later). A converted PDF needs no separate upload: send the conversion's `pdf.sha256` as `document.sha256` within 24 hours of creating the conversion. Each member request keeps its own copy, which `GET /api/v1/requests/{id}/original` returns after the conversion has expired. From the command line: `python -m esign.evidence verify bundle.json --keys keys.json --original agreement.pdf`. If anything does not match, do not treat the document as signed; investigate. **Without the SDK.** Do every step; stop at the first failure. All hashes are lowercase hex SHA-256. 1. Parse the bundle as strict JSON (UTF-8, at most 4 MiB) and keep the exact bytes you received. 2. `verification.algorithm` is `Ed25519` and `verification.key_id` equals `manifest.attestation_key_id` and is one of your pinned key ids. 3. Decode the pinned key (unpadded base64url, 32 bytes). SHA-256 of those raw 32 bytes equals `manifest.attestation_key_sha256`. 4. Canonicalise `manifest` with RFC 8785 (JCS). Its SHA-256 equals `manifest_sha256`. Every number in a manifest is an integer within ±2^53-1. 5. Decode `verification.signature` (unpadded base64url, 64 bytes). It is an Ed25519 signature over the bytes `esign-evidence-v2` + one NUL byte (`0x00`) + the canonical manifest bytes, for guest bundles (`esign-evidence-v1` for account sign-in). It is not a signature over the `manifest_sha256` string. 6. `request_id`, app, tenant and recipient email are the ones you sent. The definition (`manifest.request.definition_name` and `definition_version`, repeated in `manifest.definition` and `manifest.acceptance.definition`) equals the `definition` returned when you created the request. For plain text it is a per-document name such as `submitted-text-…`, **not** your signing policy's name: the policy appears only by its content, in `manifest.request.frozen_policy.signing`. 7. The document hash: SHA-256 of the UTF-8 bytes of `title + "\n\n" + body`, exactly as returned at preparation, equals the `original_sha256` you stored and the `original_sha256` in the signature, review and acceptance. For a PDF it is the SHA-256 of the PDF bytes you uploaded: `manifest.original` has `renderer_version` `pdf-v1`, `media_type` `application/pdf`, `sha256` and `byte_length`, and **no `content`** (the PDF is not inside the bundle). Check it against your own copy of the file. 8. `credential_digest` equals SHA-256 of the UTF-8 bytes of the `invitation` query parameter of a `signing_url` you issued for this request (record that digest when you receive each link). 9. `frozen_policy.signing.consent_version` and `consent_text` are the ones in your policy. 10. The audit-event hash chain, `manifest.audit_prefix`: three events, in order, from an app key, the worker and the signer session (`actor_kind` `app_key`, `worker`, `signer_session`). Start with `previous` set to 64 zeros. For each event: - `previous_hash` equals `previous`; - `event_hash` is the SHA-256 of the bytes of `previous` (as ASCII hex), then the base64-decoded `body_base64`, then the actor: the `actor_id` for the first event, `worker:` + `actor_id` for the second, `signer:` + `actor_id` for the third; - then set `previous` to `event_hash`. 11. `manifest.request.input_digest` is the SHA-256 of the request you sent: compact JSON with sorted keys and no ASCII escaping (`{"body":…,"method":"POST","path":…}`, UTF-8), where `body` is your create-request body and `path` is `/api/v1/requests` or `/api/v1/document-preparations/{id}/requests`. Only your app can recompute it, from the body it sent. It is plain sorted JSON, not RFC 8785. 12. The completion receipt, `manifest.completion`. `content` must equal exactly these fields copied from the manifest: - `schema_version`: `esign-completion-v2` for guest bundles, `esign-completion-v1` for account sign-in; - `scope`: `manifest.scope`; - `signature_id`, `signed_at`, `original_sha256`, `consent_version`, `declared_name`, `issuer`, `subject`: from `manifest.signature` (`signature_id` is its `id`); - `accepted_version`: `manifest.acceptance.resource_version`; - guest bundles only: `authentication_method`, set to `email-link`. `sha256` is the SHA-256 of the RFC 8785 bytes of `content`, and `byte_length` is the length of those bytes. The SDK also checks that the timestamps are in order. If you skip any step, say so in your own records. **`completion_status: "building"` inside the bundle is expected.** `manifest.acceptance` and the third audit event record the request as it was at the moment of signing, when the completed record was still being built. The bundle you fetch is the result of that build. Fetch it only once the request's completion is `ready`. **Which environment signed it.** `manifest.attestation_key_id` names the key. The public evidence keys for each environment, current and retired, are published at `https://edocink.com/evidence-keys.json`. A bundle signed by a sandbox key comes from the sandbox, where nothing signed is binding. Keys are never removed from that list. A rotated key stays, marked `retired`, so old evidence keeps verifying. **Checking evidence you did not create.** Someone outside the app, such as an auditor, a court expert or the signer, can check the signature (steps 2–5) against the published keys rather than a key the app hands over. The document hash (step 7) and the timestamp below need nothing from the app. Steps 6, 8, 9 and 11 compare against the app's own records, so ask the app for them. The published list comes from eDocInk, so it is independent of the app but not of eDocInk. The timestamp is the part that is independent of both. Evidence is the service's attestation. It is not a signed PDF. Its `assurance` text says "no independent timestamp" because the bundle itself contains none; the independent timestamp below is a separate document over the bundle's bytes. **Independent timestamp (optional, recommended).** Shortly after evidence is ready, an outside Time Stamp Authority timestamps the SHA-256 of the exact evidence bytes. `GET /api/v1/requests/{id}/evidence/timestamp` returns it (409 until it exists, so retry later; never hold up your own flow for it). Keep it with the evidence. To check it, confirm `evidence_sha256` is the SHA-256 of the evidence bytes you stored, base64-decode `response` to `timestamp.tsr`, and verify it with any RFC 3161 tool against the TSA root you pinned (DigiCert Trusted Root G4, in the sandbox and production), for example `openssl ts -verify -data evidence.json -in timestamp.tsr -CAfile tsa-root.pem`. Use OpenSSL 3. The `openssl` built into macOS is LibreSSL, and it reports `Verification: FAILED` for valid tokens. Install OpenSSL 3 with `brew install openssl@3` and run `$(brew --prefix openssl@3)/bin/openssl`. Get the root from DigiCert, not from the token or from eDocInk: `https://cacerts.digicert.com/DigiCertTrustedRootG4.crt.pem`. It is also in the macOS, Windows and Mozilla root stores. Its SHA-256 fingerprint is `55:2F:7B:DC:F1:A7:AF:9E:6C:E6:72:01:7F:4F:12:AB:F7:72:40:C7:8E:76:1A:C2:03:D1:D9:D2:0A:C8:99:88`. It proves the evidence existed no later than `gen_time`, independently of the service. It does not prove who signed or that a signing took place. Anyone can timestamp any bytes, so the timestamp only fixes when these exact bytes existed. ## 10. Errors and limits Branch on the HTTP status, never on the message text. | Status | Do this | | --- | --- | | 400, 413, 415 | Fix the request | | 401 | The key is unknown, expired or revoked: rotate | | 403 | The key lacks the scope: ask the operator | | 404 | Not visible. After a timeout this is *inconclusive*, not proof of absence. | | 409 | Not allowed in the current state (often "not ready yet"), or the same key with a different body. Re-read first. | | 410 | A list or event-feed cursor expired, or the service history was restored: restart the scan and reconcile with your records | | 412 / 428 | Re-read and send the current `If-Match` | | 429, 503 | Wait for `Retry-After`; retry with the same key | Limits: - 5 links per signing request in any rolling hour. - 100 unexpired preparations per app and tenant (each lasts 10 minutes), plus 100 unexpired envelope preparations. - 1,000 open requests (preparing or pending) per app and tenant, and 60 new requests per minute. Each envelope signer counts as one request. Ask the operator if you need more. - 2 to 20 signers per envelope. - Recipient email: a plain ASCII address such as `name@example.com`, with no display name. - `expires_in` from 60 seconds to 30 days. - Page size up to 100. - Request bodies up to 1 MiB, except text and envelope preparations (2 MiB) and a PDF upload or conversion (10 MiB). - Plain-text title up to 200 characters; the document (title, two newlines, body) up to 200,000 UTF-8 bytes, about 30,000 words. Longer documents go as a PDF (413 tells you so). Evidence for a document over 10,000 characters needs SDK 0.31.0-alpha.1 or later. ### Staying current: notices and compatibility The service tells your app about changes itself; you don't need to watch a mailing list. - Every successful API response carries `eDocInk-Notices: ; latest=""` while your app has notices it has not acknowledged. SDK 0.32 and later log one line per new notice. - `GET /api/v1/notices` lists the notices that apply to your app, each with what changed, who it affects, what to do and, when an upgrade is involved, the minimum SDK. Which notices apply depends on the SDK version your app reports (SDK 0.32 sends `User-Agent: edocink-sdk/`); an app that reports none sees every notice. - `POST /api/v1/notices/{id}/acknowledge` marks one handled for the whole app. It is idempotent. - `GET /api/v1/compatibility` returns the API version and whether your SDK is `current`, `supported` or `unsupported`. Call it at startup (`checkCompatibility()` in the SDK) and alert someone when it says to upgrade. - While an operation you call, or the SDK version you report, is being retired, responses also carry `Deprecation` (RFC 9745), `Sunset` (RFC 8594, the date it stops working) and a `Link` to the changelog. These stay until that date, even after you acknowledge the notice; log or alert on `Sunset`. Any key may call these, whatever its scopes. A change that needs you to act is announced at least 30 days ahead in production (7 in the sandbox), except for a security fix. [the changelog](/changelog) lists every release. ## 11. Your own obligations - Your privacy notice covers sending documents and signer details to the service. - Your retention rules cover your copies of documents and evidence. - You are responsible for the content of documents and for having the right to send them. - Your support channel answers signers' questions about your documents. - If you learn a key has leaked, tell the operator immediately to revoke it. ## 12. Going live checklist Complete in the **sandbox** first. The operator reviews it before issuing production credentials. - [ ] Keys are only on the server, loaded from a secret store, and never logged - [ ] Every POST's idempotency key is saved before sending; recovery after a simulated timeout returns the original result with no duplicate - [ ] A request that is still `preparing` is handled (409 then retry), not reported as a failure - [ ] Signing links reach signers within their lifetime (Continue pattern or equivalent); the 6th link in an hour is handled - [ ] Reissuing a link: the old one is refused and the new one signs - [ ] Every issued link digest is recorded per signer - [ ] Status arrives by verified, deduplicated webhooks or the event feed with a saved cursor - [ ] Evidence is verified against pinned keys and your own records before the document is marked signed; a tampered bundle is refused - [ ] Cancel and withdraw use a fresh `If-Match` - [ ] All statuses in section 10 are handled; 429/503 back off - [ ] Key rotation has been rehearsed - [ ] Signers are told who is asking; privacy and retention notes are updated - [ ] Notices reach a person: the `eDocInk-Notices` header or `checkCompatibility()` at startup is logged or alerted, and handled notices are acknowledged --- # 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 ` and `X-Tenant-ID: `. 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: ""` 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_`, `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: ; latest=""`. `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/`, 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 `..` 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) ## 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 ### 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. ### Definition | Field | Type | Required | | --- | --- | --- | | `name` | string (pattern ^[A-Za-z0-9_-]{1,80}$) | yes | | `version` | integer (minimum 1) | yes | No other fields are accepted. ### Recipient | Field | Type | Required | | --- | --- | --- | | `email` | string (format email, maxLength 254) | yes | | `display_name` | string (minLength 1, maxLength 200) | yes | No other fields are accepted. ### 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. ### 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. ### Invitation | Field | Type | Required | | --- | --- | --- | | `delivery_id` | string (format uuid) | yes | | `request_id` | string (format uuid) | yes | | `status` | `queued` | yes | No other fields are accepted. ### 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. ### 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. ### Evidence See the contract for this schema. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### 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. ### NoticeList | Field | Type | Required | | --- | --- | --- | | `sdk` | [`SdkStatus`](#schema-sdkstatus) | yes | | `notices` | array of [`Notice`](#schema-notice) | yes | No other fields are accepted. ### 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. --- # Changelog What changed for apps that integrate with eDocInk, newest first. Each entry gives the API version (`info.version` in `/openapi.json`), the SDK version that supports it, and what you need to do. Your app can also read these as notices: see "Staying current" in [INTEGRATION_REQUIREMENTS](/guides/integration-requirements). Kinds: **added** (optional), **needs upgrade** (upgrade before using it), **breaking** (you must act by the deadline), **deprecated**, **security**. ## API 1.7.0 · SDK 0.33.0-alpha.2 - **Added: `Deprecation` and `Sunset` headers.** While an operation you call, or the SDK version your app reports, is being retired, every successful response carries `Deprecation` (RFC 9745), `Sunset` (RFC 8594) and a `Link` to the changelog, until the retirement date. The matching notice says what to do. Nothing is being retired today. No action needed; alert on `Sunset` if your HTTP stack can. SDK 0.33.0-alpha.2 carries the new contract; no code change, upgrade when convenient. ## API 1.6.0 · SDK 0.33.0-alpha.1 - **Added: PDF documents in guest envelopes (SDK only).** The SDK's envelope journal, receipts and evidence verification accept a PDF document (`{title, sha256}`, from an upload or a conversion). `verifyGuestEnvelopeEvidence` verifies every member and can re-check the PDF bytes. No server change. Optional. ## API 1.6.0 · SDK 0.32.0-alpha.1 - **Added: notices and compatibility.** `GET /api/v1/notices`, `POST /api/v1/notices/{id}/acknowledge` and `GET /api/v1/compatibility`; every successful response carries an `eDocInk-Notices` header while your app has unacknowledged notices. Any key may call them. SDK 0.32 reports its version as `User-Agent: edocink-sdk/`, logs each new notice once, and adds `notices()`, `acknowledgeNotice()` and `checkCompatibility()`. Optional; nothing else changes. ## 2026-11-20 · API 1.5.0 · SDK 0.31.0-alpha.1 (engine fix) - **Fixed:** text bodies of 10,000 characters or fewer are prepared on the original 10,000-limit definition again, so SDKs 0.28 to 0.30 verify their evidence. Between 07:34 and 08:25 EST on 2026-11-20 every text request was prepared on the long definition; evidence for requests prepared in that window needs SDK 0.31. ## 2026-11-20 · API 1.5.0 · SDK 0.31.0-alpha.1 - **Needs upgrade: text documents up to 200,000 bytes.** The body limit rises from 10,000 characters to 200,000 UTF-8 bytes. Evidence for a body over 10,000 characters verifies only on SDK 0.31.0-alpha.1 or later; upgrade before sending longer text. No database change. ## 2026-11-19 · API 1.4.0 · SDK 0.30.0-alpha.1 - **Added: document conversion.** Word, OpenDocument, RTF, HTML, text and image files (up to 10 MiB) convert to PDF through `/api/v1/document-conversions`. Needs the `documents:submit` scope. Optional. ## 2026-11-19 · API 1.3.0 · SDK 0.29.0-alpha.1 - **Added: PDF documents.** Upload a PDF (up to 10 MiB) and send it for signature; evidence binds the file by SHA-256 and length. Optional. SDK upgrade details, including database steps, are in `docs/UPGRADES.md` in the SDK archive.