Skip to Content

Create a document field

You're viewing API version 2026-09, which is deprecated and stops working on October 1, 2027. To move your integration, see Upgrading to 2026-10.
POST
/api/v1/documents/{id}/fields

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.

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*string

Header Parameters

authorization*string

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.

Lengthlength <= 255

Request Body

Body

application/json
  1. body
type*string
Value in"TEXT""HTML""FORM""PDF""PRODUCT_TABLE""TABLE""SPACER""PAGE_BREAK""DURATION"
position*integer
Range0 <= value <= 9007199254740991
key?string
Match^[a-z0-9_-]*$
fieldMeta*||||||||

Response Body

Error response

application/json
  1. response

Error response

message*string

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?array<>

Every validation issue, on a 400 for an invalid request

requiredScopes?array<string>

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

grantedScopes?array<string>

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

Example Request
curl -X POST 'https://app.sajn.se/api/v1/documents/string/fields' \  -H 'authorization: string' \  -H 'Content-Type: application/json' \  -d '{  "type": "TEXT",  "position": 0,  "fieldMeta": {    "type": "TEXT"  }}'
Example Response
{  "message": "string",  "code": "string",  "errorId": "string",  "issues": [    {      "path": "string",      "message": "string"    }  ],  "requiredScopes": [    "string"  ],  "grantedScopes": [    "string"  ]}

Was this page helpful?