Blog Post

How to Fill Out PDF Forms in Java

Illustration: How to Fill Out PDF Forms in Java

PDF forms are widely used in many onboarding processes and account creation requests. Due to the well-defined standard of the PDF specification and vast support across many different platforms, it’s easy to see why companies and individuals want to work with PDF forms.

The Use Case

Most people would expect a person to fill out a PDF, field by field, but today we’re going to cover a slightly different use case, in which we’ll programmatically fill out the PDF form. This use case could be for when there is a mobile- or web-based onboarding system where the UI can enhance the experience for the user, but we still want the “paper” trail to be created with PDFs for electronic archiving purposes.

This is where a PDF library can come in handy. Once we’ve collated all the data from user input, we’ll require a library to fill the PDF form programmatically. At this point, we can save the filled-in document and send it or manipulate it further.

In the following example, we’re going to see how form filling is possible in Java with the PSPDFKit Java Library. You can jump in straight away by downloading the trial today.

Prepare the Data

First we’re going to look at setting up the data in a way that the PSPDFKit Java Library can understand and in a way that maps to the target document.

The great news is that the PSPDFKit Java Library supports form filling with JSON, which is often the format of the received data. If your data is not in JSON format, it’s very simple to map the data with plenty of open source libraries like org.json.

Let’s say we have the following, all of which are standard pieces of information we’d normally collect during an onboarding session:

  • First Name

  • Last Name

  • DOB

  • Address

  • Telephone Number

The arrangement of data that the PSPDFKit Java Library requires is a JSON object with key-value pairs, where the key is the name of the form field, and the value is the value to assign.

In our PDF form, the names of the form fields we’d like to fill, as defined by the document, are:


To create the JSON data, we use a JSONObject to set up our key-value pairs:

JSONObject valuesToSet = new JSONObject();
valuesToSet.put("Name_First", "John");
valuesToSet.put("Name_Last", "Smith");
valuesToSet.put("Birthdate", "12/12/12");
valuesToSet.put("Address_1", "123 My Street");
valuesToSet.put("Telephone_Home", "+12345678");

You can imagine all the values could be data-driven from a number of different sources: a database, a RESTful API, or any other unique data source.

Fill the Form Field Values

Now that we have our data in a format that the PSPDFKit Java Library can read, we can set the form fields on the document. Note that the list of values does not have to be exhaustive; we can set either all or a subset of the fields and the values will be taken.

There is only one call we have to make to set the form fields: setFormFieldValuesJson. And we’ll be calling this method on the document we want to set the form fields on:

PdfDocument document = FileDataProvider(new File("formDocument.pdf")));



If any of the field names provided cannot be found, an exception will be thrown.

Reading Form Field Values

In some cases, we may want to read what form fields are already filled or get a list of form fields within the document. getFormFieldValuesJson allows us to query the entire document for form fields. The method will return the values for all the form fields found in the document:

PdfDocument document = FileDataProvider(new File("formDocument.pdf")));



formFieldValues will hold a JSON object, again with key-value pairs:

  "Name_First": "John",
  "Name_Last": "Smith",
  "Name_Middle": null,

We can see from the JSON above that the first name and last name were set, but we can also see that there was an additional middle name. It was not filled because we did not give a value for Name_Middle. This is perfectly acceptable, and in this case, the field will remain blank. We know that nothing was set because Name_Middle gives a value of null.

Saving the Document

Now we want to save the changes that have been made to ensure the values are reflected in the document permanently. Very simply, to save, we will need to call save on the document: DocumentSaveOptions.Builder().build());

The above code will save the changes back to the same data provider that was opened. If we’d like to save to a different location, we could have easily used saveAs.

It’s also worth noting that the form fields in the saved document will still be editable. Therefore, the document can be opened again and the form field values can be changed.

If we want to ensure the form is non-editable, we have the option to flatten the document. Flattening a document means that all the form boxes and annotations on the pages will be embedded into the contents of the document and will no longer be editable with a standard PDF Viewer. Be aware though that just because a standard viewer cannot edit a document, it does not mean others can’t. If you want to ensure that the document is not tampered with, please look into Digital Signatures. DocumentSaveOptions.Builder().flattenAnnotations(true).build());

From the above, we can see we just need to use the flattenAnnotations flag and the document will be fully rewritten with all the annotations and form fields embedded as part of the contents of the document.


From this blog post, you’ve learned that with just a few lines of code you can take a data source, fill out a PDF form, and save and even flatten that data back into the document for use elsewhere.

The steps outlined above can be adapted to support many different scenarios — for example, reading the data from a database, automating the forwarding of the filled PDF to the next department, or even performing post-form filling document editing as seen in our How to Merge Two or More PDFs in Java (or Kotlin) post.

To find out more about form filling with the PSPDFKit Java Library, or to learn about the many other features supported by the library, please head over to our free trial page and download our library today.

Related Products
Share Post
Free 60-Day Trial Try PSPDFKit in your app today.
Free Trial

Related Articles

Explore more
TUTORIALS  |  iOS • How To • Signing • PDF

How to Digitally Sign a PDF Using a YubiKey

SOLUTIONS  |  Solutions • PDF

Revolutionizing the Construction Industry with PDF Technology


How to Save Custom Data in Image Files