---
title: "Import Instant JSON API"
canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/import-instant-json-api/"
md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/import-instant-json-api.md"
last_updated: "2026-07-06T00:00:00.000Z"
description: "Import Instant JSON into PDF files using Nutrient DWS Processor API. Apply annotations, form field values, attachments, and other Instant JSON data to existing PDFs."
---

# Import Instant JSON API

Use the import Instant JSON API to apply Instant JSON data to a PDF. Instant JSON is Nutrient’s JSON format for representing PDF annotations, form field values, attachments, and related document records.

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

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

## Import Instant JSON

The following example imports Instant JSON from `annotations.json` into `document.pdf` and writes the output to `result.pdf`:

### Shell

### Shell (Windows)

### Java

### C#

### JavaScript

### Python

### PHP

### HTTP

## Import Instant JSON from URLs

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

```json

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

```

### Shell

Run this request to import Instant JSON 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": "applyInstantJson",
        "file": {
          "url": "https://example.com/annotations.json"
        }
      }
    ]
  }' \
  -o result.pdf

```

## Import annotations

Instant JSON can contain annotations, such as highlights, notes, ink annotations, stamps, and image annotations.

The following example imports one note annotation:

```json

{
  "annotations": [
    {
      "type": "pspdfkit/note",
      "v": 2,
      "id": "01J0EXAMPLEANNOTATIONID0001",
      "pageIndex": 0,
      "bbox": [100, 100, 32, 32],
      "contents": "Review this section",
      "createdAt": "2026-06-29T00:00:00Z",
      "updatedAt": "2026-06-29T00:00:00Z"
    }
  ],
  "format": "https://pspdfkit.com/instant-json/v1"
}

```

Use the exact annotation data exported from Nutrient SDKs or another system that produces compatible Instant JSON.

## Fill form fields with Instant JSON

Instant JSON can also set PDF form field values. Add a `formFieldValues` array and reference form fields by their field names.

Use this Instant JSON structure to fill form fields:

```json

{
  "formFieldValues": [
    {
      "name": "First Name",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": "John"
    },
    {
      "name": "Last Name",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": "Appleseed"
    },
    {
      "name": "Newsletter",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": "Choice1"
    }
  ],
  "format": "https://pspdfkit.com/instant-json/v1"
}

```

The field name must match the form field name in the PDF, not only the visible label next to the field. For form-specific examples, refer to the [PDF form filling API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-form-filling-api.md) guide.

## Import image attachments

Some Instant JSON annotations reference attachments, such as image annotations or visual signature appearances. Include attachments in the `attachments` object, and reference them by ID from the annotation.

Use this Instant JSON structure to import an image attachment:

```json

{
  "annotations": [
    {
      "type": "pspdfkit/image",
      "v": 2,
      "id": "01J0EXAMPLEIMAGEANNOTATION1",
      "pageIndex": 0,
      "bbox": [72, 700, 200, 48],
      "contentType": "image/png",
      "imageAttachmentId": "signature-image",
      "isSignature": true
    }
  ],
  "attachments": {
    "signature-image": {
      "binary": "<base64-encoded-png>",
      "contentType": "image/png"
    }
  },
  "format": "https://pspdfkit.com/instant-json/v1"
}

```

A visual signature appearance imported this way differs from a cryptographic digital signature. To cryptographically sign a PDF, use the Processor API digital signature endpoint. For digital signing workflows, refer to the [PDF digital signature API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md) guide.

## Import and flatten Instant JSON

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

Use this instructions object to import and flatten Instant JSON:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": "annotations.json"
    },
    {
      "type": "flatten"
    }
  ]
}

```

Flattening turns annotations and form appearances into regular page content. Use it only when the output no longer needs editable annotations or form fields.

## Import Instant JSON into selected pages

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

Use this instructions object to import Instant JSON into selected pages:

```json

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

```

Make sure page indexes, bounding boxes, and form field names in the Instant JSON match the PDF that the action applies to.

## Import Instant JSON 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": "applyInstantJson",
      "file": "annotations.json"
    }
  ]
}

```

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 Instant JSON import with other actions

The `/build` endpoint can import Instant JSON and then apply additional actions. For example, you can import annotations, add a watermark, and then flatten the final output.

Use this instructions object to combine Instant JSON import with other actions:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": "annotations.json"
    },
    {
      "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 Instant JSON before signing the final PDF.

## Reference

An Instant JSON import request uses the Build API `actions` array with an `applyInstantJson` action:

```typescript

type ApplyInstantJsonAction = {
  type: "applyInstantJson",

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

type InstantJson = {
  annotations?: object[],
  formFieldValues?: object[],
  attachments?: Record<string, object>,
  format: "https://pspdfkit.com/instant-json/v1",
};

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 Instant JSON import.
  pages?: {
    start?: number,
    end?: number,
  },
};

type BuildInstructions = {
  parts: FilePart[],
  actions: ApplyInstantJsonAction[],
  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 Instant JSON and combine import with flattening, watermarking, security, or other document actions.

## Related guides

- Refer to the [import XFDF annotations API](https://www.nutrient.io/guides/dws-processor/tools-and-api/import-xfdf-annotations-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 flatten API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-flatten-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)
- [DOCX templating API](/guides/dws-processor/tools-and-api/docx-templating-api.md)
- [Import XFDF annotations API](/guides/dws-processor/tools-and-api/import-xfdf-annotations-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)