Introduction
PDF documents are not merely the PDF pages themselves. Sometimes, PDFs have annotations, which can be added to the pages without altering their content. PDF annotations can be used for a variety of purposes, from marking up the documents to adding interactive components to the documents such as forms.
Annotation types
The documentation for PDFs describes the various types of PDF annotations, classifying them into two categories – markup annotations and non-markup annotations.
Markup annotations
Markup annotations mark up the contents of a PDF document. Some examples are underscore, strikeout, or highlighting of text in PDF documents.
Non-markup annotations
PDF annotating does not need to integrate directly with the contents of a PDF document. Non-markup annotation types can have a variety of purposes. They can be used for annotating PDF windows, as well as for annotating PDF files.
With the proper PDF annotating software, annotations can include lines or shapes drawn on the document, similar to the features in image drawing software. Complex images can also be drawn or placed on the PDF document.
Text, in the form of sticky notes or a floating text box, can be added to a page as well as multimedia such as sounds or movies. It is even possible to add widgets such as interactive forms as an annotation to a PDF.
The PDF annotation model
PDF annotations are dictionaries of key-value pairs within the document. Each annotation is one dictionary with at least two keys: Rect (rectangle) specifies the coordinates of the annotation’s position on the page, and Subtype specifies the annotation type. The annotation type is one of the types supported in the PDF technical specification. It indicates which additional keys are required, and which may also be present.
The document as a whole can be represented as a tree data structure of dictionaries of key-value pairs. The child nodes of the tree are the dictionaries of key-value pairs the parent dictionaries contain as values. These dictionaries contain the various features of the document. The top-level node is the document itself, and the next-level nodes are the pages in the document. Each page is its own dictionary, containing the contents of the page and the annotations.
Using pdfFiller’s API
pdfFiller is a full-service PDF editor, with a request-response API focused on filling out and signing PDF forms as well as adding other types of annotations. The API manages eSignatures with the special signNow feature. It enables users to work on PDF documents without leaving an external website.
If you have API access, the “Settings” tab of developers.pdffiller.com will show Account Info, including sections for you to generate API keys. If not, this tab will merely show a link to the API documentation.
The API can be invoked in a variety of programming languages. Here is how to use a few of its features.
Uploading a PDF document from URL
In order to manipulate a PDF document in pdfFiller, the document must first be obtained and formatted. There are multiple types of documents handled by pdfFiller. A document, in pdfFiller terminology, is a PDF to which fillable fields such as text, signatures, and images can be added and filled. It can be converted into a reusable PDF template. In a fillable PDF form, the fillable fields can be both added and filled.
Transferring the document to the Server
This can be done by a single shell command:
1 2 3 4 |
curl -X "POST" "https://api.pdffiller.com/v2/templates" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/json" \ -d "{\"file\":\"https://some.url/somefile.pdf\"}" |
It returns a JSON object containing, among other things, the document ID. If one wants to continue working with the file through the API, it is important to save this ID for future use. Documents can also be uploaded here.
Viewing the document
However you upload documents, you can see them in the list of your uploaded documents on the Dashboard of your pdfFiller account. The “Add Fillable Fields” tab on the right of an open document enables you to add fields to be filled out through the API. Be sure you name the fields, so you can keep track of them.
Filling out the document
We’re adding a text field to the document, which we’ll call Text_1, and a signature field, which we’ll call Signature_1. After you add the fillable fields, you can convert the document into a template on the Dashboard of your pdfFiller account, or download the file and upload it as a template using the API. Click the three dots on the right of the document, as it is listed on your Dashboard.
Now go to Manage Documents -> Convert to template and transform the document into a template. The template will appear in the Templates tab of your Dashboard.
Or, to upload the file as a template after download, you can type this command:
1 2 3 |
curl -X "POST" "https://api.pdffiller.com/v2/templates" \ -H "Authorization: Bearer API_KEY" \ -F "file=@/path/to/file.pdf" |
For future use, you will need to obtain the template ID. In the list of templates in your account, click the three dots on the right of the template whose ID you want to obtain. You will find the template ID by going within that menu to Manage Documents -> Template Info.
The API enables you to perform a variety of operations using the template ID, such as getting the list of fillable fields and filling them out.
Transforming the document into a fillable PDF form
It is also possible to reformat the document as a fillable PDF form, done as follows:
1 2 3 4 |
curl -X "POST" "https://api.pdffiller.com/v2/fillable_forms" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/json" \ -d "{\"document_id\":\"DOCUMENT_ID\",\"access\":\"full\",\"status\":\"public\"}" |
Again, this returns a JSON object representing the newly formatted document. It is important to save the fillable_form_id value, which is the ID of the link for hosting the fillable form, and the url value, which is the URL for public access to the document.
Filling out the fillable PDF form
Once the document is uploaded, it can be viewed at the URL returned in the response obtained from transforming it into a fillable PDF form. Fillable form fields can be created and filled manually, using the buttons on top. Here, I have created a “This is a test” text field and a “Test Signature” signature field on the document.
Why choose pdfFiller?
pdfFiller is premier, easy-to-use PDF annotating software. It can securely and reliably handle the filling out and signing of PDFs. Reviewers note how much faster and easier pdfFiller is, compared to other PDF editing services. Annotating PDF files with pdfFiller is especially convenient when it is one of many automated steps in a larger process. pdfFiller is available as a standalone solution and as a part of airSlate’s suite of digital transformation tools. airSlate is a no-code workflow management system, which enables nontechnical staffers to build complex automatic workflows and which has been game-changing for streamlining many companies’ internal processes.
The pdfFiller API’s pricing starts at $1,000 per year, with discounts per document for larger plans. Start using the API here.