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)
Download sample

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 with get_form_field_collection()
  • Use the collection for iteration and lookup
  • Inspect actual field names first (for example, print field.get_full_name() while iterating) before applying targeted updates
    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 full name, verify the type, and set the value.

In this sample:

  • Field name is Text1 (placeholder — use your actual field names)
  • In this SDK surface, compare get_field_type() with enum values (for example, PdfFormFieldType.TEXT.value)
  • Value is set with set_value("John Doe")
            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, verify the type, and set the checked state.

In this sample:

  • Field name is Check1 (placeholder — use your actual field names)
  • In this SDK surface, compare with PdfFormFieldType.CHECK_BOX.value
  • Set the value with set_value(...) (for example, many checkboxes use export value "On" when checked)
            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 group, verify the type, and select an option.

In this sample:

  • Group name is RadioGroup1 (placeholder — use your actual field names)
  • In this SDK surface, compare with PdfFormFieldType.RADIO_BUTTON.value
  • Set the group value with set_value("Option2") using a valid radio export value
            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 field, verify the type, and select one value.

In this sample:

  • Field name is Dropdown1 (placeholder — use your actual field names)
  • In this SDK surface, compare with PdfFormFieldType.COMBO_BOX.value
  • Set the value with set_value("Germany")

Values must match valid option/export values exactly.

            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, verify the type, and select values.

In this sample:

  • Field name is List1 (placeholder — use your actual field names)
  • In this SDK surface, compare with PdfFormFieldType.LIST_BOX.value
  • Set selection using set_value(...) with valid list item/export values

Values must match configured option/export values exactly.

            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

Iterate through all fields and apply type-based updates.

In this sample:

  • Processes terminal, non-read-only fields
  • Sets all text fields to "Sample Value"
  • Sets checkbox values

Use this pattern for default-value or bulk-fill workflows:

get_field_type() can return an integer. Compare against enum values (for example, PdfFormFieldType.TEXT.value and PdfFormFieldType.CHECK_BOX.value).

            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 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 get_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 get_field_type() before performing field-specific operations; in this SDK surface, compare with enum .value entries.
  6. Fill text fields with set_value(), using string values for text input.
  7. Fill checkbox, radio, combo, and list controls with set_value(...) using valid control values.
  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 get_is_terminal() and get_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 get_full_name() while iterating) and update lookups accordingly.

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