Skip to Content

Add, update, or remove boxes on a PDF 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.
PATCH
/api/v1/documents/{id}/fields/{fieldId}/placed-fields

Changes individual boxes on a PDF field without sending the whole field. Only DRAFT documents can be changed.

Each box in upsert has the same shape as an entry in fieldMeta.placedFields on POST /api/v1/documents/{id}/fields, and is checked the same way. A box whose id already exists on the field replaces that box and keeps its stacking order. A box with a new id is added on top. remove lists the ids of boxes to delete. Boxes you don't mention stay as they are.

The change is atomic: if any box is invalid, nothing is written and the response lists every problem in issues. If another edit changes the field while the request runs, the request fails with an HTTP 400 Bad Request status code and code INVALID_STATE; send it again.

Example - move one box and remove another:

PATCH /api/v1/documents/{docId}/fields/{fieldId}/placed-fields{  "upsert": [    {      "id": "sig-1",      "kind": "input",      "inputType": "signature",      "page": 2,      "rect": { "x": 72, "y": 120, "width": 200, "height": 48 },      "signerId": "PARTY_ID"    }  ],  "remove": ["initials-3"]}

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*string
fieldId*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
upsert*array<|>

Boxes to add or replace. A box whose id already exists on the field replaces that box and keeps its stacking order; any other box is added on top.

Itemsitems <= 500
Default[]
remove*array<>

Ids of boxes to remove from the field.

Itemsitems <= 500
Default[]

Response Body

200

application/json
  1. response
id*string

The PDF field id

type*string
Value in"TEXT""HTML""FORM""PDF""PRODUCT_TABLE""TABLE""SPACER""PAGE_BREAK""DURATION"
position*number
fieldMeta*||||||||

The PDF field metadata after the change, including every box in placedFields

documentId*string
Example Request
curl -X PATCH 'https://app.sajn.se/api/v1/documents/string/fields/string/placed-fields' \  -H 'authorization: string' \  -H 'Content-Type: application/json' \  -d '{  "upsert": [],  "remove": []}'
Example Response
{  "id": "string",  "type": "TEXT",  "position": 0,  "fieldMeta": {    "type": "TEXT",    "content": "string",    "locked": true,    "sectionStyle": {      "background": "none",      "padding": "none",      "bleed": true,      "border": true    },    "visibilityRule": {      "customInputId": "string",      "equals": "string",      "mode": "SHOW_WHEN"    },    "hidden": true  },  "documentId": "string"}

Was this page helpful?