Custom fields

​

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 document to set values on. For more information, see Create a document.

​

How custom fields work

• name: the name shown in the sajn app, such as Project code.
• type: what the field belongs to. DOCUMENT fields hold values on documents, and CONTACT fields hold values on contacts.
• inputType: the kind of value: TEXT, TEXTAREA, NUMBER, DATE, EMAIL, PHONE, URL, BOOLEAN, SELECT, or JSON.
• required: whether the field needs a value.
• options: for SELECT, the choices as an array of strings, such as ["HR", "Sales"].
• defaultValue: optional.

​

Define a field and set its value

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
  }'

const response = await fetch("https://app.sajn.se/api/v1/custom-fields", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAJN_API_KEY}`,
    "Sajn-Version": "2026-10",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Department",
    type: "DOCUMENT",
    inputType: "SELECT",
    options: ["HR", "Sales", "Engineering"],
    required: false,
  }),
});
const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.message} (request ${body.requestId})`);
}
console.log(body.id);

import os

import requests

response = requests.post(
    "https://app.sajn.se/api/v1/custom-fields",
    headers={
        "Authorization": f"Bearer {os.environ['SAJN_API_KEY']}",
        "Sajn-Version": "2026-10",
    },
    json={
        "name": "Department",
        "type": "DOCUMENT",
        "inputType": "SELECT",
        "options": ["HR", "Sales", "Engineering"],
        "required": False,
    },
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body['code']}: {body['message']} (request {body['requestId']})")
print(body["id"])

{
  "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"
}

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" }
    ]
  }'

curl https://app.sajn.se/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10"

{
  "customFields": [
    {
      "id": "cm4k2xe9t0006abcd1357yzab",
      "name": "Department",
      "type": "SELECT",
      "value": "Engineering"
    }
  ]
}

​

Use the values

• In the invitation message: {{custom.department}} inserts the value of the field named Department. 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 TEXT or HTML field can have a visibilityRule with a customFieldId, a value in equals, and a mode of SHOW_WHEN or HIDE_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’s customFieldIds.
• From a CRM: send integrationLink when 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

​

Handle errors

• 400 VALIDATION_FAILED: name, type, inputType, or required is missing or unknown, or options is a JSON-encoded string instead of an array.
• 404 NOT_FOUND: no custom field has the ID.

​

Next steps