Changing PDF Page Numbers or Labels in Linux

PSPDFKit Processor has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Processor licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

PSPDFKit Processor lets you set labels for pages of a document by sending a multipart request to the /build endpoint and attaching both the input file(s) and the instructions JSON. 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.

This guide presents examples of setting page labels for PDFs.

Before you get started, make sure Processor is up and running.

You can download and use either of the following sample documents for the examples in this guide:

You’ll be sending multipart POST requests with instructions to Processor’s /build endpoint. To learn more about multipart requests, refer to our blog post on the topic, A Brief Tour of Multipart Requests.

Check out the API Reference to learn more about the /build endpoint and all the actions you can perform on PDFs with PSPDFKit Processor.

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.

curl -X POST http://localhost:5000/build \
  -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

POST /process HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary

--customboundary
Content-Disposition: form-data; name="document1"; filename="example-document1.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="document1"; filename="example-document2.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "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"
      }
    ]
  }
}
--customboundary--

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".

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

POST /process HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      }
    }
  ],
  "output": {
    "type": "pdf",
    "labels": [
      {
        "pageIndex": 0,
        "label": "i"
      }
    ]
  }
}
--customboundary--