eDocInk

eDocInk API 1.7.0 — reference

Generated from the OpenAPI contract.

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.

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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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
  • 201: Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → DocumentPreparation
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 503 (see 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)

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
  • 201: Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → PdfDocumentPreparation
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • 201: Immutable ten-minute snapshot, or identical original prepare-key replay, possibly expired. Active limit 100 per app/tenant → DocumentPreparation
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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 · headers ETag, Location
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see Errors)

POST /api/v1/requests

createRequest — Freeze a request and queue original preparation

  • Scopes: requests:create
  • Headers: X-Tenant-ID, Idempotency-Key
  • Body: 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 · headers ETag, Location
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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 · headers ETag
  • Errors: 400, 401, 403, 404, 409, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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 · headers ETag
  • Errors: 400, 401, 403, 404, 409, 412, 413, 415, 428, 429, 503 (see Errors)

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
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see Errors)

Multi-signer envelopes

POST /api/v1/envelope-preparations

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

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
  • Errors: 400, 401, 403, 404, 409, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • 201: Immutable N-required-signer envelope → SigningEnvelope
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 412, 413, 415, 428, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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)

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
  • Errors: 400, 401, 403, 404, 409, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 429, 503 (see 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
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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 · headers eDocInk-Notices
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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 · headers eDocInk-Notices
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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 · headers eDocInk-Notices
  • Errors: 400, 401, 403, 404, 409, 410, 429, 503 (see 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

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 yes
recipient 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 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 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 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 or 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 yes
expires_in integer (minimum 60, maximum 2592000) yes
business_reference string (maxLength 200)
policy 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 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 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 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 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 yes
manifest 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 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 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 yes
expires_in integer (minimum 60, maximum 2592000) yes
business_reference string (maxLength 200)
policy 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 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
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 yes
notices array of Notice yes

No other fields are accepted.

Compatibility

Field Type Required
api_version string (pattern ^[0-9]+.[0-9]+.[0-9]+$) yes
sdk SdkStatus yes
notices object yes

No other fields are accepted.

Something unclear or missing on this page? Suggest an improvement.