Questions? Call us now: 617-819-5274 or Chat Now

Overview

The PDFfiller API allows its users to build applications that interact with PDFfiller over the HTTP REST methods.
All API communications are SSL – encrypted and  must be made over HTTPS protocol. We recommend using SSL version higher than 3 and TLS version higher than 1.0. For authentication, we support OAuth2 authentication with password and authorization_flow grants. JSON is returned for all API responses except file downloads. PDFfiller provides API clients libraries for specific languages to help convert API objects to the language 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 features

  • /fill_request – allows users to share a document by a link, which can be seen, filled out and submitted instantly by their recipients. Such fillable documents can be embedded to your site or accessed directly from PDFfiller.
  • /signature_request – allows users to send a document for recipients’ signature. We manage 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.

 

Get Auth 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

For authentication, we support OAuth2 authorization code flow and user credentials authentication.
API authentication key can be obtained from the “API Settings” tab in PDFfiller API page.

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

"Authorization: Bearer API_KEY"

OAuth2.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

 

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

/signature_request feature is hosted and managed by PDFfiller. PDFfiller provides authentication, email notifications and offers additional features to control signature workflow.

POST /v1/signature_request

Creates new sendtosign request. The following methods are available – sendtoeach and sendtogroup (must be added “envelope_name” and “sign_in_order”. Fields are available to “sendtogroup” method only.

Success – Status 200.

Example:

 

Parameters

 document_id ID of the document used for signature request.
 method Signature request method. sendtoeach -a document is to be signed individually.  sendtogroup – the same document is to be signed by multiple recipients. [sendtoeach|sendtogroup]
 envelope_name (optional) Name of the signature request. Used only with sendtogroup method.
 security_pin (optional) Security PIN required to open the document. Used only with sendtogroup method. [standard|enhanced]
 sign_in_order (optional) Request to sign in specific order. Used only with sendtogroup method.
 recipients []
 email Email address of the document recipient.
 name Document recipient’s name.
 order Document signing order. Required only when signature request method is sendtogroup
 message_subject
 message_text
 access full – edit and sign. signature – signature only. [full, signature]
 additional_documents[] (optional) Additional documents required to be attached to the signed document.
 require_photo (optional) Requires a recipient to enclose their picture to the signed document.

GET /v1/signature_request

Will retrieve a list of all document signature requests

Success – list of document signature requests was successfull retrieved

 

To retrieve list of signatures, you must insert access token to “Authorization” field.

ParameterValue
AuthorizationYour token

GET /v1/signature_request/{signatureRequestId}

Perform signature request data retrieving according signature request ID.

Success is status 200.

Example:

To retrieve data about signature request, must be placed such parameters: access token and signatureRequestID.

ParameterValue DescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
signatureRequestIdId Signature request IDpathlong

GET/v1/signature_request/{signatureRequestId}/certificate

Returning of signature request certificate by signatureRequestID.

Success is status 200 and certificate.

Example:

To get  signature request certificate, must be placed such parameters: access token and signatureRequestID.

ParameterValue DescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
signatureRequestIdId Signature request IDpathlong

GET/v1/signature_request/{signatureRequestId}/signed_document

Performs returning of signed document with using signatureRequestID

Success is status 200 and returned signed document.

Model:

To return signed document, must be placed such parameters: access token and signatureRequestID.

ParameterValue DescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
signatureRequestIdId Signature request IDpathlong

GET /v1/signature_request/{signatureRequestId}/recipient

Allow to return data about sendtosign recipients and status.

Success is status 200 and information about recipients.

Example:

 

To return information and status, must be placed such parameters: access token and signatureRequestID.

ParameterValue DescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
signatureRequestIdId Signature request IDpathlong

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

This feature allows to remind sendtosign recipient about request.

Success is status 200 and confirmation that recipient got reminder.

Example:

To remind about sendtosign request and status, must be placed such parameters: access token, recipientID and signatureRequestID.

 
ParameterValueDescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
recipientIdRecipient data Signature request Idpathlong
signatureRequestIdId Signature request IDpathlong

DELETE /v1/signature_request/{signatureRequestId}

Cancel request of signature for specific sendtosign ID

Success is status 200.

Example:

To remove signature request, must be placed such parameters: access token and signatureRequestID.

ParameterValue DescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
signatureRequestIdId Signature request IDpathlong

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

Returns information about attached additional documents.

Success is status 200 and data about attached documents.

Example:

To get information about attached documents, must be placed such parameters: access token, recipientID and signatureRequestID.

ParameterValueDescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
recipientIdRecipient data Signature request Idpathlong
signatureRequestIdId Signature request IDpathlong

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

Returns information about specific document, attached to sendtosign request.

Success is status 200 and data bout attached document.

Example:

To get info about specific document, you must place such data: access token, recipientID, additionalDocumentID and signatureRequestID.

ParameterValueDescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
recipientIdRecipient data Signature request Idpathlong
signatureRequestIdId Signature request IDpathlong
additionalDocumentIDId

Attached additional document Id
pathlong

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

Grants ability to download a file of sendtosign request.

To download specific dodcument, you must place such data: access token, recipientID, additionalDocumentID and signatureRequestID.

ParameterValueDescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
recipientIdRecipient data Signature request Idpathlong
signatureRequestIdId Signature request IDpathlong
additionalDocumentIDId

Attached additional document Id
pathlong

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

Allows downloading of zip archive from sendtosign request.

To download archive from request, you must place such data: : access token, recipientID and signatureRequestID.

ParameterValueDescriptionParameter TypeData Type
AuthorizationYour tokenBearer Access Token obtained from client credentialsheaderstring
recipientIdRecipient data Signature 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