---
title: "PDF form filling API"
canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-form-filling-api/"
md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-form-filling-api.md"
last_updated: "2026-07-06T00:00:00.000Z"
description: "Fill PDF form fields using Instant JSON and Nutrient DWS Processor API. Set text fields, checkboxes, radio buttons, choice fields, and signature appearances in existing PDF forms."
---

# PDF form filling API

Use the PDF form filling API to populate existing PDF form fields with data. The [`/build` endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) handles form filling. Add the source PDF as a `parts` item, and apply an Instant JSON file that contains `formFieldValues`.

For signup, pricing, and task-level examples, refer to the [PDF form filling API task page](https://www.nutrient.io/api/pdf-form-filling-api/).

## Fill form fields with Instant JSON

The following example fills fields in `forms.pdf` with `form_filling.json` and writes the output to `result.pdf`:

### Shell

### Shell (Windows)

### Java

### C#

### JavaScript

### Python

### PHP

### HTTP

## Create the form filling JSON

The Instant JSON file must include a `formFieldValues` array. Each item identifies a form field by its field name and provides the value to set.

Use this Instant JSON structure to fill text 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": "Email",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": "john.appleseed@example.com"
    }
  ],
  "format": "https://pspdfkit.com/instant-json/v1"
}

```

The field name must match the form field name in the PDF and not only the visible label next to the field.

## Fill checkboxes, radio buttons, and choice fields

For checkboxes, radio buttons, list boxes, and combo boxes, use the field’s export value. Depending on the field type, the value can be a string or an array of strings.

Use this Instant JSON structure to fill choice-based fields:

```json

{
  "formFieldValues": [
    {
      "name": "Newsletter",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": "Choice1"
    },
    {
      "name": "Knowledge Level",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": ["Beginner"]
    },
    {
      "name": "Select Days",
      "type": "pspdfkit/form-field-value",
      "v": 1,
      "value": ["Wednesday"]
    }
  ],
  "format": "https://pspdfkit.com/instant-json/v1"
}

```

For checkboxes and radio buttons, the PDF form field defines the on-state value. Common values include `Yes`, `On`, `Checked`, or a custom export value. Use the exact value defined in the PDF.

## Fill a form 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/forms.pdf"
      }
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": {
        "url": "https://example.com/form_filling.json"
      }
    }
  ]
}

```

### Shell

Run this request to fill a form 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/forms.pdf"
        }
      }
    ],
    "actions": [
      {
        "type": "applyInstantJson",
        "file": {
          "url": "https://example.com/form_filling.json"
        }
      }
    ]
  }' \
  -o result.pdf

```

## Add a visual signature appearance

You can use Instant JSON to add an image annotation over a signature field, such as a drawn signature image. This creates a visual signature appearance in the document.

Use this Instant JSON structure to add a visual signature appearance:

```json

{
  "annotations": [
    {
      "type": "pspdfkit/image",
      "v": 2,
      "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 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.

## Flatten filled forms

If the filled form 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 fill and flatten a form:

```json

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

```

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

## Fill password-protected forms

If the source PDF is password-protected, include the password on the part. Use this instructions object:

```json

{
  "parts": [
    {
      "file": "protected_form",
      "password": "document-password"
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": "form_filling.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 form filling with other actions

The `/build` endpoint can fill forms and then apply additional actions. For example, you can fill a form, flatten it, and then add a watermark.

Use this instructions object to combine form filling with other actions:

```json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "actions": [
    {
      "type": "applyInstantJson",
      "file": "form_filling.json"
    },
    {
      "type": "flatten"
    },
    {
      "type": "watermark",
      "text": "COMPLETED",
      "width": "50%",
      "height": "20%",
      "opacity": 0.3,
      "rotation": 45
    }
  ]
}

```

For workflows that include cryptographic signing, fill the form and optionally flatten it before signing the final PDF.

## Reference

A PDF form filling request uses the Build API `applyInstantJson` action with an Instant JSON file that contains `formFieldValues`:

```typescript

type FormFieldValue = {
  name: string,
  type: "pspdfkit/form-field-value",
  v: 1,
  value: string | string[],
};

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

type ApplyInstantJsonAction = {
  type: "applyInstantJson",

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

type FilePart = {
  // Multipart field name, or a remote URL object.
  file: string | { url: string },

  // Optional password for encrypted input PDFs.
  password?: string,
};

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 for applying Instant JSON, filling form fields, flattening the output, and applying follow-up actions in a single request.

## Related guides

- 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 digital signature API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md) guide.

- Refer to the [PDF merge API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-merge-api.md) guide.

- Refer to the [PDF split API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-split-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 security API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-security-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)
- [Import Instant JSON API](/guides/dws-processor/tools-and-api/import-instant-json-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 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)