Filling PDF form fields

Filling PDF form fields programmatically enables teams to automate document workflows, build form prepopulation systems, and implement data integration pipelines. Whether you’re creating automated form filling workflows for employee onboarding, building government form submission systems where applicant data prepopulates from databases, implementing insurance claim processing where policy information automatically fills claim forms, creating document assembly systems that merge data into form templates, or building batch processing workflows that fill thousands of forms from CSV or database records, programmatic form filling provides precise control over field values and states. Form filling operations include populating text fields with string values, setting checkbox checked states, selecting radio button options from groups, choosing combo box items from available options, and selecting single or multiple list box entries.

How Nutrient helps you achieve this

Nutrient Python SDK handles PDF form field manipulation, method calls, and value validation. With the SDK, you don’t need to worry about:

Parsing PDF form field dictionaries and identifying field types correctly
Managing field method calls and value format validation
Handling field hierarchy traversal for nested field structures
Complex field state management for checkboxes, radio buttons, and selections

Instead, Nutrient provides an API that handles all the complexity behind the scenes, enabling you to focus on your business logic.

Complete implementation

Below is a complete working example that demonstrates filling PDF form fields with various field types, including text fields, checkboxes, radio buttons, combo boxes (dropdowns), and list boxes. The following lines set up the Python application. Start by importing the required classes from the SDK:

from nutrient_sdk import Document
from nutrient_sdk import PdfEditor
from nutrient_sdk import PdfFormFieldType
from nutrient_sdk import NutrientException

Create the main function:

def main():

Opening a document with form fields

Open a PDF document that contains form fields using a context manager(opens in a new tab) for automatic resource cleanup. The following code opens the PDF document, creates a PDF editor instance with PdfEditor.edit(), and retrieves the form field collection using get_form_field_collection(). This collection provides access to all form fields defined in the document, enabling iteration, lookup by name, and field value manipulation. The form field collection supports all PDF form field types, including text fields, checkboxes, radio buttons, combo boxes (dropdowns), list boxes, and signature fields:

    try:
        with Document.open("input_forms.pdf") as document:
            editor = PdfEditor.edit(document)
            form_fields = editor.get_form_field_collection()

Filling a text field

Find a text field by name and set its value using field-specific methods. The following code uses find_by_full_name() to locate the text field by its fully qualified name "Text1" (including parent hierarchy if nested). The null check verifies the field exists in the document. The get_field_type() method returns the field type enumeration, and the comparison == PdfFormFieldType.TEXT confirms the field is a text input field. The set_value("John Doe") method call populates the text field with the string value "John Doe", which will display in the PDF form when opened in a viewer:

            text_field = form_fields.find_by_full_name("Text1")
            if text_field is not None and text_field.get_field_type() == PdfFormFieldType.TEXT:
                text_field.set_value("John Doe")

Checking a checkbox

Find a checkbox field and set its checked state using Boolean values. The following code locates the checkbox field "Check1" using find_by_full_name() and verifies it’s a checkbox type with get_field_type() == PdfFormFieldType.CHECK_BOX. The set_checked(True) method sets the checkbox to checked state (True = checked, False = unchecked). This operation updates the field’s appearance stream, causing PDF viewers to display the checkbox with a checkmark. Checkboxes are commonly used for binary yes/no selections, agreement acknowledgments, or opt-in/opt-out choices in forms:

            checkbox = form_fields.find_by_full_name("Check1")
            if checkbox is not None and checkbox.get_field_type() == PdfFormFieldType.CHECK_BOX:
                checkbox.set_checked(True)

Selecting a radio button option

Find a radio button group and select a specific option by its export value. The following code locates the radio button group "RadioGroup1" using find_by_full_name() and verifies it’s a radio button type with get_field_type() == PdfFormFieldType.RADIO_BUTTON. Radio button groups contain multiple mutually exclusive options (buttons) that share the same parent field name. The set_selected_option("Option2") method selects the radio button with export value "Option2", automatically deselecting any previously selected option in the group. Each radio button in the group has a unique export value defining its identity, and only one option can be selected at a time. Radio buttons are commonly used for single-selection choices like gender, payment method, or preference selections:

            radio_group = form_fields.find_by_full_name("RadioGroup1")
            if radio_group is not None and radio_group.get_field_type() == PdfFormFieldType.RADIO_BUTTON:
                radio_group.set_selected_option("Option2")

Selecting an item in a combo box

