Create document fields

curl --request POST \
  --url https://app.sajn.se/api/v1/documents/{id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    {
      "type": "TEXT",
      "position": 0,
      "fieldMeta": {
        "type": "TEXT",
        "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>",
        "locked": false,
        "sectionStyle": {
          "background": "NONE",
          "padding": "NONE",
          "bleed": false,
          "border": false
        },
        "hidden": false
      }
    }
  ]
}
'

import requests

url = "https://app.sajn.se/api/v1/documents/{id}/fields"

payload = { "fields": [
        {
            "type": "TEXT",
            "position": 0,
            "fieldMeta": {
                "type": "TEXT",
                "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>",
                "locked": False,
                "sectionStyle": {
                    "background": "NONE",
                    "padding": "NONE",
                    "bleed": False,
                    "border": False
                },
                "hidden": False
            }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fields: [
      {
        type: 'TEXT',
        position: 0,
        fieldMeta: {
          type: 'TEXT',
          content: '<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>',
          locked: false,
          sectionStyle: {background: 'NONE', padding: 'NONE', bleed: false, border: false},
          hidden: false
        }
      }
    ]
  })
};

fetch('https://app.sajn.se/api/v1/documents/{id}/fields', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.sajn.se/api/v1/documents/{id}/fields",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fields' => [
        [
                'type' => 'TEXT',
                'position' => 0,
                'fieldMeta' => [
                                'type' => 'TEXT',
                                'content' => '<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>',
                                'locked' => false,
                                'sectionStyle' => [
                                                                'background' => 'NONE',
                                                                'padding' => 'NONE',
                                                                'bleed' => false,
                                                                'border' => false
                                ],
                                'hidden' => false
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sajn.se/api/v1/documents/{id}/fields"

	payload := strings.NewReader("{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sajn.se/api/v1/documents/{id}/fields")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sajn.se/api/v1/documents/{id}/fields")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "cm4k2x9p10009abcd1234efgh",
      "documentId": "cm4k2x9p10003abcd1234efgh",
      "templateId": null,
      "type": "TEXT",
      "position": 0,
      "fieldMeta": {
        "type": "TEXT",
        "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>"
      },
      "createdAt": "2026-09-28T09:12:00.000Z",
      "updatedAt": "2026-09-28T09:12:00.000Z"
    }
  ]
}

