PDF annotation flattening

Flattening is the process of embedding annotations in a PDF so that they can no longer be edited or removed. This leaves the visual representation of the annotations intact, but the annotations themselves are removed from the document.

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.

To flatten a PDF document, apply the flatten action(opens in a new tab) to the PDF part in the /api/build endpoint(opens in a new tab)’s instructions. This request merges the document1 and document2 files before flattening the annotations in the final output PDF.

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document1=@/path/to/example-document1.pdf \
  -F document2=@/path/to/example-document2.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document1"
    },
    {
      "file": "document2"
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}' \
  -o result.pdf

Flattening Specific Pages of a Document

Flattening is applied to all parts(opens in a new tab) when it’s specified in the outermost actions field. To flatten only a section of a document, split the document into multiple parts and flatten each part separately.

A part can be restricted to certain pages of a document. This way, you can flatten annotations only on the specified pages. The request below will flatten the first two pages of a four-page document with indexes from zero to four.

Terminal window
curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 1
      },
      "actions": [
        {
          "type": "flatten"
        }
      ]
    },
    {
      "file": "document",
      "pages": {
        "start": 2,
        "end": 3
      }
    }
  ]
}' \
  -o result.pdf