eDocInk agent guide: connect an application
This guide is written for AI coding agents (and the developers working with them). Follow it step by step to add document signing to an application through the eDocInk API. It summarises the integration requirements and the API reference; where they differ, those two documents win. The machine-readable contract is openapi.json.
Quick start: the smallest safe integration
For a small app with one signer per document, this is all you need. Everything after it in this guide adds robustness (webhooks, several signers, full recovery) you can grow into.
- Store three things in your database: each POST's idempotency key (written before
you send), the
original_sha256of the prepared document, and the SHA-256 of each signing link'sinvitationparameter. - Send: prepare the text, create the request, create an invitation and read its
hand-off (section 4, steps 2 to 4). You get a
signing_url. - Deliver the link yourself: an email from your app, or a button on your own page.
- Check: when the signer comes back to your app, or on a timer, call
GET /api/v1/requests/{id}until it issignedand its completion isready. No webhook endpoint is needed. - Verify: fetch the evidence and verify it (section 7). In Node, that is one call to
the SDK's
verifyGuestPlainTextEvidence. Only then mark the document signed.
You can skip webhooks, the event feed, envelopes and templates. Do not skip idempotency keys or evidence verification: they are what make the result trustworthy.
0. Rules you must not break
- The API key is a server-side secret. Never put it in browser or mobile code, logs, test snapshots, commits or prompts. Load it from the app's secret store.
- Save every idempotency key before sending its POST. After a timeout, recover with the same key. Never invent a new key to "try again".
- Do not treat a document as signed until its evidence verifies against pinned public keys and the app's own records.
- Signing links grant access to sign. Store them only as long as needed to deliver them, and never log them.
- eDocInk sends no email. The application delivers each signing link itself.
1. Ask the human for these (do not guess them)
If the developer has no credentials yet, request them on their behalf with
POST https://edocink.com/api/access (see Get access),
using their email address, and tell them to open the confirmation email. Guest-signing
credentials then arrive in their inbox, usually within a few minutes; they are shown to
them once and you never see them unless they put them in configuration. Keep building
against the contract meanwhile. Ask the developer for the values they received, and store them as
server-side configuration:
| Setting | Example | Secret? |
|---|---|---|
EDOCINK_ORIGIN |
the sandbox base URL they were given | no |
EDOCINK_APP_ID |
uuid | no |
EDOCINK_TENANT_ID |
uuid, sent as X-Tenant-ID |
no |
EDOCINK_API_KEY |
bearer key | yes |
EDOCINK_POLICY |
guest@1 (name and version) |
no |
EDOCINK_EVIDENCE_PUBLIC_KEYS |
JSON map of key id → Ed25519 public key | no, but pinned |
EDOCINK_WEBHOOK_KEYS |
key id → secret, only if webhooks are configured | yes |
Also ask: who signs (one person, or several who must all sign), how the app will reach signers (its email provider or an in-app inbox), and whether the app has a public HTTPS endpoint for webhooks. If you cannot get credentials, build against the contract and leave the integration switched off.
2. Choose a client
- Node 24+: use the SDK
@esign/integration-hooks(an archive; email info@edocink.com for it, it is not in the credentials email). It implements idempotent calls, recovery, webhook verification (receiveWebhookOnce) and evidence verification (verifyGuestPlainTextEvidence,verifyGuestEnvelopeEvidence,verifyPdfEvidence). Prefer it. CallcheckCompatibility()at startup and log what it says; the SDK also logs each new notice from eDocInk once. - Any other language: call the HTTPS API directly from openapi.json, and implement evidence verification with an Ed25519 and SHA-256 library, following section 9 of the integration requirements.
Every call sends:
Authorization: Bearer $EDOCINK_API_KEY
X-Tenant-ID: $EDOCINK_TENANT_ID
Content-Type: application/json (on POST)
Idempotency-Key: <saved key> (on every POST)
3. Add storage first
Create these records in the application's own database (names are suggestions):
signature_requests: app record id, eDocInk preparation id, request id, status,original_sha256and the exact inputs sent, latestresource_version.signature_operations: one row per POST with its idempotency key, written before the POST is sent, and its outcome after.signature_links: request id, signer, invitation key, the SHA-256 of the link'sinvitationquery parameter, expiry. Keep every digest ever issued for a signer.signature_events: processed webhookEsign-Event-IDs, or the event-feed cursor.signature_evidence: the verified evidence bundle.
4. Send a document to one signer
GET /api/v1/signing-policiesand check the configured policy is listed.POST /api/v1/text-document-preparationswith:{ "policy": {"name": "guest", "version": 1}, "document": {"title": "Service agreement", "body": "The full text to be signed."}, "recipient": {"email": "pat@example.com", "display_name": "Pat Example"}, "expires_in": 604800 }Optional:
business_reference(up to 200 characters) to link it to your record. The response'stextis exactly what will be signed andoriginal_sha256is its hash. Store both. A preparation expires after 10 minutes.POST /api/v1/document-preparations/{preparation_id}/requestswith body{}. The request startspreparingand becomespendingwithin a second or two.POST /api/v1/requests/{request_id}/invitationswith body{}and a new invitation key. ThenGET /api/v1/requests/{request_id}/invitation-handoffwith headerX-Original-Invite-Key: <that key>. The response hassigning_urlandexpires_at. A 409 means the request is still preparing: wait briefly and repeat the same GET.Record the SHA-256 of the
invitationquery parameter ofsigning_url, then deliver the link to the signer. Links last 72 hours (never beyond the request) and work once; opening one starts a 15-minute signing session.
5. Several signers who must all sign
POST /api/v1/envelope-preparations with the document and 2 or more signers (each with
slot_id, role and recipient), then POST /api/v1/envelope-preparations/{id}/envelope,
then POST /api/v1/signing-envelopes/{id}/invitations and its invitation-handoff for one
link per signer. Track with GET /api/v1/signing-envelopes/{id} and verify the evidence for
every member request once it is complete.
6. Learn what happened
- Event feed (always available):
GET /api/v1/events?after=<cursor>&limit=100. Save the cursor after each page. - Webhooks (optional): verify
Esign-Signatureas HMAC-SHA256 over<Esign-Timestamp>.<Esign-Delivery-ID>.<raw body>in constant time, reject timestamps more than 5 minutes off, skip event ids already processed, answer 2xx within 10 seconds.
Treat each event as a prompt to re-read the request (GET /api/v1/requests/{id}) and act
on its current state.
7. Verify evidence before marking anything signed
When the request is signed and its completion is ready, call
GET /api/v1/requests/{id}/evidence and verify:
- the Ed25519 signature against the pinned public keys (never keys from the bundle);
- the document hash against the stored
original_sha256; - the policy and consent against what the app chose;
- for guest links,
credential_digestagainst one of the link digests the app recorded for that signer.
Only then mark the document signed and store the bundle. If anything fails, do not mark it signed; flag it for a person.
8. Handle errors by status code
| Status | Do this |
|---|---|
| 400, 413, 415 | Fix the request; do not retry unchanged |
| 401 | Key unknown, expired or revoked: stop and tell the human |
| 403 | Key lacks a scope: tell the human |
| 404 after a timeout | Inconclusive: recover with the original key |
| 409 | Not ready or not allowed in this state: re-read, then retry only if it can change |
| 410 | Cursor expired: restart the scan and reconcile |
| 412, 428 | Re-read and send the current If-Match |
| 429, 503 | Wait for Retry-After, retry with the same key |
9. Prove it works in the sandbox
Write tests (against the sandbox, never production) that show:
- A document is prepared, sent, signed by following the link, and its evidence verifies.
- A simulated timeout on each POST recovers the original result with no duplicate.
- Reissuing a link makes the old link fail and the new one sign.
- A tampered evidence bundle is refused.
- The sixth link in an hour (429) and a still-preparing request (409) are handled.
- Cancelling (
POST /api/v1/requests/{id}/cancel) sends a freshIf-Match: "<resource_version>"from the latest read.
Then work through the go-live checklist in section 12 of the integration requirements and hand the results to the human, who sends them to runMast for production access.
10. Tell us what went wrong
If a guide was unclear, wrong or missing something, or the API did not behave as described, report it so the guides can be fixed for the next agent. Ask the human first if your environment requires approval for outbound requests.
POST https://edocink.com/api/feedback
Content-Type: application/json
{
"kind": "unclear",
"page": "/agents#4-send-a-document-to-one-signer",
"message": "What you expected, what happened, and what would have helped.",
"contact": "",
"agent": "the agent or tool name"
}
kind is one of unclear, api, missing, agent or other. contact is an optional
email for a reply. The answer is 202 {"status":"received"}. Never include API keys,
signing links, evidence bundles or real personal data. People can use the form at
https://edocink.com/feedback.
Where to find more
- Overview: https://edocink.com/index.md
- Access: https://edocink.com/access.md
- Integration requirements: https://edocink.com/guides/integration-requirements.md
- API reference: https://edocink.com/guides/api-reference.md
- OpenAPI 3.1 contract: https://edocink.com/openapi.json
- Changelog: https://edocink.com/changelog.md (feed: https://edocink.com/changelog.atom)
- Everything in one file: https://edocink.com/llms-full.txt
- Feedback: https://edocink.com/feedback
Something unclear or missing on this page? Suggest an improvement.