Create a document field

curl --request POST \
  --url https://app.sajn.se/api/v1/documents/{id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "position": 4503599627370495,
  "fieldMeta": {
    "type": "TEXT",
    "content": "<string>",
    "locked": true,
    "sectionStyle": {
      "bleed": true,
      "border": true
    },
    "hidden": true
  },
  "key": "<string>"
}
'

import requests

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

payload = {
    "position": 4503599627370495,
    "fieldMeta": {
        "type": "TEXT",
        "content": "<string>",
        "locked": True,
        "sectionStyle": {
            "bleed": True,
            "border": True
        },
        "hidden": True
    },
    "key": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    authorization: '<authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    position: 4503599627370495,
    fieldMeta: {
      type: 'TEXT',
      content: '<string>',
      locked: true,
      sectionStyle: {bleed: true, border: true},
      hidden: true
    },
    key: '<string>'
  })
};

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([
    'position' => 4503599627370495,
    'fieldMeta' => [
        'type' => 'TEXT',
        'content' => '<string>',
        'locked' => true,
        'sectionStyle' => [
                'bleed' => true,
                'border' => true
        ],
        'hidden' => true
    ],
    'key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$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  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\n}")

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

	req.Header.Add("authorization", "<authorization>")
	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", "<authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\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"] = '<authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\n}"

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

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

Document Fields

Create a document field

Add a field/section to a document. Can create single field or multiple fields at once.

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 signerId: a mark the party draws at signing, sealed into the PDF at that position.
input with inputType text, date, checkbox or select and a signerId: 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.

Example:

{
  "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,
        "signerId": "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 signerId 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 fieldMeta.placedFields.2.rect.

Read the result back with GET /api/v1/documents/{id}/fields. To add, move, or remove single boxes later, use PATCH /api/v1/documents/{id}/fields/{fieldId}/placed-fields.

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 a document field

curl --request POST \
  --url https://app.sajn.se/api/v1/documents/{id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "position": 4503599627370495,
  "fieldMeta": {
    "type": "TEXT",
    "content": "<string>",
    "locked": true,
    "sectionStyle": {
      "bleed": true,
      "border": true
    },
    "hidden": true
  },
  "key": "<string>"
}
'

import requests

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

payload = {
    "position": 4503599627370495,
    "fieldMeta": {
        "type": "TEXT",
        "content": "<string>",
        "locked": True,
        "sectionStyle": {
            "bleed": True,
            "border": True
        },
        "hidden": True
    },
    "key": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    authorization: '<authorization>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    position: 4503599627370495,
    fieldMeta: {
      type: 'TEXT',
      content: '<string>',
      locked: true,
      sectionStyle: {bleed: true, border: true},
      hidden: true
    },
    key: '<string>'
  })
};

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([
    'position' => 4503599627370495,
    'fieldMeta' => [
        'type' => 'TEXT',
        'content' => '<string>',
        'locked' => true,
        'sectionStyle' => [
                'bleed' => true,
                'border' => true
        ],
        'hidden' => true
    ],
    'key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$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  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\n}")

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

	req.Header.Add("authorization", "<authorization>")
	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", "<authorization>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\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"] = '<authorization>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"position\": 4503599627370495,\n  \"fieldMeta\": {\n    \"type\": \"TEXT\",\n    \"content\": \"<string>\",\n    \"locked\": true,\n    \"sectionStyle\": {\n      \"bleed\": true,\n      \"border\": true\n    },\n    \"hidden\": true\n  },\n  \"key\": \"<string>\"\n}"

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

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

{
  "message": "<string>",
  "code": "<string>",
  "errorId": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "requiredScopes": [
    "<string>"
  ],
  "grantedScopes": [
    "<string>"
  ]
}

You’re viewing API version 2026-09, which is deprecated and stops working on October 1, 2027. To see the current version, select 2026-10 in the menu at the top of the sidebar. To move your integration, see Upgrading to 2026-10.

Authorizations

Authorization

string

header

required

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

Headers

authorization

string

required

Bearer token for API authentication

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

Body

application/json

Body

object
object[]

type

enum<string>

required

Available options:

TEXT,

HTML,

FORM,

PDF,

PRODUCT_TABLE,

TABLE,

SPACER,

PAGE_BREAK,

DURATION

position

integer

required

Required range: 0 <= x <= 9007199254740991

fieldMeta

object

required

Show child attributes

key

string

Pattern: ^[a-z0-9_-]*$

Response

Error response

message

string

required

Error message describing what went wrong

code

string

Machine-readable error code (e.g. APPROVAL_REQUIRED)

errorId

string

Identifier for this occurrence — quote it to support when reporting a 500

issues

object[]

Every validation issue, on a 400 for an invalid request

Show child attributes

requiredScopes

string[]

OAuth scopes the endpoint requires, on a 403 for a missing scope

grantedScopes

string[]

OAuth scopes the token was granted, on a 403 for a missing scope

Overview

Login

System

Account

Workspaces

Members

Workspace Roles

Documents

Document Parties

Document Comments

Document Chat

Files

Folders

Blocks

Document Signers

Document Approval

Document Fields

Document Tags

Templates

Forms

Contacts

Companies

Tags

Document Categories

Custom Fields

Webhooks

Events

sajn ID

Organization

Helpers

API Reference

Create a document field

Authorizations

Headers

Path Parameters

Body

Response