Questions? Call us now: 617-396-4777 or Chat Now

About PDFfiller API

The PDFfiller REST API allows you to build applications that interact with PDFfiller service to create fillable forms, send e-signature requests, fill out documents, collect the submitted data, and perform other complex functions.

All API transmissions are SSL-encrypted and must be made over HTTPS protocol. We recommend using SSL version 3 and above and TLS version 1.0 and above. PDFfiller supports OAuth2 authentication with password and authorization_flow grants. JSON is returned for all API responses except file downloads. PDFfiller provides API client libraries for specific languages to help convert API objects to that programming language’s format.

API base URL
https://api.pdffiller.com
API request URL includes API version and object. For example:
https://api.pdffiller.com/v1/signature_request

PDFfiller API provides the following features:

  • /fill_request – allows users to share a document by a link, which can be seen, filled out and submitted instantly by their recipients. The fillable documents can be embedded to your site or accessed directly from PDFfiller.
  • /signature_request – allows users to send a document for recipients’ signature. PDFfiller manages full document workflow including signer notifications, authentication and signature collection order from multiple recipients.
  • /fillable_template – allows filling document templates with pre-defined fillable fields. Template fields can be populated by custom data.
  • /callback – event-triggered callbacks.  HTTP REST requests are sent to custom URL upon completion of specific user actions, such as document filling or signatures.
  • /token – unique tokens assigned to fill requests to identify signers and associate custom data, which can be retrieved by API call or returned with callback.

 

Getting Started

To start working with PDFfiller API login or register at www.pdffiller.com.

Go to FOR BUSINESS > For Developers.

 

paperless-forms-document-workflow-solutions-for-businesses-_-pdffiller-google-chrome-2017-02-10-16-12-34

 

Authentication Credentials

Obtaining authorization credentials

1. Login or register at PDFfiller.

2. Visit developers page and click to API Settings tab

3. Get API Key from the Security section

 

Upload document

Upload a document

1. Get your API Key from PDFfiller account settings.
http://www.pdffiller.com/en/developers

2. Upload a new document template from URL or local disk.

2.1. Uploading a file from your computer

Code

2.2. Uploading a file from web by URL

Code
 

Success response from API contains information about the created document template

Code
 

Authentication Overview

PDFFiller API authentication is based on the OAuth 2.0. security framework.

OAuth 2.0. is a protocol that allows your application to request authorization to private data in a user’s PDFfiller account without getting their password.

The first step in the authentication process is to obtain an API key, or access token, from the PDFfiller server to authorize access to the API. The OAuth 2.0 framework provides a number of methods for obtaining the access token from the PDFfiller authorization server. The simplest way of getting the API key for a registered user is to click on the API Settings tab on the PDFfiller developers page.

optimized-2exz

The API key is shown in the Security section. Copy the API key and insert it into the HTTP header “Authorization” to send requests to PDFfiller’s server:

“Authorization: Bearer API_KEY”

API Key must be included in the HTTP “Authorization” header with every API request along with “Bearer” token type.

You can refresh the API key by pressing REGENERATE KEY.

OAuth 2.0 Authorization

OAuth 2.0 allows your app to request authorization to access documents and other information in a PDFfiller user’s account and to perform PDffiller operations on behalf of a user.

Step 1 – Create Application

To start with OAuth 2.0 authorization flow, you need register your application in PDFfiller API Settings. Upon registration, app is assigned a ClientID and Client Secret, which will be used to authorize against PDFfiller and to obtain authorization grant.

Open My Apps section in API page on PDFfiller website and click CREATE NEW APP button.

0e2c325f8a

Fill the form and click CREATE APPLICATION button.

  • Name - name to identify your app
  • Description – brief description of the app
  • OAuth callback Url – callback URl where authorization grant will be returned after successful authentication

9a4da19432

Note Client ID and Client Secret. You will use them later in your authentication process.

Step2 – Obtain Authorization Code

From your app you need to redirect  your user to:

Users will be asked to login to PDFfiller if needed. Following authorization dialog will be presented to user:

 

ffc917cb2d

When AUTHORIZE button clicked, user redirected to REDIRECT_URL from application setup with issued authorization_code:

Step3 – Obtain Access Token

Now, you can use authorization token obtained in the Step2 to obtain your authorization grant

 

OAuth 2.0 Grants

