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
- A server-side component that can make HTTPS calls and hold secrets. The API key must never reach a browser, mobile app or log.
- Durable storage you control: a database table or two (see section 6).
- A way to reach signers: an email provider or an in-app inbox.
- 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. - 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
GET /api/v1/signing-policies: confirm the policy you will use is published.POST /api/v1/text-document-preparations(or/document-preparationsfor a template): the service returns the exact rendered text and itsoriginal_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.POST /api/v1/document-preparations/{id}/requests: creates the signing request. It startspreparingand becomespendingonce the service has frozen the document (normally a second or two).POST /api/v1/requests/{id}/invitations: issue a signing link. ThenGET /api/v1/requests/{id}/invitation-handoffwithX-Original-Invite-Keyreturns thesigning_url. A 409 here usually means the request is stillpreparing: wait briefly and retry the same GET.- Deliver the link (section 7).
- Learn the outcome by webhook or
GET /api/v1/events(section 8). - When the request is
signedand its completion isready: callGET /api/v1/requests/{id}/evidenceand 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)
POST /api/v1/envelope-preparationswith the document and 2 to 20 signers (each with aslot_id,roleand recipient).POST /api/v1/envelope-preparations/{id}/envelope: creates one request per signer.POST /api/v1/signing-envelopes/{id}/invitations, thenGET …/invitation-handoff: one signing link per signer.- Track with
GET /api/v1/signing-envelopes/{id}(signed_count,complete) or events. Fetch and verify evidence for each member request once complete. - To replace one signer's link, call the single-request
POST /api/v1/requests/{member_request_id}/invitationswith a new key. That revokes only that signer's earlier link. - Withdraw the whole envelope with
POST /api/v1/signing-envelopes/{id}/withdrawandIf-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.
POST /api/v1/document-uploadswith the raw PDF as the body,Content-Type: application/pdf, up to 10 MiB (scopedocuments:submit). The service checks only that it looks like a PDF (%PDF-header,%%EOFtrailer) and returns{sha256, byte_length, media_type, expires_at}. Uploading the same bytes again returns the same answer, so this call takes noIdempotency-Key; on a timeout, just upload again. An upload lasts 24 hours; at most 200 live uploads per app and tenant.- Check that
sha256is the SHA-256 of the bytes you sent, and store it. POST /api/v1/pdf-document-preparationswith the same body as a plain-text preparation, exceptdocumentis{title, sha256}. The response hasmedia_type,byte_lengthandoriginal_sha256(equal to the upload'ssha256) and notext. For several signers, senddocument: {title, sha256}toPOST /api/v1/envelope-preparationsinstead.- 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
POST /api/v1/document-conversionswith the raw file and itsContent-Type:.docx,.doc,.odt,.rtf,text/html,text/plain,image/pngorimage/jpeg, up to 10 MiB (scopedocuments:submit). The answer is202with anidandstatus: "converting". Sending the same file again returns the same conversion, so this call takes noIdempotency-Key. At most 50 conversions per hour per app and tenant.- Poll
GET /api/v1/document-conversions/{id}every second or two (a conversion normally takes under 10 seconds) untilstatusisreadyorfailed(reasonsays why). GET /api/v1/document-conversions/{id}/pdfand 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.- Prepare it as a PDF:
document: {title, sha256}with the conversion'spdf.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}/requestswithX-Original-Create-Key,GET …/invitationswithX-Original-Invite-Key, orGET …/envelope-preparations/{id}withX-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.
7. Delivering signing links
- A link lives 72 hours and never longer than the request. It works once: opening it starts a 15-minute signing session.
- Optional "Continue" pattern: email a link to your app. On GET, show a Continue
button and change nothing, because email scanners open links. On POST, reuse the
current link if the handoff still returns it; otherwise issue a new one with a new key
and redirect to its
signing_url. - At most 5 links per signing request in any rolling hour (the 6th is 429). A request has one signer, so this is also per signer. Each new link revokes the last one, and any open signing session with it.
- Tell signers who is asking and why. The signing page shows the document title, who requested it (tenant and app; with branding set, the tenant's name, colour and logo, otherwise a neutral "Document signing" heading), who the link was sent to, the document and the consent text.
8. Knowing what happened
Webhooks (optional): POSTed to your HTTPS endpoint with
Esign-Event-ID,Esign-Delivery-ID,Esign-Timestamp,Esign-Key-IDandEsign-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
receiveWebhookOncedoes all of this.- Compute HMAC-SHA256 over
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_sha256you stored; - the policy and consent text, against what you chose;
- for guest links,
credential_digestagainst 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.
Parse the bundle as strict JSON (UTF-8, at most 4 MiB) and keep the exact bytes you received.
verification.algorithmisEd25519andverification.key_idequalsmanifest.attestation_key_idand is one of your pinned key ids.Decode the pinned key (unpadded base64url, 32 bytes). SHA-256 of those raw 32 bytes equals
manifest.attestation_key_sha256.Canonicalise
manifestwith RFC 8785 (JCS). Its SHA-256 equalsmanifest_sha256. Every number in a manifest is an integer within ±2^53-1.Decode
verification.signature(unpadded base64url, 64 bytes). It is an Ed25519 signature over the bytesesign-evidence-v2+ one NUL byte (0x00) + the canonical manifest bytes, for guest bundles (esign-evidence-v1for account sign-in). It is not a signature over themanifest_sha256string.request_id, app, tenant and recipient email are the ones you sent. The definition (manifest.request.definition_nameanddefinition_version, repeated inmanifest.definitionandmanifest.acceptance.definition) equals thedefinitionreturned when you created the request. For plain text it is a per-document name such assubmitted-text-…, not your signing policy's name: the policy appears only by its content, inmanifest.request.frozen_policy.signing.The document hash: SHA-256 of the UTF-8 bytes of
title + "\n\n" + body, exactly as returned at preparation, equals theoriginal_sha256you stored and theoriginal_sha256in the signature, review and acceptance. For a PDF it is the SHA-256 of the PDF bytes you uploaded:manifest.originalhasrenderer_versionpdf-v1,media_typeapplication/pdf,sha256andbyte_length, and nocontent(the PDF is not inside the bundle). Check it against your own copy of the file.credential_digestequals SHA-256 of the UTF-8 bytes of theinvitationquery parameter of asigning_urlyou issued for this request (record that digest when you receive each link).frozen_policy.signing.consent_versionandconsent_textare the ones in your policy.The audit-event hash chain,
manifest.audit_prefix: three events, in order, from an app key, the worker and the signer session (actor_kindapp_key,worker,signer_session). Start withpreviousset to 64 zeros. For each event:previous_hashequalsprevious;event_hashis the SHA-256 of the bytes ofprevious(as ASCII hex), then the base64-decodedbody_base64, then the actor: theactor_idfor the first event,worker:+actor_idfor the second,signer:+actor_idfor the third;- then set
previoustoevent_hash.
manifest.request.input_digestis the SHA-256 of the request you sent: compact JSON with sorted keys and no ASCII escaping ({"body":…,"method":"POST","path":…}, UTF-8), wherebodyis your create-request body andpathis/api/v1/requestsor/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.The completion receipt,
manifest.completion.contentmust equal exactly these fields copied from the manifest:schema_version:esign-completion-v2for guest bundles,esign-completion-v1for account sign-in;scope:manifest.scope;signature_id,signed_at,original_sha256,consent_version,declared_name,issuer,subject: frommanifest.signature(signature_idis itsid);accepted_version:manifest.acceptance.resource_version;- guest bundles only:
authentication_method, set toemail-link.
sha256is the SHA-256 of the RFC 8785 bytes ofcontent, andbyte_lengthis 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_infrom 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/noticeslists 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 sendsUser-Agent: edocink-sdk/<version>); an app that reports none sees every notice.POST /api/v1/notices/{id}/acknowledgemarks one handled for the whole app. It is idempotent.GET /api/v1/compatibilityreturns the API version and whether your SDK iscurrent,supportedorunsupported. 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 aLinkto the changelog. These stay until that date, even after you acknowledge the notice; log or alert onSunset.
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
preparingis 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-Noticesheader orcheckCompatibility()at startup is logged or alerted, and handled notices are acknowledged
Something unclear or missing on this page? Suggest an improvement.