Filling PDF form fields

Use PDF form filling to set field values from your application data.

Common use cases include:

• Prepopulating onboarding or registration forms
• Filling claim and compliance forms from backend systems
• Running batch form generation from CSV or database records
• Building template-based document assembly pipelines

In this guide, you’ll fill:

• Text fields
• Checkboxes
• Radio button groups
• Combo boxes
• List boxes (single and multi-select)

How Nutrient helps

Nutrient Python SDK handles form field access, type-specific operations, and value validation.

The SDK handles:

• PDF form field dictionaries and field type detection
• Low-level value and method validation
• Hierarchy traversal for nested fields
• State synchronization for selection controls

Complete implementation

This example fills multiple form field types in one workflow.

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 the document in a context manager(opens in a new tab) so resources are cleaned up after processing.

Then:

• Create an editor with PdfEditor.edit(document)
• Get all form fields via editor.form_field_collection
• Use the collection for iteration and lookup
• Inspect actual field names first (for example, print field.full_name while iterating) before applying targeted updates

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

Filling a text field

Find a text field by full name, verify the type, and assign the value.

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

Checking a checkbox

Find a checkbox field, verify the type, and toggle its checked state via the is_checked property.

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

Selecting a radio button option

Find a radio group, verify the type, and assign one of its option values.

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

Selecting an item in a combo box

Find a combo box field, verify the type, and assign the export value of the choice you want.

Values must match a valid export value exactly.

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

Selecting an item in a list box

Find a list box field, verify the type, and assign the export value of the choice you want. The current binding exposes single-value selection through selected_value; multi-select is not yet supported in the Python SDK.

            list_box = form_fields.find_by_full_name("List1")
            if list_box is not None and list_box.field_type == PdfFormFieldType.LIST_BOX:
                list_box.selected_value = "Technology"

Iterating and filling all fields

Iterate through every field and apply type-based updates. Process only terminal, non-read-only fields.

            for field in form_fields:
                if field.is_terminal and not field.is_read_only:
                    field_type = field.field_type

                    if field_type == PdfFormFieldType.TEXT:
                        field.value = "Sample Value"
                    elif field_type == PdfFormFieldType.CHECK_BOX:
                        field.is_checked = True

Saving the filled form

Save the output PDF and close the editor.

In this sample:

• save_as("output.pdf") writes a new file
• editor.close() releases editor resources
• NutrientException handles runtime failures

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


if __name__ == "__main__":
    main()

Conclusion

Use this workflow to fill PDF form fields:

1. Open the document using a context manager(opens in a new tab) for automatic resource cleanup.
2. Create a PDF editor and retrieve the form field collection with form_field_collection.
3. The form field collection provides access to all form fields regardless of type.
4. Use find_by_full_name() to locate specific fields by their fully qualified names (including hierarchy).
5. Verify field types with field_type before performing field-specific operations.
6. Fill text fields using value = "...".
7. Fill checkbox, radio, combo, and list controls using their type-specific properties (is_checked, selected_option, selected_value).
8. For checkbox and radio controls, use valid export values (for example, checkbox values are often "On").
9. For combo/list controls, values must match available option text/export values exactly.
10. Iterate all fields with conditional logic using is_terminal and field_type for batch filling operations.
11. Save the document with save_as() to persist all filled field values.
12. Handle exceptions with try-except blocks for robust error recovery in production workflows.
13. Close the editor with editor.close() to release resources.

Field names used in this sample (Text1, Check1, RadioGroup1, Dropdown1, List1) are placeholders. Inspect actual field names in your PDF first (for example, print full_name while iterating) and update lookups accordingly.

For related form workflows, refer to the Python SDK editor guides.