The OAuth 2.0 code grant flow allows issuing access tokens on behalf of users. It means that your application can request authorization to access documents and other information in a user’s account and perform PDffiller operations on behalf of this user. In this case, the authentication process has several steps. To start the OAuth 2.0 authorization flow, you need to register your application or client in the PDFfiller API Settings. Upon registration, the application is assigned a Client ID and Client Secret, which will be used to send an authorization request to the user’s PDFfiller account and obtain an authorization grant.
Generally, OAth 2.0 provides a number of methods, or grants, which allow the application to get the access tokens. PDFfiller API uses three types of authorization grants: authorization code grant, resource owner credentials grant, and refresh token grant.

Authorization Code Grant

The scheme of authorization code grant flow is as follows:

api-picture

Step 1

The application redirects the user to:

https://www.pdffiller.com/en/developers/api_access with the following parameters in the query string:

  • client_id with the client identifier
  • redirect_uri with the client redirect URI

Step 2

The user authorizes the application to access the account, and the authorization code is returned to the above mentioned redirect URI with the following parameters in the query string:

  • code with the authorization code
  • uri with the https://api.pdffiller.com/

Step 3

The application sends this authorization code to the PDFfiller authorization server and receives an access token:

https://api.pdffiller.com/v1/oauth/access_token:

  • grant_type with the value of authorization_code
  • client_id with the client identifier
  • client_secret with the client secret
  • redirect_uri with the same redirect URI the user was redirected back to
  • code with the authorization code from the query string

Step 4

The authorization server will respond with a JSON object containing the following properties:

  • expires_in with an integer representing the TTL of the access token (i.e. when the token will expire)
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

This grant type is used for confidential applications.

The process of acquiring the access token can omit the specific steps from the authorization code grant scheme.

Resource Owner Credentials Grant

Resource owner credentials grant is recommended to use only with trusted first party applications. To obtain an access token, the application asks the user for their authorization credentials (user ID and password). When the credentials are received, the client sends the request to the authorization server:

  • grant_type with the value password
  • client_id with the client’s ID
  • client_secret with the client’s secret
  • username with the user’s username
  • password with the user’s password

The PDFfiller authorization server responds with a JSON object featuring the following:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

As we can see, this flow has fewer steps than the previous one. The client requests the access token from the PDFfiller authorization server and includes the user’s credentials into this request.

Finally, the third type of the grant is a refresh token grant.

Refresh Token Grant

Eventually the acquired access token will expire. However, your application can receive credentials which allow getting a new access token without sending requests to the resource server. The refresh token is issued by the authorization server when the current access token expires. The refresh token is included in the process of issuing the access token.

The flow of sending requests to the authorization server is as follows:

  • grant_type with the value refresh_token
  • refresh_token with the refresh token
  • client_id with the the client’s ID
  • client_secret with the client’s secret

The authorization server responds in the following manner:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

Before choosing what grant type to use, take into account these two main factors: the type of the application (first party or third party application) and the experience you’d like for your users.

Identity Tokens

Identity tokens is a mechanism which let’s to associate any information with specific user action, such as form filling or signature. Token functionality is popular for use cases when customers would like to uniquely identify users without creating multiple accounts in PDFfiller.

Sample Token workflow

  • Execute API calls to generate unique user tokens for specific form. Submit additional user information as part of token generation request to associate user with specific token.
       Get hash value from the response 
  • Generate Fillable Form and share it by link as described in fill requests examples.
  • Send urls to your users along with associated tokens, i.e. http://pdf.ac/abcdefg?token=<token_hash>
  • Once form is filled by user, it will be associated with token and you retrieve form information along with user identification data through API to identify users:
 

        Filled document information associated with token

Signature Request

SendToSign is a powerful feature that is hosted and managed by PDFfiller. It enables you to send documents for signing and collect digital signatures in minutes. In order to control the signature workflow you can enable a signer’s authentication, turn on email notifications, request additional documents and use other options.

This table represents all the parameters used with a signature request function:

