Block Document Format

The block document format lets you create signing documents from scratch through the API - no PDF required. You describe the document as a flow of blocks (headings, paragraphs, signature blocks) and AirSign lays them out on A4 pages with automatic text wrapping, page breaks and signature field placement. You never specify coordinates, so documents are always well-formed. It is used by Create Session and Create Template, and by the equivalent tools on the MCP server.

Document Object

Field	Type	Required	Description
format	string	Yes	Must be `"blocks"`
title	string	Yes	Document title shown in the header band of every page. Must fit on one line - keep it under roughly 30 characters or the request is rejected
subtitle	string	No	Smaller line shown under the title (max 200 characters)
footerLabel	string	No	Footer text. Page numbers ("page X of Y") are appended automatically. Defaults to the title
blocks	array	Yes	The document content, in order (1-500 blocks)

Block Types

Type	Fields	Description
`heading`	`text` (required, max 500 chars)	A bold section heading
`paragraph`	`text` (required), `fontSize` (7-24), `bold`, `muted`	Body text with automatic wrapping. Use `\n` for line breaks within the paragraph. `muted` renders in grey for fine print
`spacer`	`height` (required, 1-600 points)	A vertical gap
`pageBreak`	none	Forces the next block onto a new page
`signatureBlock`	`recipient` (required), `label` (required, max 100 chars)	A signature area with name, date-signed and signature fields bound to one recipient. `recipient` must match a `key` in the request's `recipients` array. Every signer should get exactly one. Never split across pages

Recipients and Keys

Recipients are declared once per request (not per document) with a stable key that signatureBlock blocks reference:

Field	Type	Required	Description
key	string	Yes	Stable identifier referenced by `signatureBlock.recipient`, e.g. `"tenant"`. Alphanumeric, underscore and hyphen only
name	string	Sessions: yes	Full name. For templates this may be a `{{{variable}}}` token or left blank to fill in later
email	string	Sessions: yes	Email address (lowercase). For templates this may be a token
signingOrder	number	No	1-based signing order. Defaults to the array position

Variables (templates only)

Templates may embed {{{variableName}}} tokens in any block text and in recipient name/email. Every token must be declared in the request's variables array, and values are supplied later when a session is created from the template (see Create Session From Template). Sessions are final documents - any token in a session document is rejected with a validation error.

Layout Rules

Pages are A4 portrait. Every page carries the title header band and the footer with automatic page numbers.
Text wraps and paginates automatically; blocks that do not fit move to the next page.
Signature blocks are kept whole - they never split across a page boundary.
The document is validated before anything is saved: out-of-bounds content, an over-long title, an unknown recipient key, or an undeclared variable all reject the request with a structured issue list.

Full Example

{
  "format": "blocks",
  "title": "Mutual NDA",
  "subtitle": "Between Party A and Party B",
  "blocks": [
    { "type": "heading", "text": "1. Purpose" },
    { "type": "paragraph", "text": "The parties wish to exchange confidential information for the purpose of evaluating a potential business relationship." },
    { "type": "heading", "text": "2. Obligations" },
    { "type": "paragraph", "text": "Each party agrees to keep the other party's confidential information secret and to use it only for the purpose above." },
    { "type": "paragraph", "text": "This clause survives termination of the agreement.", "muted": true, "fontSize": 9 },
    { "type": "spacer", "height": 24 },
    { "type": "signatureBlock", "recipient": "partyA", "label": "Party A" },
    { "type": "spacer", "height": 16 },
    { "type": "signatureBlock", "recipient": "partyB", "label": "Party B" }
  ]
}

Validation Error Shape

Status: 400 Bad Request

{
  "message": "Document failed layout validation with 1 issue(s)",
  "error": "DOCUMENT_VALIDATION_FAILED",
  "issues": [
    {
      "kind": "title-too-long",
      "page": 1,
      "message": "title wraps to 2 lines in the header band - shorten it to fit one line (roughly 30 characters)",
      "snippet": "A Very Long Agreement Title That Cannot Fit"
    }
  ]
}