Skip to main content
In this guide, you place boxes on the pages of an uploaded PDF: a signature that a party draws when signing, an input that a party fills in, and fixed text that you stamp. Then you move a box and read the layout back. A 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_KEY environment variable. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys).
  • Have a DRAFT document with its parties, and each party’s id. 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, and height as fractions of the page, from 0 to 1. x and y are measured from the top-left corner of the page, and y grows 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.
  • pageWidth and pageHeight: the page size in PDF points (1/72 inch). A4 portrait is 595.28 by 841.89. You can leave them out of a request; sajn reads them from the PDF.
  • pageRotation: optional. 0, 90, 180, or 270. 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 is RELATIVE, fractions of the page.
  • origin: BOTTOM_LEFT, where y grows upward. The default is TOP_LEFT.
The following box puts a signature 72 points from the left edge and 96 points from the bottom edge of page 3:
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 an id that’s unique in the PDF block, and a kind:
  • INPUT with inputType SIGNATURE or INITIALS: a mark that the party in partyId draws when signing. sajn seals the mark into the PDF at this position. The party must have the SIGNER role.
  • INPUT with inputType TEXT, DATE, CHECKBOX, or SELECT: a value that the party in partyId fills in before signing. Add options for SELECT and "multiline": true for long text. If required is true, the party can’t sign until it’s filled in. Without a partyId, you fill the box in yourself.
  • STATIC: fixed text that you stamp on the page. content is HTML, and style takes fontSize (6 to 72), color (hex), bold, italic, and align (LEFT, CENTER, or RIGHT).
Every enum value in a box is uppercase; a lowercase value, such as 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 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:
Replace the following:
  • DOCUMENT_ID: the ID of the draft document.
  • STORAGE_KEY: the key from the file upload.
  • PARTY_ID: the id of the signing party.
The response has the created PDF block in 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 PATCH request to /api/v1/documents/DOCUMENT_ID/content/CONTENT_ID/placed-fields:
Replace CONTENT_ID with the PDF block’s id. The request works as follows:
  • A box in upsert with an existing id replaces that box and keeps its drawing 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 issues lists every problem.
The response is the PDF block with its full 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 an INPUT 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 in issues, with its path:
  • 400 VALIDATION_FAILED: a box is invalid, uses a lowercase enum value such as signature, or uses a 2026-09 name such as signerId instead of partyId. A box in 2026-09 coordinates, with page counted from 0 and rect in points, usually fails the fit check: add 1 to page, and set unit to POINTS and origin to BOTTOM_LEFT.
  • 409 INVALID_STATE: the document isn’t a DRAFT, or another edit changed the block while the request ran. In the second case, send the request again.
For the error shape and every code, see Errors.

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.