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, input fields, images, signature blocks) plus an optional theme, and AirSign lays them out on A4 pages with automatic text wrapping, page breaks and field placement. You never specify coordinates, so documents are always well-formed and every field the recipient must fill in is placed for you. 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
theme	object	No	Colours and header style - see Theme. Omit for the classic look
logo	object	No	`{ "fileId": "...", "width": 100 }` - an image (from Upload Image) shown at the right of the header band on every page. Fits a 130 x 60 point slot; `width` (20-130) is optional
blocks	array	Yes	The document content, in order (1-500 blocks)

Theme

Every value is optional. Colours are 6-digit hex strings. Without a theme the document uses the classic look: a teal title with a thin rule under it and near-black body text.

Field	Description
`headerStyle`	`"line"` (default): coloured title with a rule under it. `"band"`: a solid `primaryColor` band across the top of every page with the title and subtitle in `bandTextColor` - the branded-form look
`primaryColor`	Title colour and header rule (line style) / band fill (band style)
`accentColor`	Section heading colour, plus a thin stripe under the band (band style)
`textColor`	Body text colour
`bandTextColor`	Title/subtitle colour on a band header. Defaults to white

Example - a red and black club form: { "headerStyle": "band", "primaryColor": "#c8102e", "accentColor": "#111111" }

Block Types

Type	Fields	Description
`heading`	`text` (required, max 500 chars)	A bold section heading. Never left orphaned at the bottom of a page
`paragraph`	`text` (required), `fontSize` (7-24), `bold`, `muted`, `align` (left / center / right)	Body text with automatic wrapping. Use `\n` for line breaks within the paragraph. `muted` renders in grey for fine print
`bulletList`	`items` (required, 1-50 strings)	A bulleted list, one item per entry
`spacer`	`height` (required, 1-600 points)	A vertical gap
`pageBreak`	`header` (optional)	Forces the next block onto a new page. `header` controls that page's header: omit to keep the document header, `null` for no header band (the body starts at the top margin), or `{ "title", "subtitle" }` to retitle it for that page
`image`	`fileId` (required), `width` (20-483 points), `align`	An inline picture uploaded with Upload Image. Height follows the image's aspect ratio; `width` defaults to the pixel width capped at the content width (483 points)
`field`	`fieldType`, `label`, `recipient` (required), `name`, `required`, `placeholder`, `options`, `dateFormat`	An input the recipient fills in while signing, spanning the content width. AirSign prints the label and the box or line and places the matching form field - see Input fields
`fieldRow`	`fields` (required, 2-3 field objects without `type`)	Two or three inputs side by side in equal columns, e.g. Child name \| Date of birth \| Age group. Kept whole on one 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

Input Fields

field and fieldRow compile to the same form fields the AirSign editor places by hand, so they behave identically during signing (validation, required markers, conditional logic added later in the editor). Field properties:

Property	Description
`fieldType`	One of the types in the table below
`label`	Printed above the input (beside it for a single checkbox) and shown to the signer. Required fields get a `*` after the printed label
`recipient`	Key of the recipient who fills the field in
`name`	Stable key the value is stored under (letters, digits, underscore, hyphen). Defaults to a slug of the label; must be unique within the document
`required`	Defaults to `true` for every type except `checkbox`
`placeholder`	Hint text shown inside text inputs and dropdowns
`options`	Choices (1-20 strings). Required for `radio` and `dropdown` (at least 2); optional on `checkbox` to make a multi-select group
`dateFormat`	`date` fields only: `DD/MM/YYYY` (default), `DD/MM/YY`, `MM/DD/YYYY`, `MM/DD/YY`, `YYYY-MM-DD`, `MM/YYYY`, `MM/YY`

fieldType	Rendered as
`text`	Single-line text input on an underline
`multilineText`	Taller boxed text area
`date`	Text input validated as a date in `dateFormat`
`number`	Text input validated as a number
`email`	Text input validated as an email address
`auMobile`	Text input validated as an Australian mobile (04 or +61)
`checkbox`	One tick box with the label beside it, or - with `options` - a multi-select group of boxes (all optional unless `required`)
`radio`	A single-choice group of round buttons, packed left to right and wrapped as needed. The chosen option text is the stored value
`dropdown`	A boxed single-choice dropdown
`initials`	An initials box

Recipients and Keys

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

Field	Type	Required	Description
key	string	Yes	Stable identifier referenced by `recipient` on signature blocks and fields, e.g. `"parent"`. 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

Images

Logos and image blocks reference pictures uploaded beforehand with Upload Image (POST /api/v1/Image, PNG / JPEG / WebP / GIF up to 2MB). The upload response returns the fileId to reference and the pixel dimensions; AirSign keeps the aspect ratio when it sizes the image on the page. Images must belong to the same organisation as the document.

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 (unless a pageBreak removes or retitles it) and the footer with automatic page numbers.
Text wraps and paginates automatically; blocks that do not fit move to the next page. Headings stay with the content that follows them.
Fields, field rows, images and 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, a duplicate field name, an image that is not uploaded yet or too tall for a page, or an undeclared variable all reject the request with a structured issue list.

Full Example

{
  "format": "blocks",
  "title": "Junior Footy Sign-Up",
  "subtitle": "Season 2027 registration and parental consent",
  "theme": { "headerStyle": "band", "primaryColor": "#c8102e", "accentColor": "#111111" },
  "logo": { "fileId": "0f6d2b7e-5c1a-4e0b-9a3f-2b7c8d9e1f00" },
  "blocks": [
    { "type": "heading", "text": "Player details" },
    { "type": "fieldRow", "fields": [
      { "fieldType": "text", "label": "Child name", "recipient": "parent" },
      { "fieldType": "date", "label": "Date of birth", "recipient": "parent" },
      { "fieldType": "dropdown", "label": "Age group", "recipient": "parent", "options": ["Under 8", "Under 10", "Under 12"] }
    ] },
    { "type": "field", "fieldType": "radio", "label": "Has your child played before?", "recipient": "parent", "options": ["Yes", "No"] },
    { "type": "field", "fieldType": "multilineText", "label": "Medical conditions or allergies", "recipient": "parent", "required": false },
    { "type": "heading", "text": "Consent" },
    { "type": "paragraph", "text": "I confirm that I am the parent or legal guardian of the child named above and consent to their participation for the season." },
    { "type": "field", "fieldType": "checkbox", "label": "I have read and agree to the club code of conduct", "recipient": "parent", "required": true },
    { "type": "bulletList", "items": ["Bring boots and a mouthguard.", "Training is Tuesdays and Thursdays."] },
    { "type": "spacer", "height": 16 },
    { "type": "signatureBlock", "recipient": "parent", "label": "Parent / Guardian" }
  ]
}

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"
    }
  ]
}

Issue kinds: title-too-long, out-of-bounds, zone-out-of-bounds, unknown-recipient, duplicate-field-name, unknown-image, image-too-tall, tokens-in-session, undeclared-variable.