{
  "code": "VALIDATION_FAILED",
  "message": "Invalid input: expected array, received undefined",
  "userMessage": "Förfrågan innehåller ogiltiga värden.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "issues": [
    {
      "path": "fields",
      "code": "INVALID_TYPE",
      "message": "Invalid input: expected array, received undefined"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API token",
  "userMessage": "Ogiltig API-nyckel",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient OAuth scope: requires documents:write",
  "userMessage": "Applikationen saknar behörighet (scope) för denna åtgärd.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "requiredScopes": [
    "documents:write"
  ],
  "grantedScopes": [
    "profile:read"
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Field not found",
  "userMessage": "Resursen hittades inte.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "resource": "field"
}

{
  "code": "INVALID_STATE",
  "message": "The resource's current state doesn't allow the operation, such as editing a document that was already sent or downloading a file that isn't produced yet.",
  "userMessage": "Åtgärden är inte möjlig i resursens nuvarande status.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "RATE_LIMITED",
  "message": "API rate limit exceeded",
  "userMessage": "För många förfrågningar. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "userMessage": "Något gick fel.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "message": "A service the operation depends on, such as an eID provider or a connected integration, failed or is unavailable. Retry with exponential backoff.",
  "userMessage": "En extern tjänst svarar inte just nu. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Document fields

Create document fields

Adds fields to a document. Send the fields in fields, even when you create one.

Field Types:

TEXT - Rich text content section (Tiptap editor format)
HTML - Raw HTML content with custom styling (API-only, sanitized for security)
FORM - Form with input fields for signers
PDF - PDF file section
PRODUCT_TABLE - Product/service table with pricing
TABLE - Simple table with custom rows and columns
SPACER, PAGE_BREAK, DURATION - Layout and duration blocks

Field Position: Determines the order fields appear in the document (0-based index).

Field Metadata: Each field type has specific metadata requirements. See schema documentation for details.

Placing fields on a PDF: a PDF field renders an uploaded PDF (fieldMeta.value is the storage key returned by the files endpoint). Add boxes on its pages with fieldMeta.placedFields. Each entry has a unique id, page (0-based), rect (x, y, width, height in PDF points, origin at the bottom-left corner of the page), and a kind. The server fills pageWidth, pageHeight, and pageRotation from the PDF page when you omit them. If you send pageWidth and pageHeight, rect is measured on a page of that size and scaled to the real page. The box kinds are the following:

INPUT with inputType SIGNATURE or INITIALS and a partyId: a mark the party draws at signing, sealed into the PDF at that position.
INPUT with inputType TEXT, DATE, CHECKBOX or SELECT and a partyId: a value the party fills in before signing. Set required to block signing until it is filled.
STATIC with content (HTML): fixed text stamped at that position.

Set key on an INPUT box to fill it in by that key through PATCH /api/v1/documents/{id}/field-values. A key can contain lowercase letters, digits, hyphens, and underscores.

The following example creates a PDF field with a signature box:

{
  "fields": [
    {
      "type": "PDF",
      "position": 0,
      "fieldMeta": {
        "type": "PDF",
        "value": "f/org_123/abc123def/contract.pdf",
        "placedFields": [
          {
            "id": "sig-1",
            "kind": "INPUT",
            "inputType": "SIGNATURE",
            "page": 2,
            "rect": { "x": 72, "y": 96, "width": 200, "height": 48 },
            "pageWidth": 595.28,
            "pageHeight": 841.89,
            "partyId": "PARTY_ID",
            "required": true
          }
        ]
      }
    }
  ]
}

The request fails with an HTTP 400 Bad Request status code, and writes nothing, when a box has a page the PDF doesn’t have, doesn’t fit on its page, names a partyId that isn’t a party on the document, or is a SIGNATURE or INITIALS box without a party with the SIGNER role. The issues array in the response lists every problem with its path, such as fields.0.fieldMeta.placedFields.2.rect.

The response lists the created fields in request order, each in the same shape as GET /api/v1/documents/{id}/fields/{fieldId}. To add, move, or remove single boxes later, use PATCH /api/v1/documents/{id}/fields/{fieldId}/placed-fields.

Product tables: a PRODUCT_TABLE field’s price values are decimal amounts in the table’s currency, such as 1499.5, not minor units. vat is a rate in percent, such as 25.

HTML Field Security: HTML fields accept raw HTML but are automatically sanitized server-side to allow only safe formatting tags (p, div, span, headings, lists, tables, images) and basic CSS styling. Links, script tags, and dangerous attributes are stripped. Images support HTTP/HTTPS URLs and data URIs for inline images.

POST

api

documents

{id}

fields

Create document fields

curl --request POST \
  --url https://app.sajn.se/api/v1/documents/{id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    {
      "type": "TEXT",
      "position": 0,
      "fieldMeta": {
        "type": "TEXT",
        "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>",
        "locked": false,
        "sectionStyle": {
          "background": "NONE",
          "padding": "NONE",
          "bleed": false,
          "border": false
        },
        "hidden": false
      }
    }
  ]
}
'

import requests

url = "https://app.sajn.se/api/v1/documents/{id}/fields"

payload = { "fields": [
        {
            "type": "TEXT",
            "position": 0,
            "fieldMeta": {
                "type": "TEXT",
                "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>",
                "locked": False,
                "sectionStyle": {
                    "background": "NONE",
                    "padding": "NONE",
                    "bleed": False,
                    "border": False
                },
                "hidden": False
            }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fields: [
      {
        type: 'TEXT',
        position: 0,
        fieldMeta: {
          type: 'TEXT',
          content: '<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>',
          locked: false,
          sectionStyle: {background: 'NONE', padding: 'NONE', bleed: false, border: false},
          hidden: false
        }
      }
    ]
  })
};