document_id (integer): ID of the document used for signature request
method(object): Signature request method. sendtoeach - a document is to be signed individually. sendtogroup - the same document is to be signed by multiple recipients [sendtoeach|sendtogroup] = ['sendtogroup', 'sendtoeach']
envelope_name (string, optional): Required for sendtogroup method. Name of the signature request envelope
security_pin (string): Generate security PIN required to open the document
= ['standard', 'enhanced']
pin(string, optional) Required if ‘security_pin’ is ‘enhanced’. Security PIN for the document
sign_in_order (boolean, optional): Required for the sendtogroup method. Determines whether request should be signed in a specific order
callback_url (string, optional): Notification from PDFfiller that the document has been signed
Recipient
email
(string): Document signer’s email. Read only field. Not used in post|put operations
name(string): Document recipient’s name
order(integer, optional): Document signing order. Required only for sendtogroup signature request method
message_subject (string): Subject of the document
message_text (string): Short message that accompanies the document
date_created (integer, optional): When the document is created
date_signed (integer, optional): When the document is signed
access(object): full - user can edit document while signing; signature - user can only add a signature;
= ['full', 'signature']
fields
(optional)
allow (Array[string], optional):
List of fields with editing access
deny(Array[string], optional):
List of fields without editing access
phone_authenticate (string, optional): Password will be sent to authenticate user before signing the document
additional_documents
(Array, optional):
document_request_notification (string, optional): Additional documents required to be attached to the signed document
require_photo (boolean, optional): Requires a recipient to enclose their photo to the signed document

The commands can be sent as POST, GET, DELETE and PUT requests.

POST /v1/signature_request

Creates a new SendToSign request. The following methods are available for this request: SendToEach and SendToGroup (“envelope_name” and “sign_in_order” must be added). Fields” parameter is available for SendToGroup method only.

Successful response status code: 200

Response example:

GET /v1/signature_request

Retrieves a list of all requests for a signature.

Response example:

GET /v1/signature_request/{signatureRequestId}

Performs signature request data retrieving according to the signature request ID. 

Response example:

Parameters:

ParameterValue DescriptionParameter TypeData Type
signatureRequestIdId Signature request IDpathlong

GET/v1/signature_request/{signatureRequestId}/certificate

Returns a signing certificate for a specific signatureRequestID. The certificate provides the information about the document, sender, recipient(s) and signing status.

To get a signature request certificate, the following parameters should be used:

ParameterValue DescriptionParameter TypeData Type
signatureRequestIdId Signature request IDpathlong

GET/v1/signature_request/{signatureRequestId}/signed_document

Returns the signed document using Signature Request ID.

To return a signed document the following parameters should be used:

ParameterValue DescriptionParameter TypeData Type
signatureRequestIdId Signature request IDpathlong

GET /v1/signature_request/{signatureRequestId}/recipient

This request allows the return of data about SendToSign recipients and status.

Response example:

To return information and status, add these parameters:

ParameterValue DescriptionParameter TypeData Type
signatureRequestIdId Signature request IDpathlong

PUT /v1/signature_request/{signatureRequestId}/recipient/{recipientId}/remind

This command will remind SendToSign recipients about a request.

Response example:

Parameters:

ParameterValueDescriptionParameter TypeData Type
recipientIdRecipient dataSignature request IDpathlong
signatureRequestIdId Signature request IDpathlong

DELETE /v1/signature_request/{signatureRequestId}

Cancels a signature request for a specific SendToSign ID.

Response example:

 

Parameters:

ParameterValue DescriptionParameter TypeData Type
signatureRequestIdId Signature request IDpathlong

GET/v1/signature_request/{signatureRequestId}/recipient/{recipientId}/additional_document 

Returns information about additional documents attached by the recipients.

Response example:

Parameters:

ParameterValueDescriptionParameter TypeData Type
recipientIdRecipient dataSignature request IDpathlong
signatureRequestIdId Signature request IDpathlong

GET /v1/signature_request/{signatureRequestId}/recipient/{recipientId}/additional_document/{additionalDocumentId} 

Returns information about the specific document attached to the SendToSign request.

Response example:

Parameters:

ParameterValueDescriptionParameter TypeData Type
recipientIdRecipient dataSignature request IDpathlong
signatureRequestIdId Signature request IDpathlong
additionalDocumentIDIdAttached additional document Id
pathlong

GET /v1/signature_request/{signatureRequestId}/recipient/{recipientId}/additional_document/{additionalDocumentId}/download

Grants the ability to download a file attached to a SendToSign request.

Parameters:

ParameterValueDescriptionParameter TypeData Type
recipientIdRecipient dataSignature request IDpathlong
signatureRequestIdId Signature request IDpathlong
additionalDocumentIDIdAttached additional document Id
pathlong