Find a combo box (dropdown) field and select a specific item from its available options. The following code locates the combo box field "Dropdown1" using find_by_full_name() and verifies it’s a combo box type with get_field_type() == PdfFormFieldType.COMBO_BOX. Combo boxes (also called dropdowns) display a list of predefined options when clicked, with only one option visible initially. The set_selected_item("Germany") method selects the option with value "Germany" from the dropdown’s option list. The selected value must match exactly one of the predefined options configured in the form field’s option array. If the value doesn’t exist in the options, the selection fails silently. Combo boxes are commonly used for country selection, state/province selection, or category choices where users pick from a predefined list:

            combo_box = form_fields.find_by_full_name("Dropdown1")
            if combo_box is not None and combo_box.get_field_type() == PdfFormFieldType.COMBO_BOX:
                combo_box.set_selected_item("Germany")

Selecting items in a list box

Find a list box field and select one or more items from its available options. The following code locates the list box field "List1" using find_by_full_name() and verifies it’s a list box type with get_field_type() == PdfFormFieldType.LIST_BOX. List boxes display multiple options simultaneously in a scrollable list, unlike combo boxes, which show only one option initially. The set_selected_item("Technology") method selects a single option with value "Technology". The set_selected_items(["Technology", "Music"]) method enables multiple selection when the list box is configured for multi-selection mode. List boxes can be configured to enable single or multiple selections — when multiple selection is enabled, users can select several items. The selected value(s) must match exactly one or more of the predefined options in the list box’s option array. List boxes are commonly used for multi-category selection, skills selection, or interest selection where users can see multiple options at once:

            list_box = form_fields.find_by_full_name("List1")
            if list_box is not None and list_box.get_field_type() == PdfFormFieldType.LIST_BOX:
                # Select a single item
                list_box.set_selected_item("Technology")

                # Or select multiple items if multi-select is enabled
                list_box.set_selected_items(["Technology", "Music"])

Iterating and filling all fields

Fill multiple fields programmatically by iterating through the entire form field collection and applying batch operations. The following code demonstrates batch form filling using iteration and conditional logic. The loop iterates through all form fields in the collection. The get_is_terminal() check identifies terminal fields (leaf nodes with actual values) rather than parent container fields, and not get_is_read_only() filters out read-only fields that shouldn’t be modified. The get_field_type() method returns the field type enumeration, enabling type-specific handling. The first conditional branch checks field_type == PdfFormFieldType.TEXT to identify text fields and sets a default value, "Sample Value". The second branch checks field_type == PdfFormFieldType.CHECK_BOX to identify checkboxes and checks all checkboxes with set_checked(True). This batch processing pattern is commonly used for form prepopulation from database records, applying default values across multiple forms, or testing form layouts with sample data:

            for field in form_fields:
                if field.get_is_terminal() and not field.get_is_read_only():
                    field_type = field.get_field_type()

                    if field_type == PdfFormFieldType.TEXT:
                        field.set_value("Sample Value")
                    elif field_type == PdfFormFieldType.CHECK_BOX:
                        field.set_checked(True)

Saving the filled form

Save the document with all filled form values to persist the field data. The following code uses save_as() to write the modified document to a new file, "output.pdf", preserving the original input file. The editor.close() call releases resources associated with the editor. All field values set during the session are embedded in the PDF structure, becoming part of the document’s permanent data. When users open the saved PDF in a viewer, all filled fields display the programmatically set values. The except block captures any exceptions during form filling or saving, printing error messages for debugging. This pattern ensures proper error handling for production workflows where form filling may fail due to invalid field names, type mismatches, or file system errors:

            editor.save_as("output.pdf")
            editor.close()
    except NutrientException as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Conclusion

The PDF form filling workflow consists of several key operations:

Open the document using a context manager(opens in a new tab) for automatic resource cleanup.
Create a PDF editor and retrieve the form field collection with get_form_field_collection().
The form field collection provides access to all form fields regardless of type.
Use find_by_full_name() to locate specific fields by their fully qualified names (including hierarchy).
Verify field types with get_field_type() before performing field-specific operations.
Fill text fields with set_value(), using string values for text input.
Set checkbox states with set_checked() using Boolean values (True = checked, False = unchecked).
Select radio button options with set_selected_option() using export values from the option group.
Select combo box items with set_selected_item() matching predefined dropdown options exactly.
Select list box items with set_selected_item() for single selection or set_selected_items() for multiple selection configurations.
Iterate all fields with conditional logic using get_is_terminal() and get_field_type() for batch filling operations.
Save the document with save_as() to persist all filled field values.
Handle exceptions with try-except blocks for robust error recovery in production workflows.
Close the editor with editor.close() to release resources.

Nutrient handles PDF form field dictionary parsing, field type identification, method call validation, value format checking, and field appearance stream updates so you don’t need to understand PDF form field specifications or manage field state synchronization manually. The form filling system provides precise control for automated document workflows, form prepopulation from databases, data integration pipelines merging external data into form templates, batch processing workflows filling thousands of forms from CSV or database records, and document assembly systems creating filled forms from templates.