Import and export annotations with Instant JSON

Importing and exporting annotations enables you to persist user interactions — such as highlights, comments, or drawings — and reload them later. This is especially useful when working with custom-rendered annotations, where you control how annotations appear in the viewer. Exporting annotations in a portable format such as Instant JSON makes it possible to store, share, or sync them across users, devices, or sessions without needing to save the entire PDF file.

Annotation serialization

Serialization converts an annotation’s properties — such as type, position, color, and custom metadata — into a text-based format called Instant JSON. Think of it as capturing a complete snapshot of the annotation’s state that can be saved or transmitted.

Annotation deserialization

Deserialization is the reverse process. It takes saved Instant JSON data and uses it to recreate the annotation inside the viewer. This ensures annotations maintain their appearance and behavior, even across sessions or platforms.

How to serialize and deserialize annotations

You can export (serialize) a single annotation to Instant JSON by passing the annotation’s immutable record to the PSPDFKit.Annotations.toSerializableObject() method of our public API. This method converts the given annotation into a JSON object that captures all supported properties:

// Create an annotation and convert a rectangle annotation to Instant JSON.
const annotation = new PSPDFKit.Annotation.RectangleAnnotation({
  pageIndex: 0,
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 100,
    top: 150,
    width: 200,
    height: 75
  })
});
const annotationJSON = PSPDFKit.Annotations.toSerializableObject(
  annotation
);

// Annotation Instant JSON.
{
  v: 1,
  pageIndex: 0,
  bbox: [100, 150, 200, 75],
  opacity: 1,
  createdAt: "1970-01-01T00:00:00.000Z",
  updatedAt: "1970-01-01T00:00:00.000Z",
  isCommentThreadRoot: false,
  strokeWidth: 5,
  strokeColor: "#2293fb",
  type: "pspdfkit/shape/rectangle",
};

To import (deserialize) the annotation later, use the counterpart, PSPDFKit.Annotations.fromSerializableObject(). This method takes the exported JSON and reconstructs the annotation in the viewer:

const annotation = PSPDFKit.Annotations.fromSerializableObject(
  annotationJSON
);

Refer to the Instant JSON guide for details on format structure and supported properties.

Importing annotations in Instant JSON

You can import annotations in Instant JSON format in both operational modes of Nutrient Web SDK:

• When using Web SDK only (client-side processing)

• When using Web SDK with Document Engine (server-side processing)

This guide covers Instant JSON importing and exporting when using Web SDK. For Web SDK with Document Engine, refer to the importing and exporting with Document Engine guide.

Importing annotations in Instant JSON with document editing

If document editing is included in your license, you can use the applyInstantJson document operation to import Instant JSON through instance.applyOperations(), as demonstrated in the code snippet below:

instance.applyOperations([
  {
    type: "applyInstantJson",
    instantJson: {
      annotations: [
        {
          bbox: [100, 150, 200, 75],
          blendMode: "normal",
          createdAt: "1970-01-01T00:00:00Z",
          id: "01F73GJ4RPENTCMFSCJ5CSFT5G",
          name: "01F73GJ4RPENTCMFSCJ5CSFT5G",
          opacity: 1,
          pageIndex: 0,
          strokeColor: "#2293FB",
          strokeWidth: 5,
          type: "pspdfkit/shape/rectangle",
          updatedAt: "1970-01-01T00:00:00Z",
          v: 1
        }
      ],
      format: "https://pspdfkit.com/instant-json/v1"
    }
  }
]);

Importing annotations in Instant JSON without document editing

If document editing is not included in your license, you can use the PSPDFKit.Configuration#instantJSON setting, as demonstrated in the code snippet below:

PSPDFKit.load({
  ...otherOptions,
  instantJSON: {
    annotations: [
      {
        bbox: [100, 150, 200, 75],
        blendMode: "normal",
        createdAt: "1970-01-01T00:00:00Z",
        id: "01F73GJ4RPENTCMFSCJ5CSFT5G",
        name: "01F73GJ4RPENTCMFSCJ5CSFT5G",
        opacity: 1,
        pageIndex: 0,
        strokeColor: "#2293FB",
        strokeWidth: 5,
        type: "pspdfkit/shape/rectangle",
        updatedAt: "1970-01-01T00:00:00Z",
        v: 1
      }
    ],
    format: "https://pspdfkit.com/instant-json/v1"
  }
});

Exporting annotations in Instant JSON

To export an annotation in Instant JSON for storage or further processing, use the instance.exportInstantJSON() API method. Annotations that have been saved can be exported in the Instant JSON format:

instance.exportInstantJSON();