Skip to main content
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_KEY environment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys).
  • Have a DRAFT document with at least one SIGNER party, and the party’s id. For more information, see Create a document.

Add a form with party inputs

1

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:
Replace the following:
  • DOCUMENT_ID: the ID of the draft document.
  • PARTY_ID: the id of 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.
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 is fieldMeta.type, in uppercase. Every type takes label, placeholder, description, partyId, and required:
  • INPUT: a single-line text input. The value is in value.
  • TEXT: a text area. rows sets its height, from 2 to 20.
  • NUMBER: a number input.
  • DATEPICKER: a date picker.
  • SELECT: a drop-down list. Set options to a list such as [{ "value": "Engineering" }, { "value": "Sales" }], and optionally defaultValue.
  • RADIO: one choice from options.
  • CHECKBOX: any number of choices from options. The selected values are in values.
  • ATTACHMENT: a file that the party uploads. allowedTypes takes PDF and IMAGE. After the upload, value is { 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:
  1. To find the FORM block by the subfield’s key, call GET /api/v1/documents/DOCUMENT_ID/content?key=address. The block is in data.
  2. In its fieldMeta.fields, change the subfield’s partyId. To fill the subfield in yourself, set partyId to null and set value.
  3. Send the whole fieldMeta to Update a document content block:
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:
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 as home-address.
  • party: the id of the party who fills it in.
  • type: TEXT, DATE, or SELECT. Default: TEXT.
  • label: the text the party sees in the empty field.
  • description: optional help text for the party.
  • required: true or false. If true, the party can’t sign until the field is filled in. Default: true.
  • options: for SELECT, the choices, separated by commas, such as options="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 &quot;. 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 without row, with an unknown or lowercase type, or with signerId instead of partyId. Read issues for the path.
  • 409 INVALID_STATE: the document isn’t a DRAFT. 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

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.