---
title: "Import XFDF annotations API"
canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/import-xfdf-annotations-api/"
md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/import-xfdf-annotations-api.md"
last_updated: "2026-07-06T00:00:00.000Z"
description: "Import XFDF annotation data into PDF files using Nutrient DWS Processor API. Apply annotation exports from external PDF tools and optionally flatten the imported annotations."
---

# Import XFDF annotations API

Use the import XFDF annotations API to apply XFDF annotation data to a PDF. XML Forms Data Format (XFDF) is a common Extensible Markup Language (XML)-based format for exchanging PDF annotations between tools.

The [`/build` endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) handles XFDF import. Add the source PDF as a `parts` item, and add an `applyXfdf` action that references the XFDF file.

For signup, pricing, and task-level examples, refer to the [XFDF import API task page](https://www.nutrient.io/api/xfdf-import-api/).

## Import XFDF annotations

The following example imports annotations from `annotations.xfdf` into `annotations.pdf` and writes the output to `result.pdf`:

### Shell

### Shell (Windows)

### Java

### C#

### JavaScript

### Python

### PHP

### HTTP

## Import XFDF from URLs

For remotely hosted source files, send a JSON request and pass URLs for both the PDF and the XFDF file. Use this instructions object:

```json

{
  "parts": [
    {
      "file": {
        "url": "https://example.com/document.pdf"
      }
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": {
        "url": "https://example.com/annotations.xfdf"
      }
    }
  ]
}

```

### Shell

Run this request to import XFDF from URLs:

```bash

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "file": {
          "url": "https://example.com/document.pdf"
        }
      }
    ],
    "actions": [
      {
        "type": "applyXfdf",
        "file": {
          "url": "https://example.com/annotations.xfdf"
        }
      }
    ]
  }' \
  -o result.pdf

```

## Control rich text conversion

By default, `richTextEnabled` is `true`. This converts plain text annotations to rich text annotations when importing XFDF. Set it to `false` if you want all imported text annotations to remain plain text annotations.

Use this instructions object to disable rich text conversion:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf",
      "richTextEnabled": false
    }
  ]
}

```

## Ignore page rotation

Use `ignorePageRotation` when you need to ignore page rotation while applying XFDF data. This can help when XFDF coordinates were produced by a system that doesn’t account for page rotation the same way.

Use this instructions object to ignore page rotation:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf",
      "ignorePageRotation": true
    }
  ]
}

```

## Import and flatten XFDF annotations

If the imported annotations should no longer be editable, add a `flatten` action after `applyXfdf`. Actions run in the order specified in the `actions` array.

Use this instructions object to import and flatten XFDF annotations:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf"
    },
    {
      "type": "flatten"
    }
  ]
}

```

Flattening turns annotations into regular page content. Use it only when the output no longer needs editable annotations.

## Import XFDF into selected pages

The `applyXfdf` action applies to the assembled PDF in the request. If you first extract pages with `parts[].pages`, Nutrient DWS Processor API applies the XFDF to that extracted output.

Use this instructions object to import XFDF into selected pages:

```json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 2
      }
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf"
    }
  ]
}

```

Make sure the page indexes and annotation coordinates in the XFDF match the PDF that the action applies to.

## Import XFDF into password-protected PDFs

If the source PDF is password-protected, include the password on the part. Use this instructions object:

```json

{
  "parts": [
    {
      "file": "protected_document",
      "password": "document-password"
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf"
    }
  ]
}

```

Nutrient DWS Processor API uses the password only to open the source document for processing. To set a password on the output PDF, configure `output.user_password`, `output.owner_password`, and `output.user_permissions`.

## Combine XFDF import with other actions

The `/build` endpoint can import XFDF annotations and then apply additional actions. For example, you can import annotations, watermark the document, and then flatten the result.

Use this instructions object to combine XFDF import with other actions:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyXfdf",
      "file": "annotations.xfdf"
    },
    {
      "type": "watermark",
      "text": "REVIEWED",
      "width": "50%",
      "height": "20%",
      "opacity": 0.3,
      "rotation": 45
    },
    {
      "type": "flatten"
    }
  ]
}

```

For workflows that include cryptographic signing, import and optionally flatten annotations before signing the final PDF.

## Reference

An XFDF import request uses the Build API `actions` array with an `applyXfdf` action:

