Fields that parties fill in
Add form inputs and inline fields that a party fills in while signing, next to values you fill in yourself
In this guide, you add a form to a document. Some inputs you fill in before sending, and others the party fills in while signing, such as an address or a start date.
A FORM content block holds a grid of inputs, called subfields. A subfield with a partyId in its fieldMeta belongs to that party: it's empty when you send the document, and the party fills it in on the signing page. A subfield without a partyId is yours: you fill it in, and the party sees the value as read-only text.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Have a
DRAFTdocument with at least oneSIGNERparty, and the party'sid. For more information, see Create a document.
Add a form with party inputs
Create the FORM block
Send a POST request to /api/v1/documents/DOCUMENT_ID/content with the FORM block in a content array. Each subfield has an id that's unique in the form, a row and column in the grid, and its own fieldMeta. The following form has two values you fill in and two inputs for the party:
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"content": [
{
"type": "FORM",
"position": 1,
"fieldMeta": {
"type": "FORM",
"columns": 2,
"fields": [
{ "id": "company", "key": "company", "row": 0, "column": 0,
"fieldMeta": { "type": "INPUT", "label": "Company", "value": "Example AB" } },
{ "id": "role", "key": "role", "row": 0, "column": 1,
"fieldMeta": { "type": "INPUT", "label": "Role", "value": "Developer" } },
{ "id": "address", "key": "address", "row": 1, "column": 0,
"fieldMeta": { "type": "INPUT", "label": "Home address", "partyId": "PARTY_ID", "required": true } },
{ "id": "start-date", "key": "start-date", "row": 1, "column": 1,
"fieldMeta": { "type": "DATEPICKER", "label": "Preferred start date", "partyId": "PARTY_ID" } }
]
}
}
]
}'Replace the following:
DOCUMENT_ID: the ID of the draft document.PARTY_ID: theidof the party who fills in the inputs.
The response has the created FORM block in data. position is the block's 0-based place among the document's content blocks.
A subfield's key lets you fill it in later without knowing the block ID. Keys can contain lowercase letters, digits, hyphens, and underscores.
Change your values before sending
To change the values you fill in, use Fill in values on a document with the subfield keys. It writes every value in one request:
curl -X PATCH https://app.sajn.se/api/v1/documents/DOCUMENT_ID/field-values \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{ "values": [ { "key": "role", "value": "Senior developer" } ] }'The response lists the outcome for each key in results. You can also send a value for an input that the party fills in, such as address. While the document is a draft, that value prefills the input, and the party can change it before signing.
Send the document
Send the document as usual. On the signing page, the party sees Company and Role as text, and Home address and Preferred start date as inputs. The party can't sign until every required input is filled in.
After signing, the values are on the document. Read them with List the fillable values on a document. The values are in data, and each value the party filled in has filledBy set to SIGNER and the partyId of that party.
Subfield types
The subfield type is fieldMeta.type, in uppercase. Every type takes label, placeholder, description, partyId, and required:
INPUT: a single-line text input. The value is invalue.TEXT: a text area.rowssets its height, from 2 to 20.NUMBER: a number input.DATEPICKER: a date picker.SELECT: a drop-down list. Setoptionsto a list such as[{ "value": "Engineering" }, { "value": "Sales" }], and optionallydefaultValue.RADIO: one choice fromoptions.CHECKBOX: any number of choices fromoptions. The selected values are invalues.ATTACHMENT: a file that the party uploads.allowedTypestakesPDFandIMAGE. After the upload,valueis{ filename, mimeType, size }.
A lowercase type, such as input, fails with 400 VALIDATION_FAILED.
Give each party their own inputs
When a document has several signing parties, set each subfield's partyId to the party who owns it. A party can only fill in their own inputs. Another party's inputs show as empty until that party fills them in. For the signing order, see Multi-party signing.
Change who fills in a subfield
To move a subfield to another party, or back to yourself, update the FORM block that holds it. A PATCH request replaces the block's whole fieldMeta, so start from the stored one:
- To find the FORM block by the subfield's key, call
GET /api/v1/documents/DOCUMENT_ID/content?key=address. The block is indata. - In its
fieldMeta.fields, change the subfield'spartyId. To fill the subfield in yourself, setpartyIdtonulland setvalue. - Send the whole
fieldMetato Update a document content block:
curl -X PATCH https://app.sajn.se/api/v1/documents/DOCUMENT_ID/content/CONTENT_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"fieldMeta": {
"type": "FORM",
"columns": 2,
"fields": [
{ "id": "company", "key": "company", "row": 0, "column": 0,
"fieldMeta": { "type": "INPUT", "label": "Company", "value": "Example AB" } },
{ "id": "role", "key": "role", "row": 0, "column": 1,
"fieldMeta": { "type": "INPUT", "label": "Role", "value": "Developer" } },
{ "id": "address", "key": "address", "row": 1, "column": 0,
"fieldMeta": { "type": "INPUT", "label": "Home address", "partyId": null, "value": "Storgatan 1, Stockholm" } },
{ "id": "start-date", "key": "start-date", "row": 1, "column": 1,
"fieldMeta": { "type": "DATEPICKER", "label": "Preferred start date", "partyId": "PARTY_ID" } }
]
}
}'Replace CONTENT_ID with the FORM block's id. The response is the updated FORM block. A block is addressed by its ID only; to change a value without changing who fills it in, use Fill in values on a document instead.
Inline fields in text
To let a party fill in a value in the middle of a sentence, such as their personal address in an agreement, put a <sajn-field> tag in the content of a TEXT or HTML block:
{
"content": [
{
"type": "HTML",
"position": 0,
"fieldMeta": {
"type": "HTML",
"content": "<p>The employee lives at <sajn-field key=\"home-address\" party=\"PARTY_ID\" type=\"TEXT\" label=\"Home address\"></sajn-field> and starts on <sajn-field key=\"start-date\" party=\"PARTY_ID\" type=\"DATE\" label=\"Start date\"></sajn-field>.</p>"
}
}
]
}Replace PARTY_ID with the id of the party. A <sajn-field> tag takes the following attributes:
key: a stable name for the field, such ashome-address.party: theidof the party who fills it in.type:TEXT,DATE, orSELECT. Default:TEXT.label: the text the party sees in the empty field.description: optional help text for the party.required:trueorfalse. Iftrue, the party can't sign until the field is filled in. Default:true.options: forSELECT, the choices, separated by commas, such asoptions="Full time, Part time".value: the party's answer. sajn sets it when the party signs.
sajn returns the tag in the same form in TEXT and HTML content. HTML attribute values stay HTML-escaped, so a quotation mark in a label is ". List the fillable values on a document lists inline fields with kind set to INLINE, so you can prefill them by key and read the party's answer after signing. The answer is also in the value attribute of the tag. A key names one field in the document, but you can place the same <sajn-field> again for the same party, such as a name that appears twice.
Handle errors
400 VALIDATION_FAILED: a subfield is invalid, for example withoutrow, with an unknown or lowercasetype, or withsignerIdinstead ofpartyId. Readissuesfor the path.409 INVALID_STATE: the document isn't aDRAFT. Content can change only before sending.404 NOT_FOUND: no content block on the document has the ID.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on