Fields

A field is one box drawn on a page. Every field shares the same geometry: page (1-based, default 1), x, y, width (default 120), height (default 24), in PDF points from the top-left, plus a type that decides what the box renders. A document or version holds up to 200 fields.

Type	Renders
text	Drawn text, plain or markdown
field	A fillable text box (interactive form field)
checkbox	A checkable box
symbol	One glyph (✓ ✗ ● ■ ★ …) centered in the box
fill	Sets a form field that already exists in the base PDF
image	An uploaded image asset
barcode	A QR code or Code 128 barcode
table	Ruled line items with columns
html	An HTML/CSS box composed onto the page

Field types are an open set; a version that uses a type the API doesn't support is rejected with 422 UNSUPPORTED_FIELD_TYPE.

text

Draws content, either literally or from a merge tag:

{ "type": "text", "merge_tag": "client_name", "x": 90, "y": 200, "width": 300, "height": 20 }

With "content_format": "markdown", a rendered subset of markdown is supported: #/##/### headings, **bold**, *italic*, [links](https://example.com) (rendered with live link annotations), - and 1. lists, and blank-line paragraphs. Markdown always word-wraps.

field

Creates a fillable text box: an interactive form field a recipient can type into. label names the created widget:

{ "type": "field", "label": "signature_name", "x": 90, "y": 500, "width": 240, "height": 22 }

To convert every interactive widget into static page content after rendering, set "flatten": true on the request (Generating documents).

checkbox

A checkable box. Bind it to a merge tag and it renders checked when the data value is truthy:

{ "type": "checkbox", "merge_tag": "interpreter_needed", "x": 90, "y": 260, "width": 16, "height": 16 }

symbol

Draws a single curated glyph centered in the box: check marks, bullets, stars, arrows (✓ ✗ ● ■ ★ and similar). content holds the glyph:

{ "type": "symbol", "content": "✓", "x": 91, "y": 261, "width": 14, "height": 14 }

Only geometry and text_color styling apply. A glyph outside the supported set is skipped with a SYMBOL_NOT_ENCODABLE warning.

fill

Sets the value of a form field that already exists in the base PDF. label is the existing field's name, content (or a merge tag) is the value:

{ "type": "fill", "label": "defendant_name", "merge_tag": "client_name" }

The valid targets are listed in the version's acro_fields inventory: name, kind (text, checkbox, dropdown, option_list, radio_group), options, and max length, so pickers can offer real choices. Fill problems (an unknown name, a value that doesn't match a dropdown's options) are warn-and-skip: the document still renders and the skip is reported.

fill requires a base PDF, so it is rejected on template-free /v1/documents requests (422 FILL_REQUIRES_TEMPLATE).

image

Draws an uploaded image asset: a logo, seal, or signature. Upload assets first (POST /v1/assets, PNG or JPEG, max 2 MB, base64, templates:write), then reference them:

{ "type": "image", "asset_id": "2c9e5b7a-…", "x": 36, "y": 36, "width": 120, "height": 120 }

• fit: "contain" (default) preserves aspect ratio, centered in the box; "stretch" fills it.
• Bind via merge_tag with an image-typed tag to supply a different asset per generation (a signature, a photo). The data value is an asset id.
• Uploads are validated by content, not filename: a corrupt image fails at upload (422 INVALID_IMAGE), not on a rendered document. The response includes the image's pixel dimensions for aspect-correct placement.
• A field referencing a deleted asset is skipped with an ASSET_NOT_FOUND warning.

barcode

Barcodes are vector-drawn, crisp at any print resolution, black, with standard quiet zones, centered and fitted to the box:

{ "type": "barcode", "symbology": "qr", "merge_tag": "portal_url",
  "x": 440, "y": 640, "width": 120, "height": 120 }

symbology	Capacity	Typical use
qr	≤ 500 characters	Link a notice to its portal page
code128	Printable ASCII, ≤ 80 characters	Case numbers, filing ids

Unencodable values are skipped with a BARCODE_INVALID warning.

table

Ruled line items (fee schedules, charge lists) with up to 10 columns:

{
  "type": "table", "merge_tag": "fees",
  "columns": [
    { "key": "description", "label": "Description" },
    { "key": "amount", "label": "Amount", "width": 90, "align": "right" }
  ],
  "x": 72, "y": 320, "width": 468, "height": 220
}

• Rows come from an array-typed merge tag ("data": { "fees": [ { "description": "Filing fee", "amount": "$50.00" }, … ] }) or from static rows (max 100). The expected row shape is advertised in the version's merge_tags[].columns for discovery.
• Any column label enables the bold header row. Unsized columns share the remaining width. Cells are single-line and ellipsis-truncated.
• row_height defaults to 1.6 × the font size.
• Rows beyond the box's capacity truncate with a TABLE_ROWS_TRUNCATED warning, or fail generation with 422 TABLE_OVERFLOW when the field sets "overflow": "error". Use error for legal documents where a silently shortened fee table would be wrong.

html

Renders content as HTML/CSS at exactly the box size (real browser layout inside the box) and composes the result onto the page:

{ "type": "html",
  "content": "<p style='font-size:14px'>Dear {{client_name}},<br>your hearing is confirmed.</p>",
  "x": 72, "y": 144, "width": 468, "height": 200 }

• {{merge_tag}} tokens substitute from data, HTML-escaped: merge values are data, never markup. Referenced tags appear in the version's merge-tag schema like any other.
• Content is limited to 64 KB per field and sanitized exactly like whole-document HTML.
• Content that overflows the box is truncated to it, with an HTML_FIELD_TRUNCATED warning.

For whole documents authored in HTML, where the content determines its own page count, see HTML documents.

Typography

text, field, table, and other text-bearing fields accept a typography object, merged per field:

service defaults ← document typography ← field typography

Property	Values	Default
font_family	Mapped to the nearest built-in font: helvetica/arial/verdana/trebuchet → Helvetica; times/georgia/palatino → Times Roman; courier → Courier	Helvetica
font_size	6–72	12
font_style	normal, bold, italic, bolditalic	normal
text_color	Hex color	#000000
line_height	0.5–3	1.2
text_align	left, center, right, justify (renders as left)	left
auto_size	Shrink text to fit the box	true
word_wrap	Wrap long lines	false
direction	ltr, rtl, auto (requires Unicode mode)	ltr

Unrecognized typography values fall back to defaults; they never reject a request.