Skip to main content
A document’s content is an ordered list of content blocks, such as a section of text, an uploaded PDF, a form, or a product table. Templates have content in the same shape, and a document created from a template gets a copy of it. A field is a value inside the content that someone fills in: you, before you send the document, or a party, before they sign. Fields live in content blocks: as subfields of a form, as boxes on a PDF, as form fields inside a PDF, or inline in a text section.

Content block anatomy

Every content block has the following properties: The following content block is a short HTML section:

Content block types

Most types also accept the following settings in fieldMeta: locked freezes the block in the editor, hidden hides it, and visibilityRule shows it only when a custom field has a given value. To add content, send the blocks in a content array to POST /documents/{id}/content, also when you add one. To read them, pass expand=content to GET /documents/{id}, or call GET /documents/{id}/content. You can change content only while a document is a DRAFT.

Values that someone fills in

Fields come in four kinds:
  • FORM subfields. A FORM block’s fieldMeta.fields lists its subfields in a grid of row and column. A subfield’s type is INPUT, TEXT, SELECT, DATEPICKER, RADIO, CHECKBOX, NUMBER, or ATTACHMENT.
  • Placed fields. A PDF block’s fieldMeta.placedFields lists boxes placed on its pages. Each box has a page, counted from 1, a rect in fractions of the page from its top-left corner, and a kind: INPUT for a value or mark, or STATIC for fixed text.
  • PDF form fields. A PDF block’s fieldMeta.formFields lists the form fields that were already in the uploaded PDF.
  • Inline fields. A TEXT or HTML block’s text can hold <sajn-field> tags, each a text, date, or choice that a party fills in where it stands in the sentence. For more information, see Fields that parties fill in.
Who fills a value depends on partyId: A placed box with inputType set to SIGNATURE or INITIALS is a signature mark. The party draws it when they sign, and sajn seals it into the PDF at that position. A signature mark must belong to a party with the SIGNER role. For the coordinate model, see Place fields on a PDF. The following FORM block has one subfield that you fill in and one that the party fills in:
In API version 2026-10, fieldMeta names the party partyId, and every enum inside it is uppercase. API version 2026-09 calls the party signerId, spells these enums in lowercase, and calls content blocks fields.

Fill in values by key

A key is a stable name for a value, such as customer-name. Keys can contain lowercase letters, digits, hyphens, and underscores. Set keys on FORM subfields, placed boxes, and inline fields in a template, and every document created from it has the same keys. A key names one field within a document or template. A request that would give two different fields the same key fails with 400 VALIDATION_FAILED, and a document that already has a duplicate key can’t be sent until you rename one of them: the send fails with 409 DOCUMENT_NOT_READY and the readiness code DUPLICATE_KEY.

One field in several places

Some fields share a key because they are one field placed more than once:
  • Fields that the same party fills in, with the same key and the same kind: text, date, or a choice. The kind doesn’t depend on where the field sits, so a FORM subfield, a placed box, and a <sajn-field> can be copies of one field.
  • One AcroForm field that spans several PDF blocks after a page split.
The party fills in such a field once, and every copy shows the value. GET /documents/{id}/field-values lists the field once, and a value you send with the key fills every copy. The value must be valid in every copy. Checkboxes and attachments are never shared. Copies must have the same options and validation rules, such as a format or a number limit. If they don’t, the readiness check reports SHARED_FIELD_SETTINGS and the document can’t be sent. A number field and a free text field differ in rules, so give them different keys. The same key on fields that different parties fill in, or on fields of different kinds, is still a duplicate. In a bundle, the same rule reaches across documents. When a party fills in a field, the same field in the bundle’s other documents starts with that answer. Each document still signs and seals its own values. To fill in values by key, use the field values endpoints:
  1. To list every value on the document and its key, call GET /documents/{id}/field-values.
  2. To fill in several values in one request, call PATCH /documents/{id}/field-values:
The same request works for FORM subfields, placed boxes, PDF form fields, and inline fields, which the list shows with kind set to FORM, PDF_PLACED, PDF_ACROFORM, and INLINE. You can fill in values while the document is a DRAFT or IMPORTED. On a draft, a value for a field that a party fills in, with filledBy set to SIGNER, prefills it: the party sees your value on the signing page and can change it. A value fails, and the other values are still written, when its key doesn’t exist, when two fields share the key, or when the value doesn’t match the field’s type or options. The results array lists the outcome for each key: success, and when it’s false, an error with code, message, and userMessage. remaining lists the keys of required values that you fill in and that are still empty.

Next steps

Templates and forms

Reuse content and keys across documents.

Fields that parties fill in

Collect values from parties at signing.

Place fields on a PDF

Place signature marks and inputs on an uploaded PDF.

Product tables

Sell products and services in a document.