PDF content block holds one uploaded PDF. The boxes on its pages are in fieldMeta.placedFields, an array where each entry is one box, drawn in array order.
Before you begin
- Store your API key in the
SAJN_API_KEYenvironment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys). - Have a
DRAFTdocument with its parties, and each party’sid. For more information, see Create a document. - Upload the PDF file and keep the storage
key. For more information, see Upload files.
Coordinates
A box’s position is relative to its page, so the same values work on any page size:page: the page the box is on, counted from 1.rect:x,y,width, andheightas fractions of the page, from0to1.xandyare measured from the top-left corner of the page, andygrows downward. For example,{ "x": 0.5, "y": 0, "width": 0.5, "height": 0.1 }covers the right half of the top tenth of the page.pageWidthandpageHeight: the page size in PDF points (1/72 inch). A4 portrait is595.28by841.89. You can leave them out of a request; sajn reads them from the PDF.pageRotation: optional.0,90,180, or270. If you leave it out, sajn reads it from the PDF.
Send PDF points instead
If your layout is in PDF points measured from the bottom-left corner, as in AcroForm fields and most PDF libraries, send it as is and set two properties on the box:unit:POINTS. The default isRELATIVE, fractions of the page.origin:BOTTOM_LEFT, whereygrows upward. The default isTOP_LEFT.
unit and origin apply only to the request. Responses always give rect in fractions from the top-left corner, with pageWidth and pageHeight in points. To convert a response back to points from the bottom-left corner, use x = rect.x * pageWidth and y = (1 - rect.y - rect.height) * pageHeight.
Box kinds
Each box has anid that’s unique in the PDF block, and a kind:
INPUTwithinputTypeSIGNATUREorINITIALS: a mark that the party inpartyIddraws when signing. sajn seals the mark into the PDF at this position. The party must have theSIGNERrole.INPUTwithinputTypeTEXT,DATE,CHECKBOX, orSELECT: a value that the party inpartyIdfills in before signing. AddoptionsforSELECTand"multiline": truefor long text. Ifrequiredistrue, the party can’t sign until it’s filled in. Without apartyId, you fill the box in yourself.STATIC: fixed text that you stamp on the page.contentis HTML, andstyletakesfontSize(6 to 72),color(hex),bold,italic, andalign(LEFT,CENTER, orRIGHT).
input, fails with 400 VALIDATION_FAILED. To fill in an INPUT box through the API, give it a key. Keys can contain lowercase letters, digits, hyphens, and underscores.
Place the boxes
1
Create the PDF block with its boxes
Send a Replace the following:
POST request to /api/v1/documents/DOCUMENT_ID/content with the PDF block in a content array. The following request places a signature near the bottom of page 3, a start-date input on page 1, and a reference number in the top-right corner of page 1:DOCUMENT_ID: the ID of the draft document.STORAGE_KEY: thekeyfrom the file upload.PARTY_ID: theidof the signing party.
data. Store its id for the next step.sajn checks every box before it writes anything. The request fails with 400 VALIDATION_FAILED, and writes nothing, when a box’s page doesn’t exist, its rect doesn’t fit on the page, sajn can’t read the page size from the PDF and the box has no pageWidth and pageHeight, its partyId isn’t a party on the document, or it’s a signature or initials box for a party without the SIGNER role.2
Move, add, or remove single boxes
To change boxes without sending the whole block again, send a Replace
PATCH request to /api/v1/documents/DOCUMENT_ID/content/CONTENT_ID/placed-fields:CONTENT_ID with the PDF block’s id. The request works as follows:- A box in
upsertwith an existingidreplaces that box and keeps its drawing order. A box with a newidis added on top. removelists 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
issueslists every problem.
fieldMeta after the change.3
Read the layout back
List the document’s content:The response lists every content block in position order in
data. The PDF block has the placedFields you sent, with rect in fractions from the top-left corner, also for a box you sent in points, and pageWidth, pageHeight, and pageRotation filled in. The following example leaves out most boxes:GET /api/v1/documents/DOCUMENT_ID?expand=content returns the same blocks in the document’s content array.Fill in boxes and PDF form fields
To fill in anINPUT box that has no partyId, use Fill in values on a document with the box’s key. The same endpoint fills in the uploaded PDF’s own form fields (AcroForm fields), which sajn lists in fieldMeta.formFields with an uppercase type: TEXT, CHECKBOX, DROPDOWN, or RADIO. A form field’s page and rect use the same model as a box: pages counted from 1, and fractions of the page from the top-left corner. To see every fillable key, call List the fillable values on a document. The values are in data: values with kind set to PDF_PLACED are boxes, and values with kind set to PDF_ACROFORM are the PDF’s own form fields.
Use placements on templates
The same requests work on templates, through/api/v1/templates/TEMPLATE_ID/content and /api/v1/templates/TEMPLATE_ID/content/CONTENT_ID/placed-fields. On a template, partyId refers to a template party. A document created from the template gets the boxes, mapped to the matching document parties.
Handle errors
A placement error lists every invalid box inissues, with its path:
400 VALIDATION_FAILED: a box is invalid, uses a lowercase enum value such assignature, or uses a 2026-09 name such assignerIdinstead ofpartyId. A box in 2026-09 coordinates, withpagecounted from 0 andrectin points, usually fails the fit check: add 1 topage, and setunittoPOINTSandorigintoBOTTOM_LEFT.409 INVALID_STATE: the document isn’t aDRAFT, or another edit changed the block while the request ran. In the second case, send the request again.
Next steps
Send for signing
Send the document to its parties.
Fields that parties fill in
Add form inputs outside the PDF.
Add, update, or remove boxes
See the placed-fields endpoint in the API reference.
Fields
Learn how content and fields work.

