---
title: "Detecting and adding form fields to a PDF document | Nutrient Java SDK"
canonical_url: "https://www.nutrient.io/guides/java/editor/detect-and-add-form-fields/"
md_url: "https://www.nutrient.io/guides/java/editor/detect-and-add-form-fields.md"
last_updated: "2026-05-26T21:54:59.603Z"
description: "How to detect form fields in a PDF and add interactive form fields using Nutrient Java SDK."
---

# Detecting and adding form fields to a PDF document

Scanned forms — tax filings, healthcare intake sheets, lease agreements, expense reports — usually arrive as image-based PDFs. The page shows boxes, checkboxes, and signature lines, but the PDF has no AcroForm structure behind them, so end users can't fill the form in a viewer and downstream tools can't read the values. Adding those fields by hand means measuring rectangles for every blank on every page.

This sample shows how to detect form-field regions on each page of a document and add matching AcroForm fields automatically using Nutrient Java SDK. The input can be any document format the SDK supports. If the input isn't already a PDF, the SDK converts it to PDF when you create the editor.

[Download sample](https://www.nutrient.io/downloads/samples/java/detect-and-add-form-fields.zip)

## How Nutrient helps

Nutrient Java SDK handles the full detection-and-creation pipeline behind a single method call. The SDK takes care of:

- Implicitly converting non-PDF inputs (images, multi-page TIFFs, Office documents) to PDF when the editor is created

- Rendering each PDF page to a bitmap at the resolution the detection model expects

- Running the form-field detection model and classifying each region as text, checkbox, or signature

- Mapping image coordinates back to PDF page coordinates (including the Y-axis flip)

- Adding a matching AcroForm widget for each detected region with a unique field name

The result is a standard PDF with interactive form fields that any viewer can fill or any downstream tool can read.

## Supported field types and limits

The current detection model classifies regions into three types: text, checkbox, and signature. The SDK maps them to `PdfTextField`, `PdfCheckBoxField`, and `PdfSignatureField` respectively. Radio buttons aren't yet emitted by the model and are skipped. Detection runs on the rendered page image, so accuracy depends on the visual quality of the original document — clean scans produce better results than heavily compressed or skewed pages.

## Preparing the project

Specify a package name and create the main class:

```java

package io.nutrient.Sample;

```

Import the classes used in the sample:

```java

import io.nutrient.sdk.Document;
import io.nutrient.sdk.editors.PdfEditor;

public class DetectAndAddFormFields {

```

## Detecting and adding form fields

The entry point opens the source document, creates a PDF editor, and calls `detectAndAddFormFields()` to process every page in a single call. The sample uses a scanned form as input, but the same code handles raw images or any other supported document format:

```java

    public static void main(String[] args) {
        try (Document document = Document.open("input_forms_detection.pdf")) {
            PdfEditor editor = PdfEditor.edit(document);
            editor.detectAndAddFormFields();

```

`PdfEditor.edit(document)` attaches an editor to the open document. If the document isn't already a PDF, the SDK converts it to PDF at this step so the rest of the pipeline works on a uniform page representation. `editor.detectAndAddFormFields()` walks every page, runs detection, and adds an AcroForm widget for each detected region. Existing form fields on the document aren't removed — detection only adds new fields and synthesizes unique names so it doesn't collide with anything already present.

## Saving the result

Save the modified document to a new file and close the editor:

```java

            editor.saveAs("output.pdf");
            editor.close();
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

```

The `try` block uses try-with-resources, so the `Document` is closed automatically when the block exits, even if detection throws. The `catch` clause surfaces any licensing, model-loading, or I/O issue raised by the SDK.

## Conclusion

The workflow for auto-populating an image-based form is:

1. Open the source document.

2. Create a `PdfEditor` for the document.

3. Call `detectAndAddFormFields()` to detect and add fields across every page.

4. Save the result and close the editor.

The output is a standard PDF with interactive form fields, so existing PDF viewers can fill the form and downstream tools can read the values without any extra configuration.

For related workflows, refer to the [Java SDK guides](https://www.nutrient.io/guides/java.md).
---

## Related pages

- [Adding free text annotations to a PDF document](/guides/java/editor/add-freetext-annotations-to-pdf.md)
- [Adding a custom page to a PDF document](/guides/java/editor/add-custom-page-to-pdf.md)
- [Adding invisible digital signatures to a PDF document](/guides/java/editor/add-invisible-signature-to-pdf.md)
- [Adding link annotations to a PDF document](/guides/java/editor/add-link-annotations-to-pdf.md)
- [Adding interactive form fields to a PDF document](/guides/java/editor/add-form-fields-to-pdf.md)
- [Adding shape annotations to a PDF document](/guides/java/editor/add-shape-annotations-to-pdf.md)
- [Adding annotations to a PDF document](/guides/java/editor/add-annotations-to-pdf.md)
- [Adding redaction annotations to a PDF document](/guides/java/editor/add-redaction-annotations-to-pdf.md)
- [Adding stamp annotations to a PDF document](/guides/java/editor/add-stamp-annotations-to-pdf.md)
- [Adding sticky note annotations to a PDF document](/guides/java/editor/add-sticky-note-annotations-to-pdf.md)
- [Adding text markup annotations to a PDF document](/guides/java/editor/add-text-markup-annotations-to-pdf.md)
- [Adding visible digital signatures to a PDF document](/guides/java/editor/add-visible-signature-to-pdf.md)
- [Advanced digital signature workflows](/guides/java/editor/advanced-digital-signatures.md)
- [Editing PDF metadata with Nutrient Java SDK](/guides/java/editor/editing-pdf-metadata.md)
- [Editing PDF form fields](/guides/java/editor/editing-pdf-form-fields.md)
- [Filling PDF form fields](/guides/java/editor/fill-pdf-form.md)
- [Managing PDF page order](/guides/java/editor/manage-pdf-page-order.md)
- [Merging PDFs](/guides/java/editor/merge-pdf-into-other-pdf.md)
- [Nutrient Java SDK editor guides](/guides/java/editor.md)