--- title: "PDF annotations import/export on Android" canonical_url: "https://www.nutrient.io/guides/android/annotations/import-and-export/instant-json/" md_url: "https://www.nutrient.io/guides/android/annotations/import-and-export/instant-json.md" last_updated: "2026-06-09T10:25:14.332Z" description: "Learn how to import and export PDF annotations using Instant JSON on Android for smooth document handling and long-term storage." --- # Seamlessly import and export PDF annotations [Instant JSON](https://www.nutrient.io/guides/android/json.md) is our approach to bringing annotations into a modern format while keeping all important properties to make the [Instant JSON](https://www.nutrient.io/guides/android/json.md) spec work with PDF. It’s fully documented and supports long-term storage. [Instant JSON](https://www.nutrient.io/guides/android/json.md) stores a list of new or updated annotations. Annotations follow the [format for Instant JSON for annotations](https://www.nutrient.io/guides/web/json.md). When an annotation contains a `pdfObjectId`, it’s considered to be an update to one of the annotations of the original PDF. For newly created annotations, this key won’t be set. There are some limitations with [Instant JSON](https://www.nutrient.io/guides/android/json.md), in that not _all_ annotation types are currently supported, and only the properties that can be handled correctly across all of Nutrient’s supported platforms (iOS, Android, Web, Windows, and Document Engine) are serialized. For more information, check out the detailed [JSON format](https://www.nutrient.io/guides/web/json.md) guide. ## Exporting annotations To serialize an [`Annotation`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/index.html) and export it to its JSON representation, you can call [`annotation.toInstantJson()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/to-instant-json.html). For example: ### KOTLIN ```kotlin // Serializes a single annotation to a JSON string. val json: String = annotation.toInstantJson() ``` ### JAVA ```java // Serializes a single annotation to a JSON string. final String json = annotation.toInstantJson(); ``` The string will contain a human-readable JSON. Here’s an Instant JSON sample payload for an ink annotation: ```json { "v": 1, "type": "pspdfkit/ink", "bbox": [89, 98, 143, 207], "blendMode": "normal", "createdAt": "2018-07-03T13:53:03Z", "isDrawnNaturally": false, "lineWidth": 5, "lines": { "intensities": [ [0.5, 0.5, 0.5], [0.5, 0.5, 0.5] ], "points": [ [ [92, 101], [92, 202], [138, 303] ], [ [184, 101], [184, 202], [230, 303] ] ] }, "opacity": 1, "pageIndex": 0, "strokeColor": "#AA47BE", "updatedAt": "2018-07-03T13:53:03Z" } ``` ## Importing annotations To create an annotation from an existing Instant annotation JSON, use [`createAnnotationFromInstantJson()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/create-annotation-from-instant-json.html) from your document’s [`AnnotationProvider`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/index.html). For example: ### KOTLIN ```kotlin // Deserialize an Instant annotation JSON and create an annotation from it. val annotation: Annotation = document.getAnnotationProvider().createAnnotationFromInstantJson(json) ``` ### JAVA ```java // Deserialize an Instant annotation JSON and create an annotation from it. final Annotation annotation = document.getAnnotationProvider().createAnnotationFromInstantJson(json); ``` The created [`Annotation`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/index.html) will automatically be added to the [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/index.html) of the used [`AnnotationProvider`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/index.html) during deserialization. ## Instant JSON annotation attachment API The Instant JSON annotation attachment API enables you to represent an annotation’s binary attachments as data blobs. For example, a stamp annotation with an image has an attachment. ### Importing image annotations To import an image annotation, you need to perform a two-step operation: - Create the annotation from the instant JSON data using the [`createAnnotationFromInstantJson`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/create-annotation-from-instant-json.html) method. - Attach the binary instant JSON attachment using the [`attachBinaryInstantJsonAttachment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/attach-binary-instant-json-attachment.html) method. ### KOTLIN ```kotlin override fun onDocumentLoaded(document: PdfDocument) { super.onDocumentLoaded(document) val jsonData = "{"bbox": [170.78128051757812, 219.125, 249.99993896484375, 249.99993896484375], "createdAt": "2021-11-02T15:32:58Z", "creatorName": "simone", "imageAttachmentId": "566", "name": "bc8a9057-c000-4adb-b438-8731f42e5814", "opacity": 1, "pageIndex": 0, "rotation": 0, "type": "pspdfkit/image", "updatedAt": "2021-11-02T15:33:24Z", "v": 1}" val anotherStampAnnotation = document.annotationProvider.createAnnotationFromInstantJson(jsonData) val tempBinaryAttachmentJsonFile = File("image/stamp.jpeg") anotherStampAnnotation.attachBinaryInstantJsonAttachment(FileDataProvider(tempBinaryAttachmentJsonFile), "image/jpeg") ``` ### JAVA ```java override private void onDocumentLoaded(PdfDocument document){ super.onDocumentLoaded(document); String jsonData = "{"bbox": [170.78128051757812, 219.125, 249.99993896484375, 249.99993896484375], "createdAt": "2021-11-02T15:32:58Z", "creatorName": "simone", "imageAttachmentId": "566", "name": "bc8a9057-c000-4adb-b438-8731f42e5814", "opacity": 1, "pageIndex": 0, "rotation": 0, "type": "pspdfkit/image", "updatedAt": "2021-11-02T15:33:24Z", "v": 1}"; StampAnnotation anotherStampAnnotation = document.annotationProvider.createAnnotationFromInstantJson(jsonData); File tempBinaryAttachmentJsonFile = new File("image/stamp.jpeg"); anotherStampAnnotation.attachBinaryInstantJsonAttachment(new FileDataProvider(tempBinaryAttachmentJsonFile), "image/jpeg"); } ``` ### Exporting image annotations To export an image annotation: - Convert the annotation to Instant JSON annotation using the [`Annotation#toInstantJson()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/to-instant-json.html) method. - Fetch the binary Instant JSON attachment and write the binary into another file using the [`fetchBinaryInstantJsonAttachment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/fetch-binary-instant-json-attachment.html) method. At the end of the exporting process, you’ll end up with two files — one containing the JSON data, and another one containing the binary Instant JSON attachment. ### KOTLIN ```kotlin val jsonData = stampAnnotation.toInstantJson() val tempBinaryAttachmentJsonFile = File.createTempFile("tmp_", "stampAnnotationBinaryJsonAttachment.jpeg") val outputStream = FileOutputStream(tempBinaryAttachmentJsonFile) if (stampAnnotation.hasBinaryInstantJsonAttachment()) { stampAnnotation.fetchBinaryInstantJsonAttachment(outputStream) } val tempJsonFile = File.createTempFile("tmp_", "stampAnnotationJson.txt") FileWriter(tempJsonFile).use { w -> w.write(jsonData) } ``` ### JAVA ```java String jsonData = stampAnnotation.toInstantJson(); File tempBinaryAttachmentJsonFile = File.createTempFile("tmp_", "stampAnnotationBinaryJsonAttachment.jpeg"); FileOutputStream outputStream = new FileOutputStream(tempBinaryAttachmentJsonFile); if (stampAnnotation.hasBinaryInstantJsonAttachment()) { stampAnnotation.fetchBinaryInstantJsonAttachment(outputStream); } File tempJsonFile = File.createTempFile("tmp_", "stampAnnotationJson.txt"); File writer = new FileWriter(tempJsonFile); writer.write(jsonData); writer.flush(); writer.close(); ``` For information on detailed use, see the [catalog example](https://github.com/PSPDFKit/pspdfkit-android-catalog/blob/9eac1be5767cdeb5a58d879d0749c2338d4f77fb/app/src/main/java/com/pspdfkit/catalog/examples/kotlin/InstantJsonAttachmentExample.kt) for the Instant JSON attachment API. --- ## Related pages - [Effortlessly manage PDF annotations on Android](/guides/android/annotations/import-and-export/document-engine.md) - [Import and export PDF annotations from XFDF Files on Android](/guides/android/importing-exporting/xfdf-support.md)