---
title: "Flatten PDF annotations server-side"
canonical_url: "https://www.nutrient.io/guides/document-engine/annotations/flatten/"
md_url: "https://www.nutrient.io/guides/document-engine/annotations/flatten.md"
last_updated: "2026-06-09T10:25:14.392Z"
description: "Learn how to flatten PDF annotations using our Document Engine API for uneditable, secure PDF documents."
---

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

- Ensure [Document Engine is up and running](https://www.nutrient.io/sdk/document-engine/getting-started.md).

- Send a [multipart POST request](https://www.baeldung.com/postman-form-data-raw-x-www-form-urlencoded) with [instructions](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) to Document Engine’s `/api/build` endpoint.

For more information, refer to the [API reference](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Build-API) 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](https://www.nutrient.io/blog/a-brief-tour-of-multipart-requests/) blog post.









To flatten a PDF document, apply the [`flatten` action](https://www.nutrient.io/api/reference/document-engine/upstream/#model/BuildInstructions) to the PDF part in the [`/api/build` endpoint](https://www.nutrient.io/api/reference/document-engine/upstream/#tag/Document-Editing/operation/build-document)’s instructions. This request merges the `document1` and `document2` files before flattening the annotations in the final output PDF.

### SHELL

```shell

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

```

### HTTP

```http

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](https://www.nutrient.io/api/reference/document-engine/upstream/#model/BuildInstructions) 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.

### SHELL

```shell

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

```

### HTTP

```http

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

```
---

## Related pages

- [Annotate on images](/guides/document-engine/annotations/annotate-on-images.md)
- [Create](/guides/document-engine/annotations/create.md)
- [Architecture diagram](/guides/document-engine/annotations/architecture-diagram.md)
- [PDF annotation server](/guides/document-engine/annotations.md)
- [Edit](/guides/document-engine/annotations/edit.md)
- [Remove](/guides/document-engine/annotations/remove.md)