```typescript

type ApplyXfdfAction = {
  type: "applyXfdf",

  // Multipart field name, or a remote URL object pointing to an XFDF file.
  file: string | { url: string },

  // If `true`, ignores page rotation when applying XFDF data.
  ignorePageRotation?: boolean,

  // If `true`, plain text annotations are converted to rich text annotations.
  // If `false`, all text annotations are plain text annotations.
  richTextEnabled?: boolean,
};

type FilePart = {
  // Multipart field name, or a remote URL object.
  file: string | { url: string },

  // Optional password for encrypted input PDFs.
  password?: string,

  // Optional page range to use before XFDF import.
  pages?: {
    start?: number,
    end?: number,
  },
};

type BuildInstructions = {
  parts: FilePart[],
  actions: ApplyXfdfAction[],
  output?: {
    type?: "pdf",
  },
};

```

## Related API reference operations

- Refer to the [build document endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) API reference to import XFDF annotations and combine import with flattening, watermarking, security, or other document actions.

## Related guides

- Refer to the [import Instant JSON API](https://www.nutrient.io/guides/dws-processor/tools-and-api/import-instant-json-api.md) guide.

- Refer to the [PDF flatten API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-flatten-api.md) guide.

- Refer to the [PDF form filling API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-form-filling-api.md) guide.

- Refer to the [PDF watermark API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-watermark-api.md) guide.

- Refer to the [PDF digital signature API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md) guide.

- Refer to the [tools and APIs](https://www.nutrient.io/guides/dws-processor/tools-and-api.md) guide.
---

## Related pages

- [Image-to-PDF API](/guides/dws-processor/tools-and-api/image-to-pdf-api.md)
- [Analyze Build API](/guides/dws-processor/tools-and-api/analyze-build-api.md)
- [Tools and APIs](/guides/dws-processor/tools-and-api.md)
- [Document-to-image API](/guides/dws-processor/tools-and-api/document-to-image-api.md)
- [Import Instant JSON API](/guides/dws-processor/tools-and-api/import-instant-json-api.md)
- [DOCX templating API](/guides/dws-processor/tools-and-api/docx-templating-api.md)
- [Office-to-PDF API](/guides/dws-processor/tools-and-api/office-to-pdf-api.md)
- [Markdown-to-PDF API](/guides/dws-processor/tools-and-api/markdown-to-pdf-api.md)
- [PDF digital signature API](/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md)
- [PDF merge API](/guides/dws-processor/tools-and-api/pdf-merge-api.md)
- [PDF form filling API](/guides/dws-processor/tools-and-api/pdf-form-filling-api.md)
- [PDF flatten API](/guides/dws-processor/tools-and-api/pdf-flatten-api.md)
- [PDF OCR API](/guides/dws-processor/tools-and-api/pdf-ocr-api.md)
- [PDF generator API](/guides/dws-processor/tools-and-api/pdf-generator-api.md)
- [PDF linearization API](/guides/dws-processor/tools-and-api/pdf-linearization-api.md)
- [PDF rotate API](/guides/dws-processor/tools-and-api/pdf-rotate-api.md)
- [PDF optimization API](/guides/dws-processor/tools-and-api/pdf-optimization-api.md)
- [PDF security API](/guides/dws-processor/tools-and-api/pdf-security-api.md)
- [PDF page manipulation API](/guides/dws-processor/tools-and-api/pdf-page-manipulation-api.md)
- [PDF split API](/guides/dws-processor/tools-and-api/pdf-split-api.md)
- [PDF-to-HTML API](/guides/dws-processor/tools-and-api/pdf-to-html-api.md)
- [PDF-to-image API](/guides/dws-processor/tools-and-api/pdf-to-image-api.md)
- [PDF-to-Markdown API](/guides/dws-processor/tools-and-api/pdf-to-markdown-api.md)
- [PDF-to-Office API](/guides/dws-processor/tools-and-api/pdf-to-office-api.md)
- [PDF-to-PDF/A API](/guides/dws-processor/tools-and-api/pdf-to-pdfa-api.md)
- [PDF watermark API](/guides/dws-processor/tools-and-api/pdf-watermark-api.md)
- [Redaction API](/guides/dws-processor/tools-and-api/redaction-api.md)
- [PDF/UA auto-tagging API](/guides/dws-processor/tools-and-api/pdfua-api.md)