GET  /v1/signature_request/{signatureRequestId}/recipient/{recipientId}/additional_document/all/download 

Creates and downloads a zip archive of files attached to a signature request.

Parameters:

ParameterValueDescriptionParameter TypeData Type
recipientIdRecipient dataSignature request IDpathlong
signatureRequestIdId Signature request IDpathlong

Fill Request

/fill_request allows to create a fillable document and share it by link. Such fillable documents can be embedded to your site or accessed directly from PDFfiller.

POST /fill_request

Creates a fill request

Parameters

 document_id  ID of the document template for linkToFill operations
 access(optional)  Access level for the fill request document. Full – read|write|sign. Signature – read|sign  (full|signature).
 status(optional)  Document access permission. Public – open to everyone. Private – open to the document  owner only (public|private).
 email_required (optional)  Collect user email upon form completion (true|false).
 name_required (optional)  Collect user name upon form completion (true|false).
 custom_message (optional)  Message to send to user with LinkToFill request.
 allow_downloads(optional)  Allow user to download filled document upon form completion (true|false).
 redirect_url(optional)  URL to redirect user upon form completion.
 notification_emails []
 email  Email address to receive notifications of LinkToFill actions.
 name  Email recipient name.
 required_fields (optional)  Prevent closing document before filling all fields (true|false).
 custom_logo_id  Document custom logo ID.
 callback_url  Callback url to send events associated with the fill request.

GET /fill_request

Lists fill requests

GET /fill_request/{fillRequestId}

Information about created fill request

DELETE /fill_request/{fillRequestId}

Delete fill request

PUT /fill_request/{fillRequestId}

Update fill request

GET /fill_request/{fillRequestId}/filled_form

List of all completed forms for the given fill_request

GET /fill_request/{fillRequestId}/filled_form/{filledFormId}

Information about filled form

DELETE /fill_request/{fillRequestId}/filled_form/{filledFormId}

Delete filled form

GET /fill_request/{fillRequestId}/filled_form/{filledFormId}/export

Export filled form data in JSON format

GET /fill_request/{fillRequestId}/filled_form/{filledFormId}/download

Download filled PDF form

User

GET /user/me

Shows information about the user who made the request.

Token

/token is a hash which can be used to track a created fill request. Token can be added to URL to uniquely identify the document recipient. One fill request can have many tokens as they are a part of the fill request URL.

POST /token

Creates the token with custom data.

dataAny JSON data necessary to be recorded by a token which will be created in this request.

GET /token

Lists existing tokens.

GET /token/{tokenId}

Retrieves  custom data from the token.

PUT /token/{tokenId}

Updates custom token data by its identifier.

DELETE  /token/{tokenId}

Removes the token.

Callback

/callback  notifies the owner about specific actions associated with a document.

POST /callback

Registers the callback for fill of signature request by the document identifier.

event_idType of event, which must be reported by a notification. Can be either fill_request.done or signature_request.done.
callback_urlNotification URL.
document_idDocument ID of the previously created fill or signature request.

GET /callback

Lists all created callbacks.

GET /callback/{callbackId}

Retrieves information about the callback.

PUT /callback/{callbackId}

Updates the callback.

DELETE  /callback/{callbackId}

Cancels a notification about fill or signature request action

Obtain access token

When user wants to use your application you should redirect him to PDFfiller API access page https://www.pdffiller.com/en/developers/api_access?client_id=REGISTERED_CLIENT_ID&redirect_uri=REGISTERED_CALLBACK_URL

After user approved permissions to his account the PDFfiller API will send the authorization code to redirect_uri. There should be some endpoint to catch authorization code. For getting access token perform a POST request to https://api.pdffiller.com/v1/oauth/access_token
with parameters:

  • grant_type => authorization_code
  • client_id – registered application client id
  • redirect_uri – registered callback url
  • code – authorization code

Success response looks like this

 

Application

/application feature allows to create applications containing client credentials for integrating PDFfiller API into the application owner’s service. PDFfiller applications use OAuth2 protocol for authenticating users.

POST /application

Creates an application in PDFfiller.

Parameters

nameName of your application.
descriptionDescription of your application.
domainDomain is the callback URL for getting a code parameter necessary for retrieving access token.

GET /application

Lists applications.

GET /application/{applicationId}

Shows information about the created application.

DELETE /application/{applicationId}

Deletes the application.

PUT /application/{applicationId}

Updates the application.

 

Document

