How to Flatten Annotations in PDF Files with cURL, Tutorial

Share this page

This step-by-step tutorial explains how to flatten annotations in PDF files from a shell script with the Flatten Annotations API Tool. After reviewing the command and its response handling, you'll be ready to test the Flatten Annotations in PDF request with representative files.

Why Flatten Annotations in PDF Files with cURL?

Review comments, highlights, stamps, and drawing markup may need to remain visible in a final PDF without staying independently editable. Flattening incorporates each annotation appearance into the ordinary page content.

A legal review workflow can use this after comments are resolved but must still be preserved in the delivered record. The resulting PDF shows the markup consistently in viewers and print workflows that might otherwise hide or handle annotations differently.

The operation creates a separate flattened PDF. Retain the annotated source when reviewers may need comment metadata, editing controls, or the original audit trail later.

cURL Code Example

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

curl -X POST "$API_URL/flattened-annotations-pdf" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -F "file=@/path/to/file" \
  -F "output=example_out"

Source for Flatten Annotations in PDF: View the cURL sample on GitHub.

Breaking Down the Code

Choose the pdfRest service region

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

The annotation-flattening command starts with the US pdfRest hostname and keeps the EU service available as a documented alternative. Use the same host for the reviewed input and the flattened result throughout the workflow.

Build the authenticated multipart request

curl -X POST "$API_URL/flattened-annotations-pdf" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \

cURL submits the reviewed document directly to /flattened-annotations-pdf. The headers distinguish the expected JSON response, multipart upload body, and API credential before any file data is sent.

Upload the input file data

-F "file=@/path/to/file" \

The Flatten Annotations in PDF request reads the local source from the path after @ and sends its bytes in the multipart file field. For Flatten Annotations in PDF, cURL treats the path as an upload rather than ordinary form text.

Set the operation-specific fields

-F "output=example_out"

The output value names the flattened copy created from the reviewed PDF. Annotation appearances already stored in the document determine what becomes fixed page content.

Read the generated resource response

curl -X POST "$API_URL/flattened-annotations-pdf" \

pdfRest returns a new PDF resource after incorporating the annotation appearances. Keep its output ID or download URL for final distribution while retaining the annotated source separately when review history must remain editable.

Beyond the Tutorial

You now have a direct cURL request for converting visible annotations into fixed page content before distribution, printing, or another PDF operation.

Inspect representative annotation types before final delivery, including stamps, free text, highlights, and drawings. Flattening is intentionally irreversible in the generated output, so preserve the editable reviewed version when history matters.

Continue exploring the Flatten Annotations in PDF workflow in API Lab. For the complete Flatten Annotations in PDF request contract, accepted values, defaults, and limitations, consult the Flatten Annotations API Tool documentation.

Note: The Flatten Annotations in PDF example above uploads a file with multipart form data. For source content already stored in pdfRest, the Flatten Annotations in PDF JSON payload example shows the resource-ID request shape.