PDF Filler is a RESTful service (API) to aid in the completion of existing PDF-based forms and empowers web developers to use browser-based forms and modern web standards to facilitate the collection of information.
PDF Filler works with virtually any unencrypted PDF, supporting both fillable (e.g., PDFs with pre-defined entry fields) and non-fillable (e.g., scanned PDFs) forms. Simply pass it the URL to any publicly hosted PDF. PDF Filler can even automatically create the markup necessary to embed an HTML form in an existing webpage.
- RESTful service (API) to aid in the completion of PDF-based forms
- Submit form values via HTTP POST, receive the completed PDF as a download
- Works with both fillable and non-fillable (e.g., scanned) PDFs
- Dynamically generates HTML forms for any fillable PDF
- Provides developers with field name lookup service to facilitate the rapid development of client applications
The project abstracts the form-filling logic of pdftk and prawn-fillform.
PDF Filler works by accepting a key => value pair of field names and values. These fields can either be fillable PDF form fields, or can be an arbitrary x/y coordinate of a non-fillable field. For fillable PDFs the key should represent the field name. In non-fillable PDFs, the key should represent the field coordinates as described below (e.g., 100,100). In both insstances, the field value should contain the user input for that given field.
Field names can be discovered locally using open-source PDF utility pdftk, or dynamically using the service.
To get a list of all fields within a given PDF
/fields?pdf={URL to the PDF}
To get a JSON representation of all fields within a given PDF
/fields.json?pdf={URL to the PDF}
To fill out a PDF, issue a POST request to /fill. POST data should be in the format of key => value where key reprents the field name and value represents the field value. Be sure to pass a key of "pdf" with the URL of the PDF to fill. The service will return the filled in PDF as a download.
To get a generic HTML representation of any fillable PDF form
/form?pdf={URL To PDF}
Non-Fillable PDFs (e.g., scanned or other PDFs without structured forms) require passing X, Y coordinates, and (optionally) a page number. This data is passed using the following naming convention for the field: x,y,page (or simply x,y) where X and Y represent the pointer coordinates from the bottom left hand corner of the document. If no page is given, the first page will be assumed.
Data can be submitted programmatically (e.g. via an API) or as a standard web-based form. For example, to structure an HTML form, you may do so as follows:
<form method="post" action ="/fill">
<!-- A standard, fillable field, simply pass the field name -->
<label>First Name: <input type="text" name="first_name" /><label>
<!-- A non-fillable field for which we pass coordinates -->
<label>Last Name: <input type="text" name="100,100,1" /><label>
<input type="submit" value="Submit" />
</form>
You can freely use PDF Filler as a web service. But if you'd like to grab the source code and host it locally, it's actually pretty easy.`
PDF Filler uses pdftk to handle the action form filling. pdftk can be freely downloaded and installed on most systems. If installed at a location other than ``, be sure to update the configuration.
PDF Filler is written in Ruby and uses Sinatra to generate a RESTful API
The app is designed to be hosted on hosting services like heroku. If using Heroku, be sure to select the "Bamboo" build (which comes compiled with pdftk) and set an environment config for PATH_TO_PDFTK to /usr/bin/pdftk.
Anyone is encouraged to contribute to the project by forking and submitting a pull request. (If you are new to GitHub, you might start with a basic tutorial.)
By contributing to this project, you grant a world-wide, royalty-free, perpetual, irrevocable, non-exclusive, transferable license to all users under the terms of the MIT License.
This project constitutes a United States Government Work under 17 USC 105 and is distributed under the terms of the MIT License.