/document allows to manage PDFfiller documents. Once document is uploaded through API, it can be used to create signature request, fill request or perform other operations.

POST /document

Uploads a new document to your PDFfiller account.

Parameters

fileThe uploaded file can be an attachment, URL, or base64 string.

GET /document

Lists all user documents.

GET /document/{documentId}

Shows information about previously uploaded document.

DELETE /document/{documentId}

Deletes the document from user’s account.

Fillable Template

POST /fillable_template

Populates a fillable form template which was pre-created in PDFFiller fillable constructor.

document_idIdentifier of previously created document with fillable fields.
fillable_fields
key1Value which must be set for field key1.
......
keyNValue which must be set for field keyN.

GET /fillable_template/

Lists created fillable templates.

GET /fillable_template/{fillableTemplateId}

Gets information about the fillable template.

GET /fillable_template/{fillableTemplateId}/download

Downloads the filled document by its identifier.

Signature/Fill request from your website

1. Get the API KEY from “API Settings” tab in PDFfiller API page.

2. Upload a document from URL

Save ID from the JSON response for further steps

3. Create a fill_request entity based on the document uploaded in step 2

Save document_id and url element values from the JSON response.
url is a publicly accessible fillable document which you can share with others. When a document is filled out or signed by somebody, you are going to receive email notifications.
document_id is ID of a fillable form created by the fill request.

You can also register callbacks (See https://api.pdffiller.com/docs) to receive automatic REST HTTP callbacks for a document signature or filling events.

4. List all completed PDF forms for a specific document

Save id of the document item from the response

5. Download a filled PDF form

* Note, you can also attach a callback to a specific document to receive a REST call notification to a custom URL when form filling is complete.

File content will be sent back in the response body

Signature request through PDFfiller

1. Get the API KEY from “API Settings” tab in PDFfiller API page.

2. Upload a document to PDFfiller

Save document ID from the upload response
3. Send a signature request
Save signature request ID from the response

4. Check signature status

5. Download a signed document
6. Download signature request cerificate
 

Fill the fillable form

Create a fillable template through PDFfiller website

  1. Upload a PDF form to PDFFiller website to create a fillable template and to define fillable fields using Web Constructor. This tutorial describes how to use Fillable Constructor: https://www.youtube.com/watch?v=8IPMuQayKxw
  2. When a form is created, save project ID (i.e. DOCUMENT_ID) of the created fillable template:
    Click ‘More -> Project Info‘ in MyForms on PDFFiller website or request this info through the API.
  3. Now you can use FillableTemplate functionality of the API to populate this template to generate filled forms. See API call examples in the next section.

API calls to fill the fillable template

1. Get the API KEY from “API Settings” tab in PDFfiller API page.
2. Get information about fillable fields for the template

3. Fill the template form
Currently, we support these fillable fields types: Text, Number, Date, Checkbox (or RadioButton )

We use the following JSON format to fill forms:

Now you can download the generated form or use SendToSign API to send it for signature.

4. Download a filled PDF form

File content will be sent back in the response body

Embedded JS Client

Embedded JS Client allows to embed fillable documents directly to your site in an iFrame. The documentation below describes setup steps and requirements for the embedded LinkToFill flow.

Note: By default, The API app domain name in OAuth Callback Url indicates where the Client can be opened. Embedded JS Client will only works on pages from this domain.

To manually specify the domain name, please go to App Settings, scroll to the Embedded JS Client section, and type the domain name in the Access Domain URL field. You can also use the Allow All Domains checkbox to place the Embedded JS Client on any domain.

The iFrame checks that the parent window belongs to the domain associated with your app. If it does not, the PDFfiller page will show “Domain verification failed” error message in iframe.

Preliminary

Before you start doing anything, make sure the following steps have been done:

1) Create an API app for your domain (login required)

9a4da19432

2) Include JS library reference on your page:

<script src="//integrations-static.pdffiller.com/1.0/PDFfillerClient.js"></script>
3) Open the client dialog window using the following code:

PDFfiller.init({ client_id: "application-id-created-by-step-1", url: 'your-link-to-fill-url', width: '(optional) width in pixels, recommended 960', height: '(optional) height in pixels' });

client_idYour application_id from step 1
urlA LinkToFill URL you’re sending. It should be publicly accessible when you create the document.
width (optional)Recommended 960 px.
height (optional)Recommended 600 px.
Run Client