SmartDocs API

Core Concepts

The SmartDocs API is organized around a small set of resources. This page explains how they relate so the reference reads naturally.

Organizations

Everything you create belongs to your organization — templates, PDF assets, signing processes, and API keys are all org-scoped, and an API key can only see its own organization's data.

Access inside an organization is role-based: OWNER, ADMIN, and MEMBER. API keys carry either ADMIN or MEMBER (never OWNER); required roles vary by endpoint — managing templates and PDF assets, and creating direct signing processes, require ADMIN, while reading data and starting signings from a published template are available to MEMBER keys. The required role for each operation is noted in the API reference. Plans (FREE, PRO, ENTERPRISE) set quotas — storage, monthly signing volume, daily API requests — and gate features such as SMS-verified signing. Exceeding a plan quota returns a 402 with a stable error code (see Conventions).

Templates

A template is a reusable document definition. Templates come in two kinds:

  • PDF — built on an uploaded PDF, with signing fields placed on its pages.
  • HTML — rendered to PDF from an HTML layout with dynamic input data.

A template moves through three statuses: DRAFT → PUBLISHED → ARCHIVED. The draft is mutable — you edit it via PATCH /templates/{id}/draft. Publishing snapshots the draft into a template version: an immutable, numbered record of everything needed to start a signing. Already-published versions never change; publishing again creates the next version, and in-flight signing processes keep pointing at the exact version they were started from.

A version's definition contains:

  • Signer roles — the named parties (each with a stable role key) that must sign.
  • Input schema — the dynamic data your integration supplies at start time (rendered into HTML templates and prefillable fields).
  • Signing fields — typed boxes (TEXT, DATE, CHECKBOX, SIGNATURE) placed on the document and assigned to a role.

POST /templates/{id}/start-signing starts a signing process from the latest published version: you supply the runtime data, one concrete signer per role, and an expiry.

Signing processes

A signing process is one document sent to an ordered set of signers. It is created in one of two ways — its origin records which:

  • TEMPLATE — started from a published template version via start-signing.
  • DIRECT — created from a raw PDF asset via POST /signing-processes, with signers and fields declared inline.

How signers reach the document is the dispatchMode:

  • EMAIL — each signer receives a hosted signing link by email, in sign order.
  • KIOSK — signers sign in person on a staff-supervised device; no emails are sent.
  • CURRENT_USER — the caller signs the document themselves (single signer).

How signers are authenticated is the authPolicy:

  • AES_OTP — the signer must pass an SMS one-time code before submitting (advanced signature; external signers need a phoneE164).
  • SES_LINK_ONLY — possession of the personal invite link authorizes signing.

A process is born SENT — there is no draft state — and moves through a strict lifecycle:

SENT → IN_PROGRESS → COMPLETED, or terminally DECLINED, VOIDED (cancelled by you via POST /signing-processes/{id}/void), or EXPIRED (passed its expiresAt; extendable beforehand via POST /signing-processes/{id}/extend).

Signers

Each party on a process occupies a signer slot with a sequential signOrder starting at 1. Signing is strictly ordered: signer 2 is only activated once signer 1 completes. Each slot tracks its own status (PENDING → READY → OPENED → COMPLETED, or DECLINED / EXPIRED).

Signers act on a hosted signing page that SmartDocs serves and links to from the invite email (or the kiosk session). Your integration never constructs signing URLs and never calls the signer endpoints with an API key — those endpoints authenticate the signer, not your server. You can re-send a pending signer's invite with POST /signing-processes/{id}/signers/{signerId}/resend-invite, which also invalidates the previously emailed link.

PDF assets

Uploaded PDFs become PDF assets, the input for direct signings and PDF templates. Two things to know:

  • Deduplication — assets are content-addressed by SHA-256 within your organization. Uploading a byte-identical file returns the existing asset rather than storing a copy.
  • Async processing — after the two-step upload (initiate → PUT → commit), preview and thumbnail artifacts are generated in the background: QUEUED → PROCESSING → READY (or FAILED, which can be retried). Actions that depend on artifacts — publishing a PDF template, starting a signing — require the asset to be READY and answer 409 until then.

Audit trail

Every signing process carries an append-only list of audit events — process created and sent, signer opened, OTP verified, signer submitted and completed, process completed, declined, voided, and so on. Each event stores the hash of its predecessor and its own hash, forming a per-process hash chain: any attempt to alter or remove history breaks the chain. Events also record the document's SHA-256 at the time, binding the trail to the exact bytes being signed.

When the last signer completes, SmartDocs renders the final signed PDF and a completion certificate summarizing the signers, the authentication evidence, and the audit chain.

How it fits together

Organization ─┬─ Template ──< TemplateVersion (published, immutable)
              │      └─ definition: signer roles + input schema + signing fields
              ├─ PdfAsset (sha256-deduped, async processed)
              └─ SigningProcess (TEMPLATE or DIRECT origin)
                     ├─< SignerSlot (ordered; hosted signing links)
                     ├─< FieldDefinition ──< CommittedFieldValue
                     └─< AuditEvent (hash-chained)