---
title: "Convert between Instant JSON and XFDF | Nutrient .NET SDK"
canonical_url: "https://www.nutrient.io/guides/dotnet/annotations/convert-between-instant-json-and-xfdf/"
md_url: "https://www.nutrient.io/guides/dotnet/annotations/convert-between-instant-json-and-xfdf.md"
last_updated: "2026-06-26T00:00:00.000Z"
description: "Convert annotation and form data between Instant JSON and XFDF using Nutrient .NET SDK."
---

# Convert between Instant JSON and XFDF

XFDF is Adobe's XML-based format for sharing PDF form data and annotations. Many legacy review workflows ship XFDF files alongside PDFs, and teams that migrate to Instant JSON often need a bridge between the two formats. Nutrient.NET SDK can import and export both formats, so an XFDF payload from an older system can become an Instant JSON file for Web SDK, Document Engine, or another GdPicture-based service.

This guide shows how to move data between the two formats.

- Apply an Instant JSON file to a PDF and export the result as XFDF

- Reimport the XFDF file and export it back as Instant JSON

- Control whether form fields, annotations, or both are included in each direction

## Prepare the project

Start by registering the SDK license before you process documents. For setup details, refer to the [getting started with.NET SDK](https://www.nutrient.io/sdk/dotnet/getting-started.md) guide.

```csharp

using GdPicture14;

LicenseManager licence = new LicenseManager();
licence.RegisterKEY(""); // Set your license key

```

## Import Instant JSON and export XFDF

Start with a PDF that already contains form fields. The first step is to import an Instant JSON file with form field values, then export the resulting state as XFDF. The XFDF export uses two Boolean values to control which object families it includes — set both to `true` to capture the full annotation and form field surface:

```csharp

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.LoadFromFile(@"test_form_fields.pdf");

    GdPictureStatus importStatus = pdf.ImportInstantJSONDataFromFile(@"test_form_fields_instant.json");
    if (importStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Instant JSON import failed: {importStatus}");
        Environment.Exit(1);
    }

    GdPictureStatus exportStatus = pdf.ExportXFDFDataToFile(@"output.xfdf", ExportFormFields: true, ExportAnnotations: true);
    if (exportStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"XFDF export failed: {exportStatus}");
        Environment.Exit(1);
    }
}

```

The XFDF payload is human-readable XML, so you can inspect it in a text editor before you send it to a downstream consumer.

## Import XFDF back into a PDF

Next, open the same source PDF in a new `GdPicturePDF` instance and import the XFDF you just produced. `ImportXFDFDataFromFile` mirrors the export call, and two Boolean values enable you to scope the import to form fields, annotations, or both:

```csharp

using (GdPicturePDF pdf = new GdPicturePDF())
{
    pdf.LoadFromFile(@"test_form_fields.pdf");

    GdPictureStatus importStatus = pdf.ImportXFDFDataFromFile(@"output.xfdf", ImportFormFields: true, ImportAnnotations: true);
    if (importStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"XFDF import failed: {importStatus}");
        Environment.Exit(1);
    }

```

## Export the imported XFDF as Instant JSON

After you import the XFDF, export the document state as Instant JSON. Pass `fullState: true` so the export captures every annotation and form field, not just the diff since load:

```csharp

    using FileStream stream = new FileStream(@"output.json", FileMode.Create, FileAccess.Write);
    GdPictureStatus exportStatus = pdf.ExportInstantJSONDataToStream(stream, fullState: true);
    if (exportStatus!= GdPictureStatus.OK)
    {
        Console.Error.WriteLine($"Instant JSON export failed: {exportStatus}");
        Environment.Exit(1);
    }
}

```

## Scope the conversion

Use the `ImportFormFields` / `ExportFormFields` and `ImportAnnotations` / `ExportAnnotations` flags when only one object family should round-trip. For example, export only form values back to a server that doesn't need review markup, or import annotations from a markup tool without overwriting form data filled in by an end user.

## Error handling

XFDF and Instant JSON imports validate input before they apply changes. Common failure cases include:

- `GdPictureStatus.PdfDocumentMustBeUnencrypted` — both formats refuse to operate on encrypted PDFs

- `GdPictureStatus.FileNotFound` — the path is wrong, or the source file is missing

- `GdPictureStatus.GenericError` — malformed XFDF or Instant JSON

For status-handling patterns, refer to the [handling errors with.NET SDK](https://www.nutrient.io/guides/dotnet/best-practices.md#error-handling) guide.

## Conclusion

This guide bridges Instant JSON and XFDF in both directions. It gives you a migration path from legacy XFDF-based workflows to Instant JSON while still supporting downstream consumers that expect XFDF.
---

## Related pages

- [Configure Instant JSON appearance and tracking](/guides/dotnet/annotations/configure-instant-json-appearance-and-tracking.md)
- [Attach a file to an annotation in C#](/guides/dotnet/annotations/attach-a-file.md)
- [Annotate on images in C# .NET](/guides/dotnet/annotations/annotate-on-images.md)
- [Attach an image to an annotation in C#](/guides/dotnet/annotations/attach-an-image.md)
- [Convert between Instant JSON and XMP](/guides/dotnet/annotations/convert-between-instant-json-and-xmp.md)
- [Create an annotation in a PDF using C#](/guides/dotnet/annotations/create.md)
- [Custom annotations](/guides/dotnet/annotations/custom-annotations.md)
- [Edit PDF annotations in C#](/guides/dotnet/annotations/edit.md)
- [Export Instant JSON from a PDF](/guides/dotnet/annotations/export-instant-json-from-pdf.md)
- [Export annotation data from PDFs in C# .NET](/guides/dotnet/annotations/export-pdf.md)
- [Get PDF annotation properties in C# .NET](/guides/dotnet/annotations/get-properties.md)
- [Export XMP annotation data in C# .NET](/guides/dotnet/annotations/export-xmp.md)
- [Import Instant JSON into a PDF](/guides/dotnet/annotations/import-instant-json-into-pdf.md)
- [Flatten PDF annotations in C# .NET](/guides/dotnet/annotations/flatten.md)
- [Import XFDF annotation data to PDFs in C# .NET](/guides/dotnet/annotations/import-xfdf.md)
- [Import XMP annotation data to PDF or image in C#](/guides/dotnet/annotations/import-xmp.md)
- [Instant JSON appearance theme comparison](/guides/dotnet/annotations/instant-json-appearance-theme-comparison.md)
- [PDF annotations in C#.NET](/guides/dotnet/annotations.md)
- [Remove PDF annotations in C# .NET](/guides/dotnet/annotations/remove.md)
- [Add PDF actions using C# in form fields](/guides/dotnet/annotations/pdf-actions-support.md)
- [Stamp a PDF document in C# .NET](/guides/dotnet/annotations/stamp-a-document.md)
- [XMP annotations in C# .NET](/guides/dotnet/annotations/xmp-annotations.md)