Templates, roles & fields

A template is a reusable contract. It has a name, a single draft, and any number of published versions. Envelopes are always created from a published version, which is immutable: editing a template means saving a new draft and publishing it as the next version. Envelopes already sent keep the version they pinned.

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Ids are prefixed strings (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); timestamps are RFC 3339 in UTC.

Two ways to author

Overlay mode (source: "pdf") starts from an uploaded document. Fields are rectangles placed on its pages in PDF points (1/72 in), origin at the top-left of the page, page index from 0. A .docx upload is converted to PDF once (LibreOffice, keeping the Word layout; fonts the file does not embed may be substituted), and from then on it is a PDF like any other: the file reports convertedFrom: "docx". Overlay versions can also carry content edits (text edited in place, white-out, text boxes, images, page operations) that are applied when the version is published.

Document mode (source: "document") stores the contract itself as rich text (ProseMirror JSON) with variable chips such as {{client.name}}, inline field blocks, conditional sections (kept only when a showIf expression is true) and repeating sections and table rows (one per item of an array variable). Each envelope renders its own PDF, and field positions are read from that render. In the dashboard, Document mode is “Start from blank document”. Over the API, a Word file can also be imported into Document mode with POST /v1/templates/{id}/import: {{tags}} become variables or fields and signature lines (“Signature: ____”, “By: ____”, “Date: ____”) become field blocks.

In the dashboard

New template offers two starts:

Upload document: one dropzone for .pdf and .docx files up to 25 MB. Word files are converted to PDF and open in the designer with a reminder to check the converted layout before placing fields. Small fixes are made in place on the PDF (“Edit content”); for a larger rewrite, change the Word file and upload it again.
Start from blank document: write the contract in Document mode.

Content edits

The designer’s Edit content mode changes what signers see without touching the uploaded file. Its default tool, Edit text, highlights the text blocks of the page (lines and paragraphs grouped from the PDF’s text layer); click one, or Tab to it and press Enter, to edit it in place in the same position, size, colour, alignment and font. Ctrl/Cmd+Enter saves, Esc cancels, and each edit can be reverted from the edits list. Edits are undoable like any other change. The other tools add white-out, text boxes and images, and insert, delete, reorder or rotate pages.

An in-place text edit is stored as two items that share a group: a white-out over the original block (in the page’s background colour) and a text item laid out in the block, with the block’s line height and first baseline:

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face picks the font: the PDF’s embedded font when it can draw every character of the new text, else a bundled metric-compatible font (sans Arimo for Helvetica/Arial, serif Tinos for Times, mono Cousine for Courier, carlito Carlito for Calibri) in the matching weight and style. The text wraps within the block; when it needs more lines than the original, the edit grows into free space below it, and the designer refuses to save it when there is none (“text doesn’t fit — shorten it or add space”). The designer and the API share the layout and font code, so the published PDF matches the preview line for line.

Edits can only change a draft. Publishing applies them to a new base PDF whose SHA-256 is the version’s documentHash (the hash of what signers see); the uploaded original is kept as the version’s sourceFile, and the next draft starts from it with the same edits. White-out covers content visually; the original text stays in the file underneath, so it is not a secure redaction.

Roles

Roles are the parties of the contract. Recipients of an envelope are matched to roles by key.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "email_otp" }

Property	Meaning
`key`	Lowercase identifier (`^[a-z][a-z0-9_]*$`) used by fields and by envelope recipients
`kind`	`signer` (must have a signature or initials field), `approver`, `form_filler`, or `cc` (receives, never signs)
`order`	Routing order from 1. Roles with the same order sign in parallel; the next order starts when they are done
`verification`	Default for the role’s recipient: `email_otp` (default) or `none`. A recipient can override it

passkey, id_check and sms_otp appear in the schema but are not available for signing yet: a template that uses passkey or id_check cannot be published, and SMS codes are not delivered yet.

Fields

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Field types: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp, and variable_text (filled from a variable by the sender, not by a signer). Fields can also have:

variable: a JSON Pointer into the variables (/client/name) to bind or prefill the field;
options for radio and dropdown;
validation: pattern, min, max, maxLength, or a format (email, phone, date, number, currency);
showIf: a condition over variables and other fields, such as plan != "free";
formula: a computed, read-only value;
overflow: what to do when a value does not fit the box: shrink (default), wrap or reject.

Variables

A version’s variables is a JSON Schema (draft 2020-12) for the data you send with each envelope; the version’s sampleVariables is an example. POST /v1/envelopes validates your variables against it and reports every problem with a JSON Pointer:

{
  "type": "https://bonafide.republic.global/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

To see the result before sending, render a watermarked preview of any version with POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), or create the envelope with ?dry_run=true.

Building a template with the API

Most teams design templates in the dashboard’s designer. Everything it does is available over the API:

POST /v1/templates with { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files with the PDF (or .docx) as the body (Content-Type: application/pdf) or as the multipart field file. Up to 25 MB. The response has the file id (tfl_…), page count and page sizes.
PUT /v1/templates/{id}/draft with roles, fields, variables (and file, or source: "document" with content). Drafts are saved as they are; nothing is checked yet.
POST /v1/templates/{id}/publish. Publishing lints the draft: every field’s role exists, every signer role has a signature field, fields fit their pages, radio and dropdown fields have options, expressions parse. Problems come back as a 422 with pointers such as /fields/3/rect.

curl https://bonafide-api.republic.global/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Version endpoints accept a number, latest or draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (the base PDF). A template that was never used by an envelope or a signing link can be deleted; otherwise DELETE answers 409 in-use.