Named Regions a Page Marks for Filling

Mark rectangles on a page by name, where an address, a logo or another page goes, so that a later request fills each one by its name.

Summary

A form is laid out once: here the customer's address, there the logo, down there the order number. Each of those spaces gets a name. Nothing of them is drawn: the names travel inside the PDF. Later, whoever places that page in a document sends only the words and the pictures, each under its name, and each lands in its space, even when the page is shrunk or moved.

Technically

Written at the top level of a request, under "page_regions"

page_regions writes, page by page, a list of named rectangles under the page's /PieceInfo, with the moment the list was last changed. Each region says what fills it, words, a picture or a page of another PDF, where it sits, how its words are set or how a picture is fitted, and a sample it shows while it is left unfilled. A pdf_page item placing that page fills the regions by their names through its fill, wherever the page lands and at whatever size.

Request Schema

  • page_regions — array, optional, empty by default.
  • page_regions[].page — integer ≥ 1, required. The page the regions are on.
  • page_regions[].modified — string, required. When the list was last changed, an ISO 8601 date and time.
  • page_regions[].regions — array, required. The regions, each under a name no other region of the page takes.
  • regions[].name — string, required. The name a fill gives.
  • regions[].kind — text, image or page, required. What fills it: words, a picture or a drawing, a page of another PDF.
  • regions[].rect — object, required. Where it sits on the page: llx, lly, urx, ury, in points.
  • regions[].font, font_size, color and align — optional. How the words of a region of text are set: the name of a standard font or of a font the filling request names, the size in points, a device colour, and left, right, center or justify.
  • regions[].next — string, optional. The region of text the words that do not fit this one run on into.
  • regions[].fit and anchor — optional. How a picture or a page is sized to the region, and where it sits in it.
  • regions[].sample — string, optional. What the region shows while it is left unfilled: its text, or the name of the file meant to fill it.
  • regions[].custom — array, optional, empty by default. Named values the region carries for the program that fills it, each a name and a value written as a document part's data writes them. Nothing of them is drawn.

Refused, 400: two regions of one page under one name, an empty name, a rectangle without width or height, words sent on to a region the page does not mark, and a moment that is not a date and time.

A Whole Request That Creates a PDF

{
  "page_regions": [
    {
      "page": 1,
      "modified": "2026-10-07T09:00:00Z",
      "regions": [
        {
          "name": "recipient",
          "kind": "text",
          "rect": { "llx": 72, "lly": 600, "urx": 300, "ury": 680 },
          "font": "Helvetica",
          "font_size": 10,
          "sample": "Recipient's name",
          "custom": [{ "name": "column", "value": { "text": "customer_address" } }]
        },
        {
          "name": "logo",
          "kind": "image",
          "rect": { "llx": 400, "lly": 700, "urx": 520, "ury": 770 },
          "fit": "contain",
          "anchor": "top_right",
          "sample": "logo.png"
        }
      ]
    }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 740, "urx": 380, "ury": 770 },
      "content": ["Delivery label"],
      "font": "sans",
      "font_size": 14
    }
  ]
}

The line that sends it, in three languages

The sheet, and what is laid under it

The Size of the Pages A Size of Its Own for Certain Pages The Unit a Page Is Measured In Where a Page's Sheet Sits in the Drawing The Areas a Page States The Shapes a Page Lays over What It Draws Which Way up a Page Is Shown How a Page Arrives, and How Long It Stands A PDF You Send, as the Pages Themselves How Far a Supplied PDF Is Allowed to Unpack The Template under the Pages A Watermark Laid across a Run of Pages

Where to Go Next

Every JSON key of a request, in one page The other forty-one settings of a request

See the Prices See the Examples