Custom fields
Define your own fields, such as a project code or a contract value, and set their values on documents
In this guide, you define a custom field for the workspace and set its value on documents. Custom fields hold structured data that's yours, such as a project code, a cost center, or a renewal date. You can use the values in invitation messages and to show or hide content.
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 document to set values on. For more information, see Create a document.
How custom fields work
A custom field definition has the following properties:
name: the name shown in the sajn app, such asProject code.type: what the field belongs to.DOCUMENTfields hold values on documents, andCONTACTfields hold values on contacts.inputType: the kind of value:TEXT,TEXTAREA,NUMBER,DATE,EMAIL,PHONE,URL,BOOLEAN,SELECT, orJSON.required: whether the field needs a value.options: forSELECT, the choices as an array of strings, such as["HR", "Sales"].defaultValue: optional.
Values are always strings. Send a number as "50000", a date as "2026-12-31", and a boolean as "true" or "false".
The API sets values on documents. CONTACT field values are set in the sajn app.
Define a field and set its value
Create the definition
Send a POST request to /api/v1/custom-fields:
curl -X POST https://app.sajn.se/api/v1/custom-fields \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Department",
"type": "DOCUMENT",
"inputType": "SELECT",
"options": ["HR", "Sales", "Engineering"],
"required": false
}'The response is the definition:
{
"id": "cm4k2xe9t0006abcd1357yzab",
"name": "Department",
"type": "DOCUMENT",
"inputType": "SELECT",
"defaultValue": null,
"required": false,
"options": ["HR", "Sales", "Engineering"],
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}Definitions are shared by the workspace. To find existing ones, call List all custom fields, optionally with type=DOCUMENT. The list is in data; while hasMore is true, pass nextCursor as cursor to get the next page.
Set the value on a document
Send customFields with the definition's id as customFieldId. You can send it when you create the document, or with a PATCH request:
curl -X PATCH https://app.sajn.se/api/v1/documents/DOCUMENT_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"customFields": [
{ "customFieldId": "cm4k2xe9t0006abcd1357yzab", "value": "Engineering" }
]
}'Replace DOCUMENT_ID with the document ID. To clear a value, send "value": null.
Read the values
Get the document. Its customFields array has every value, with the field's name and inputType as type:
curl https://app.sajn.se/api/v1/documents/DOCUMENT_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"The following example shows only customFields:
{
"customFields": [
{
"id": "cm4k2xe9t0006abcd1357yzab",
"name": "Department",
"type": "SELECT",
"value": "Engineering"
}
]
}Use the values
- In the invitation message:
{{custom.department}}inserts the value of the field namedDepartment. The slug is the field name in lowercase with hyphens. For more information, see Send a document for signing. - To show or hide content: a
TEXTorHTMLfield can have avisibilityRulewith acustomFieldId, a value inequals, and amodeofSHOW_WHENorHIDE_WHEN. - By document type: a document category (Dokumenttyp) scopes which custom fields apply to its documents. Set
documentMeta.documentCategoryId, and call List document categories to see each category'scustomFieldIds. - From a CRM: send
integrationLinkwhen you create a document, and sajn prefills mapped custom fields from the linked record. For more information, see CRM field integration.
Change or delete a definition
To rename a field or change its options, send a PATCH request to /api/v1/custom-fields/CUSTOM_FIELD_ID. Every property is optional, and type can't change. Changing inputType can make existing values invalid for the new type.
To delete a field, send a DELETE request to the same path. The response is { "id": "CUSTOM_FIELD_ID", "deleted": true }. Deleting a definition removes its values from every document and contact. To keep a copy of the definition, get it before you delete it.
Handle errors
400 VALIDATION_FAILED:name,type,inputType, orrequiredis missing or unknown, oroptionsis a JSON-encoded string instead of an array.404 NOT_FOUND: no custom field has the ID.
For the error shape and every code, see Errors.
Next steps
Was this page helpful?
Last updated on