fetch('https://app.sajn.se/api/v1/documents/{id}/fields', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.sajn.se/api/v1/documents/{id}/fields",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fields' => [
        [
                'type' => 'TEXT',
                'position' => 0,
                'fieldMeta' => [
                                'type' => 'TEXT',
                                'content' => '<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>',
                                'locked' => false,
                                'sectionStyle' => [
                                                                'background' => 'NONE',
                                                                'padding' => 'NONE',
                                                                'bleed' => false,
                                                                'border' => false
                                ],
                                'hidden' => false
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sajn.se/api/v1/documents/{id}/fields"

	payload := strings.NewReader("{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sajn.se/api/v1/documents/{id}/fields")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sajn.se/api/v1/documents/{id}/fields")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [\n    {\n      \"type\": \"TEXT\",\n      \"position\": 0,\n      \"fieldMeta\": {\n        \"type\": \"TEXT\",\n        \"content\": \"<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>\",\n        \"locked\": false,\n        \"sectionStyle\": {\n          \"background\": \"NONE\",\n          \"padding\": \"NONE\",\n          \"bleed\": false,\n          \"border\": false\n        },\n        \"hidden\": false\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "cm4k2x9p10009abcd1234efgh",
      "documentId": "cm4k2x9p10003abcd1234efgh",
      "templateId": null,
      "type": "TEXT",
      "position": 0,
      "fieldMeta": {
        "type": "TEXT",
        "content": "<p>Anställningen gäller tills vidare från och med den 1 november 2026, med sex månaders provanställning.</p>"
      },
      "createdAt": "2026-09-28T09:12:00.000Z",
      "updatedAt": "2026-09-28T09:12:00.000Z"
    }
  ]
}

{
  "code": "VALIDATION_FAILED",
  "message": "Invalid input: expected array, received undefined",
  "userMessage": "Förfrågan innehåller ogiltiga värden.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "issues": [
    {
      "path": "fields",
      "code": "INVALID_TYPE",
      "message": "Invalid input: expected array, received undefined"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API token",
  "userMessage": "Ogiltig API-nyckel",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient OAuth scope: requires documents:write",
  "userMessage": "Applikationen saknar behörighet (scope) för denna åtgärd.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "requiredScopes": [
    "documents:write"
  ],
  "grantedScopes": [
    "profile:read"
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Field not found",
  "userMessage": "Resursen hittades inte.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "resource": "field"
}

{
  "code": "INVALID_STATE",
  "message": "The resource's current state doesn't allow the operation, such as editing a document that was already sent or downloading a file that isn't produced yet.",
  "userMessage": "Åtgärden är inte möjlig i resursens nuvarande status.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "RATE_LIMITED",
  "message": "API rate limit exceeded",
  "userMessage": "För många förfrågningar. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "userMessage": "Något gick fel.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "message": "A service the operation depends on, such as an eID provider or a connected integration, failed or is unavailable. Retry with exponential backoff.",
  "userMessage": "En extern tjänst svarar inte just nu. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Authorizations

Authorization

string

header

required

Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.

Headers

Sajn-Version

enum<string>

API version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.

Available options:

2026-09,

2026-10

Idempotency-Key

string

Makes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.

Maximum string length: 255

Path Parameters

string

required

The document ID.

Body

application/json

Body

fields

object[]

required

The fields to create, in the order the response lists them

Minimum array length: 1

Show child attributes

Response

200

data

object[]

required

The created fields, in request order

Show child attributes

Get started

Core concepts

Guides

Webhooks

API fundamentals

Upgrading

sajn Login

API reference

Create document fields

Authorizations

Headers

Path Parameters

Body

Response