Content and fields
The content blocks of a document, the fields parties fill in, and how to address them by key
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.
flowchart TD
doc["Document or template"] --> f0["Block, position 0: TEXT"]
doc --> f1["Block, position 1: FORM"]
doc --> f2["Block, position 2: PDF"]
doc --> f3["Block, position 3: PRODUCT_TABLE"]
f0 --> inline["Inline fields: sajn-field tags in the text"]
f1 --> sub["Subfields: INPUT, DATEPICKER, CHECKBOX, and more<br/>each with a key and an optional partyId"]
f2 --> placed["placedFields: boxes on the PDF pages<br/>SIGNATURE, INITIALS, TEXT, DATE, and more"]
f2 --> acro["formFields: form fields inside the PDF"]Content block anatomy
Every content block has the following properties:
| Property | Description |
|---|---|
id | The content block ID. |
documentId, templateId | The document or template the block belongs to. The other one is null. |
type | The block type, such as TEXT or PDF. |
position | The 0-based order of the block in the document. |
fieldMeta | The type-specific content and settings. fieldMeta.type always equals type. |
The following content block is a short HTML section:
{
"id": "cm4k2x9p50007abcd7890uvwx",
"documentId": "cm4k2x9p10001abcd1234efgh",
"templateId": null,
"type": "HTML",
"position": 0,
"fieldMeta": {
"type": "HTML",
"content": "<h2>Scope of work</h2><p>Example AB delivers the services in Appendix 1.</p>"
}
}Content block types
| Type | Content |
|---|---|
TEXT | Rich text, as written in the sajn editor. |
HTML | HTML that you send through the API. sajn sanitizes it and keeps only safe formatting. For more information, see HTML content. |
FORM | A grid of input subfields, such as text inputs, dates, and checkboxes. |
PDF | An uploaded PDF. It can carry boxes placed on its pages, and form fields from the PDF itself. |
PRODUCT_TABLE | Products or services with prices, quantities, discounts, and totals. For more information, see Product tables. |
TABLE | A table with your own columns and rows. |
DURATION | The agreement's term and notice period, written out as text. A document has at most one. |
SPACER | Vertical space. |
PAGE_BREAK | A page break in the PDF. |
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
FORMblock'sfieldMeta.fieldslists its subfields in a grid ofrowandcolumn. A subfield's type isINPUT,TEXT,SELECT,DATEPICKER,RADIO,CHECKBOX,NUMBER, orATTACHMENT. - Placed fields. A
PDFblock'sfieldMeta.placedFieldslists boxes placed on its pages. Each box has apage, counted from 1, arectin fractions of the page from its top-left corner, and akind:INPUTfor a value or mark, orSTATICfor fixed text. - PDF form fields. A
PDFblock'sfieldMeta.formFieldslists the form fields that were already in the uploaded PDF. - Inline fields. A
TEXTorHTMLblock'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:
partyId | Who fills the value | When |
|---|---|---|
| Set | The party | On the signing page, before signing. Set required to block signing until the value is filled. |
| Not set | You | Before you send the document, through the API or the editor |
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:
{
"type": "FORM",
"position": 1,
"fieldMeta": {
"type": "FORM",
"columns": 2,
"fields": [
{
"id": "customer-name",
"key": "customer-name",
"type": "INPUT",
"row": 0,
"column": 0,
"fieldMeta": { "type": "INPUT", "label": "Customer", "value": "Example AB" }
},
{
"id": "start-date",
"key": "start-date",
"type": "DATEPICKER",
"row": 0,
"column": 1,
"fieldMeta": {
"type": "DATEPICKER",
"label": "Start date",
"partyId": "cm4k2x9p20002abcd5678ijkl",
"required": true
}
}
]
}
}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
PDFblocks 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:
-
To list every value on the document and its key, call
GET /documents/{id}/field-values. -
To fill in several values in one request, call
PATCH /documents/{id}/field-values:{ "values": [ { "key": "customer-name", "value": "Example AB" }, { "key": "org-number", "value": "556000-0000" }, { "key": "accept-terms", "value": true } ] }
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
Was this page helpful?
Last updated on