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
1
Create the FORM block
Send a Replace the following:
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:DOCUMENT_ID: the ID of the draft document.PARTY_ID: theidof the party who fills in the inputs.
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.2
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: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.3
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 isfieldMeta.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 }.
input, fails with 400 VALIDATION_FAILED.
Give each party their own inputs
When a document has several signing parties, set each subfield’spartyId 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. APATCH 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:
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:
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.
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.
Next steps
Place fields on a PDF
Put inputs and signature boxes on an uploaded PDF.
Templates and forms
Reuse a form across documents.
Content and fields
Learn how content and fields work.
Create document content
See every content block type in the API reference.

