Skip to content

Send Pipeline

Jump to bottom
Yohan Marshall edited this page Aug 29, 2026 · 2 revisions

Send Pipeline

What happens between "here's a document" and a sealed PDF.

Input formats

POST /v1/documents takes exactly one of markdown or file:

Format How it's handled
PDF Used as-is. {{sig}} tags in the text are parsed into fields and whited out; AcroForm widgets import as fields bound to the first human signer.
DOCX Converted to PDF on the server (headless Chromium), then treated like a PDF upload. Rate-limited per caller; legacy .doc is rejected with a clear error.
Markdown Rendered server-side to a clean Letter PDF (marked + pdf-lib). {{sig}} tags place fields; tags inside code blocks stay literal. Latin-1 text only. The source is kept and retrievable via GET /v1/documents/:id.pdf?kind=source.

The web send page accepts all three plus plain text: .md and .txt drops open in a write view for editing before send, and the page-wide dropzone highlights while a file is dragged anywhere over it.

Fields

Four ways fields get onto a document, all producing the same field model (percent coordinates, role-bound, typed):

  1. Tags in the document text: {{sig}}, {{initials}}, {{Full Name;type=text;role=Signer 2}}.
  2. Placed in the send editor: pick a type, click the page.
  3. AcroForm import from fillable PDFs.
  4. AI detection (POST /v1/detect-fields, PDF only): suggests fields, rate-limited per user.

Corrections (whiteout patches) can be drawn in the editor and are burned into the PDF at send time.

Sending and confirmation

  • No Authorization header: the sender gets an OTP email; the document is pending_sender until confirmed.
  • Logged-in session matching sender_email: sends directly unless "Confirm my sends" is on.
  • sign_live_ key: standing authorization, sends immediately.
  • OAuth agent (sign_oauth_): held for the owner's emailed confirmation while "Confirm agent sends" is on (the default).

Signers finish at /s/:token. Sequential order by default, order=parallel for all-at-once. Completion seals the PDF (PKCS#12) and writes the audit trail; webhooks fire if registered.

Retention

Free documents hard-delete PDF bytes when shred_at is due (7 days to sign, 7 days keep after completion). Pro keeps for 1 year. DELETE /v1/documents/:id purges immediately. There is no restore.

Clone this wiki locally