Flatten PDF Annotations

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.

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

You’ll be sending multipart POST requests with instructions to Document Engine’s /api/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 /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

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

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
POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

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

<PDF data>
--customboundary
Content-Disposition: form-data; name="document2"; 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"
    }
  ],
  "actions": [
    {
      "type": "flatten"
    }
  ]
}
--customboundary--

Flattening Specific Pages of a Document

Flattening is applied to all parts 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.

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
POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

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

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

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 1
      },
      "actions": [
        {
          "type": "flatten"
        }
      ]
    },
    {
      "file": "document",
      "pages": {
        "start": 2,
        "end": 3
      }
    }
  ]
}
--customboundary--