Changing PDF Page Numbers or Labels

Document Engine lets you set labels for pages of a document by sending a multipart request to the /build endpoint(opens in a new tab) and attaching both the input file(s) and the instructions JSON(opens in a new tab). This is done using the instructions.output.labels field. This can be useful when, for example, you want PDF readers to show Roman numerals for page labels instead of Arabic numerals.

Learn more about the instructions schema in our API Reference(opens in a new tab).

This guide presents examples of setting page labels for PDFs.

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Setting the Page Label of a File on Disk

This example merges two documents together and then sets the label of the first page (index 0) in the merged output to "i", the label of the pages with indexes 1, 2, and 3 to "intro", and the label of the pages with indexes 4, 5, 6, and 7 to "final".

As shown in the example, there are multiple ways to specify the index or range of indexes you want to apply a specific label to. You can learn more by checking out our API Reference(opens in a new tab).

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document1=@/path/to/example-document1.pdf \
  -F document1=@/path/to/example-document2.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document1"
    },
    {
      "file": "document2"
    }
  ],
  "output": {
    "type": "pdf",
    "labels": [
      {
        "pageIndex": 0,
        "label": "i"
      },
      {
        "pages": {
          "start": 1,
          "end": 3
        },
        "label": "intro"
      },
      {
        "pages": [
          4,
          5,
          6,
          7
        ],
        "label": "final"
      }
    ]
  }
}' \
  -o result.pdf

Setting the Page Label of a File from a URL

You can also specify the file to set a page label on using a URL. This example provides a URL to the PDF and then sets the label of the first page to "i".

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      }
    }
  ],
  "output": {
    "type": "pdf",
    "labels": [
      {
        "pageIndex": 0,
        "label": "i"
      }
    ]
  }
}' \
  -o result.pdf