--- title: "Import and export PDF annotations in XFDF file | Nutrient Web SDK" canonical_url: "https://www.nutrient.io/guides/web/importing-exporting/xfdf-support/" md_url: "https://www.nutrient.io/guides/web/importing-exporting/xfdf-support.md" last_updated: "2026-06-09T10:32:42.876Z" description: "Learn to import and export PDF annotations using XFDF with Nutrient Web SDK for interoperability with Adobe Acrobat, including selective-export and data-scoping guidance alongside Instant JSON and server-backed sync." --- # Importing and exporting annotations in XFDF XML Forms Data Format (XFDF) is an XML-based standard from Adobe [XFDF (ISO 19444-1:2016)](https://www.iso.org/obp/ui/#iso:std:iso:19444:-1:ed-1:v1:en) for encoding annotations and form field values. It’s compatible with Adobe Acrobat and several other third-party frameworks. Recommendation summary: - **Instant JSON** — Default format for internal persistence and syncing annotation data. - **XFDF** — Best when you need interoperability with external PDF tools. - **Server-backed (Document Engine with Instant synchronization)** — Best for collaborative, multiuser workflows across sessions and devices. If you’re deciding between these approaches, start with [how to choose Instant JSON vs. XFDF vs. server-backed sync](https://www.nutrient.io/guides/web/annotations/import-and-export/choose-persistence-strategy.md). If you need team synchronization and collaborative review, refer to the [importing and exporting with Document Engine](https://www.nutrient.io/guides/web/annotations/import-and-export/server-backed.md) and [Instant synchronization](https://www.nutrient.io/guides/web/instant-synchronization.md) guides. If you need to export only a selected subset of annotations for sharing, refer to the [export only selected annotations](https://www.nutrient.io/guides/web/annotations/import-and-export/export-only-selected-annotations.md) guide. XFDF has various limitations. In most cases, using the [Instant JSON](https://www.nutrient.io/guides/web/importing-exporting/instant-json.md) format will result in a smaller file and better synchronization. ## Importing XFDF You can import annotations in XFDF format in both [operational modes](https://www.nutrient.io/guides/web/about/operational-modes.md) of Nutrient Web SDK: - When using Web SDK with Document Engine (server-side processing) - When using Web SDK only (client-side processing) ### Importing XFDF with Document Engine Nutrient Web SDK with Document Engine supports importing annotations from an XFDF file when uploading a document using the `/api/documents` endpoint. Send a `multipart/form-data` `POST` request, including the PDF and the XFDF file, to import the annotations in the given PDF file. This will replace all existing annotations in the uploaded PDF with the annotations from the uploaded XFDF file. If you want to add annotations to existing ones instead of replacing them, set `keep_current_annotations` to `true`: **Request** ```http POST /api/documents Content-Type: multipart/form-data; boundary=customboundary Authorization: Token token="" --customboundary Content-Disposition: form-data; name="file"; filename="Example Document.pdf" Content-Type: application/pdf --customboundary Content-Disposition: form-data; name="attachment"; filename="attachment.xfdf" Content-Type: application/vnd.adobe.xfdf --customboundary Content-Disposition: form-data; name="keep_current_annotations" true --customboundary-- ``` For an in-depth example, refer to the [importing and exporting annotations with Document Engine](https://www.nutrient.io/guides/web/annotations/import-and-export/server-backed.md) guide. ### Importing XFDF when only using Web SDK To import XFDF when using Nutrient Web SDK, use the [`Configuration#XFDF`](https://www.nutrient.io/api/web/interfaces/Configuration.html#xfdf) option. In addition to the [`Configuration#XFDF`](https://www.nutrient.io/api/web/interfaces/Configuration.html#xfdf) option, you can also set the [`Configuration#XFDFKeepCurrentAnnotations`](https://www.nutrient.io/api/web/interfaces/Configuration.html#xfdfkeepcurrentannotations) flag. This flag ensures that annotations already in the source PDF are kept and not replaced with those defined in the XFDF: ```js NutrientViewer.load({ document: "https://your-server.com/some/document.pdf", XFDF: `..` }); ``` ## Exporting XFDF You can export the document’s annotations in XFDF format in both [operational modes](https://www.nutrient.io/guides/web/about/operational-modes.md). When using Web SDK with Document Engine, export XFDF using the REST API or the client-side API. When only using Web SDK, export XFDF using the client-side API. ### Exporting XFDF using REST API When using Nutrient Web SDK with Document Engine, export the current annotations of a document as an XFDF file using a `GET` request to `/api/documents/:document_id/document.xfdf`. To get the current annotations of a document’s layer, send a `GET` request to `/api/documents/:document_id/layers/:layer_name/document.xfdf`: **Request** ```http GET /api/documents/:document_id/document.xfdf Authorization: Token token="" ``` ```bash $ curl "http://localhost:5000/api/documents/abc/document.xfdf" \ -H "Authorization: Token token=" ``` **Response** ```http HTTP/1.1 200 OK Content-Type: application/vnd.adobe.xfdf ``` ### Exporting XFDF using the client-side API In both [operational modes](https://www.nutrient.io/guides/web/about/operational-modes.md), you can export the XFDF file through the client-side API using the [`Instance#exportXFDF`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#exportxfdf) method: ```js instance.exportXFDF().then((xfdf) => { console.log(xfdf); // => ... }); ``` XFDF works seamlessly with the [annotation API](https://www.nutrient.io/guides/web/annotations/introduction-to-annotations.md). If you want to persist annotations whenever changes are made, we recommend using the [`annotations.didSave`](https://www.nutrient.io/api/web/types/Events.AnnotationsDidSaveEvent.html) event. This event will be triggered automatically and can be configured using [`Configuration#autoSaveMode`](https://www.nutrient.io/guides/web/annotations/annotation-saving-mechanism/). ### Saving annotations when using only Web SDK When using only Web SDK, saving annotations doesn’t send them to a backend server. Instead: - Annotations are stored in memory after a save operation. - To persist annotations, you must either: - Export them using [`Instance#exportXFDF`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#exportxfdf). - Write them directly into the PDF document using [`Instance#exportPDF`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#exportpdf). Unsaved annotations won’t be exported. This behavior mirrors how annotations are handled when using a server: ```js instance.addEventListener("annotations.didSave", async () => { const xfdf = await instance.exportXFDF(); await fetch("https://your-server.com/xfdf", { method: "post", headers: { "Content-Type": "application/vnd.adobe.xfdf" }, body: xfdf }); }); ``` ## Exporting annotations to XFDF using Adobe Acrobat To export annotations from Adobe Acrobat into XFDF format, follow the steps below. 1. Open the **Comments** tool from the sidebar. 2. Click the three dots menu and select **Export All To Data File**. 3. In the export dialog: - Set the file type to **Acrobat XFDF Files** at the bottom. - Select the directory where you want to save the XFDF file and enter a name for the file. - Click **Save**. After exporting, you’ll have a file with an `.xfdf` extension. ## Importing annotations from XFDF using Adobe Acrobat To import annotations from an XFDF file into Adobe Acrobat, follow the steps below. 1. Open the **Comments** tool from the sidebar. 2. Click the three dots menu and select **Import Data File**. 3. Choose the `.xfdf` file you want to import and click **Select**. After importing, Adobe Acrobat will place the annotations onto the document. ## Adobe Acrobat error conditions | Error description | Screenshot | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Damaged/missing document body | | | Damaged/missing description tag | | | Missing document flag | | --- ## Related pages - [How to choose Instant JSON vs. XFDF vs. server-backed sync](/guides/web/annotations/import-and-export/choose-persistence-strategy.md) - [Importing and exporting annotations in a database](/guides/web/annotations/import-and-export/database.md) - [Export only selected annotations](/guides/web/annotations/import-and-export/export-only-selected-annotations.md) - [Importing and exporting annotations with Document Engine](/guides/web/annotations/import-and-export/server-backed.md) - [Importing and exporting annotations with Instant JSON](/guides/web/importing-exporting/instant-json.md)