SDK

Low-Code

Workflow

DWS API

How to flatten PDF annotations effectively

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