eDocInk

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.

  1. Store three things in your database: each POST's idempotency key (written before you send), the original_sha256 of the prepared document, and the SHA-256 of each signing link's invitation parameter.
  2. 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.
  3. Deliver the link yourself: an email from your app, or a button on your own page.
  4. Check: when the signer comes back to your app, or on a timer, call GET /api/v1/requests/{id} until it is signed and its completion is ready. No webhook endpoint is needed.
  5. 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. Call checkCompatibility() 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_sha256 and the exact inputs sent, latest resource_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's invitation query parameter, expiry. Keep every digest ever issued for a signer.
  • signature_events: processed webhook Esign-Event-IDs, or the event-feed cursor.
  • signature_evidence: the verified evidence bundle.

4. Send a document to one signer

  1. GET /api/v1/signing-policies and check the configured policy is listed.

  2. POST /api/v1/text-document-preparations with:

    {
      "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's text is exactly what will be signed and original_sha256 is its hash. Store both. A preparation expires after 10 minutes.

  3. POST /api/v1/document-preparations/{preparation_id}/requests with body {}. The request starts preparing and becomes pending within a second or two.

  4. POST /api/v1/requests/{request_id}/invitations with body {} and a new invitation key. Then GET /api/v1/requests/{request_id}/invitation-handoff with header X-Original-Invite-Key: <that key>. The response has signing_url and expires_at. A 409 means the request is still preparing: wait briefly and repeat the same GET.

  5. Record the SHA-256 of the invitation query parameter of signing_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-Signature as 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_digest against 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:

  1. A document is prepared, sent, signed by following the link, and its evidence verifies.
  2. A simulated timeout on each POST recovers the original result with no duplicate.
  3. Reissuing a link makes the old link fail and the new one sign.
  4. A tampered evidence bundle is refused.
  5. The sixth link in an hour (429) and a still-preparing request (409) are handled.
  6. Cancelling (POST /api/v1/requests/{id}/cancel) sends a fresh If-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

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