---
title: "Flatten PDF forms server-side | Nutrient"
canonical_url: "https://www.nutrient.io/guides/document-engine/forms/flatten/"
md_url: "https://www.nutrient.io/guides/document-engine/forms/flatten.md"
last_updated: "2026-05-20T19:49:34.767Z"
description: "Flattening a PDF form is a process that converts interactive form fields into static content, making them part of the PDF document itself."
---

# Flatten PDF forms

Flattening a PDF form is a process that converts interactive form fields into static content, making them part of the PDF document itself. This means that once a PDF form is flattened, the information filled in the form fields cannot be edited or modified.

Flattening is used to preserve a document’s content and prevent any further changes, ensuring the information remains as it was when the form was flattened. This is particularly useful in situations where the completed form needs to be shared, archived, or submitted for official purposes and it’s important that the data remains unchanged.

Since form fields in a PDF document are a type of annotation called a “widget annotation,” the process of flattening a form is similar to that of [flattening annotations](https://www.nutrient.io/guides/document-engine/annotations/flatten.md).

## How to flatten PDF forms

- 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

- [PDF form server](/guides/document-engine/forms.md)
- [Extract form data](/guides/document-engine/forms/extract-form-data.md)
- [Fill PDF form fields](/guides/document-engine/forms/fill-form-fields.md)