eDocInk

Integration requirements

What an application needs, and must do, to use the eDocInk service. Read this before the 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: "<resource_version>" 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: "<resource_version>" (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:<sha256 of the canonical manifest>:<slot_id>. 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-IDs, 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.

  • 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 <timestamp>.<delivery id>.<raw body>.
    • 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=<cursor>&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: <count>; latest="<id>" 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/<version>); 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 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

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