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_in60 s to 30 days. - Page size:
limit1-100 on/requestsand/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· headersETag,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· headersETag,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· headersETag - 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· headersETag - Errors: 400, 401, 403, 404, 409, 412, 413, 415, 428, 429, 503 (see 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 - 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
- Scopes:
documents:prepare,documents:submit - Headers:
X-Tenant-ID,Idempotency-Key - Body:
EnvelopeSubmission - 201: Success →
EnvelopePreparation - Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (see 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 - 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· headerseDocInk-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· headerseDocInk-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· headerseDocInk-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.