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 an SSL version higher than 3 and a 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 client libraries for specific languages to help convert API objects to the language format.

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

Quickstart

These guides have been designed to demonstrate the advantages of integrating PDFfiller endpoints in three simple steps:

• Step One – Authentication

• Step Two – Document Creation

• Step Three – Endpoint Utilization

  • Fillable Template
  • LinkToFill
  • SendToSign

For the purposes of these guides, we will utilize standard parameter settings so that you can begin implementing the best solution for your documentation needs in as little time as possible.

Authentication

Whether you want to create, upload, sign, or send a document, you'll need an access token to utilize PDFfiller's API.

Step One – Retrieve your API Key:

Login to your PDFfiller account and Navigate to: https://developers.pdffiller.com Select the “API Settings” Tab and copy your API Key

Step Two – Create a Document Template or Upload a Document:

A – Create a Document Template

Navigate to our API Documentation and select 'Document' in the reference section on the left. Click the 'Create a new document template' bar. Then, in the developer console on the right, select 'Switch to Console'. Now your screen should match the image below: Click the 'Headers' submenu of the developer's console, under the 'Authorization' field, replace the 'AccessToken' text with your API key. Click the 'URI Parameters' submenu and select “Add a new query parameter”. Replace the 'New item' text with 'file'. Then replace the 'null' text with the URL of your document (.pdf). Upload the document of your choice via url. For the purposes of this guide, we will use a blank NDA form. Paste the URL into the field and change 'null' to 'file'. Now click the 'Call Resource' button. Scroll down in the console to confirm the operation completed successfully. A 200 response indicates that your document request was successful.

B – Upload a Document Template via URL or local disk

Upload a file from your computer:

curl -X "POST" "https://api.pdffiller.com/v1/document" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -F "file=@/path/to/file.pdf"

Upload a file via URL:

curl -X "POST" "https://api.pdffiller.com/v1/document" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json" \
     -d "{\"file\":\"http://site.com/file.pdf\"}"

A success response from the API will contain information about the created document template:

{
  "id": 1111111,
  "name": "file.pdf",
  "type": "pdf",
  "created": 1457373425
}

Endpoint Utilization

Step Three – Choose Your Endpoint:

Create a Fillable Template

Create a LinkToFill Document

Create a SendToSign Document

Fillable Template – Creating and Sending Your Fillable Document

Now that you've created a document to be filled, you'll want to send it out. To do this, scroll down to the 'Body' section at the bottom of the console to retrieve your document id and copy it to your clipboard: Open a new tab in your internet browser and proceed to your MyBox at https://www.pdffiller.com/en/forms.htm where you should find your newly imported NDA form. To begin adding fillable fields to the form, click on the green 'Add Fillable Fields' tab located in the upper-right of the PDFfiller interface: Now that you've finished adding your desired fillable fields, copy the new document id located in the address bar: For every fillable field you add, you'll need to assign a field name which will be noted when sharing the document. To do this, click on the fillable field you wish to name and under the 'Add Fillable Fields' tab, select 'Advanced' and scroll to the 'Database Field Name' bar: Populating the 'Body' field: Switch back to the PDFfiller API tab and add the fillable fields with their Database Field Names to the 'Body' field with the text you would like to populate the fillable field with, for example: Scroll down in the console to confirm the operation completed successfully. A 200 response indicates that your document request was successful. Now switch back to 'MyBox' at your PDFfiller tab and confirm that your desired fields were completed in your updated document: See the LinkToFill or SendToSign quickstart guides for distributing Fillable Forms to your recipients.

LinkToFill – Sharing Your Fillable Document

Now that you've created a document to be filled, you'll want to send it out. To do this, scroll down to the 'Body' section at the bottom of the console to retrieve your document id and copy it to your clipboard: With your document id and API Key, select 'LinkToFill' in the reference section on the left. Then click on 'Creates a new document and shares it via short url'. Click the 'Headers' submenu in the developer's console and under the 'Authorization' field, replace the 'AccessToken' text with your API key. Click the 'Body' submenu and paste your document id over the existing number: Delete all of the other text so that only your document id information remains. Click the 'Call Resource' button. Scroll down in the console to confirm the operation completed successfully. A 200 response indicates that your document request was successful. Scroll to the bottom of the console to fetch your document's shareable URL: You now have a link to your fillable document which may be used to share with your recipients.

SendToSign – Send Your Recipients a Signature Request

Now that you've created a document to be signed, you'll want to send it out. To do this, scroll down to the 'Body' section at the bottom of the console to retrieve your document id and copy it to your clipboard: With your document id and API Key, select 'Signature' in the reference section on the left. Then click on 'Create new sendtosign request'. Click the 'Headers' submenu in the developer's console and under the 'Authorization' field, replace the 'AccessToken' text with your API key. SendToSign supports two signature request methods:

• sendtoeach – a document is to be signed individually.

• sendtogroup – a document is to be signed by multiple recipients.

Whichever method you choose, it will be necessary to modify the field properties.

A. SendToEach:

For 'sendtoeach' you'll need to modify the body field properties (using the below example). Be sure to edit the fields highlighted in yellow with your own credentials:

{
  "document_id": 123456789,
  "method": "sendtoeach",
  "security_pin": "standard",
  "sign_in_order": false,
  "recipients": [
    {
      "email": "john@email.com",
      "name": "John",
      "order": 1,
      "message_subject": "Digital signature request from API Testing Letter",
      "message_text": "Please sign and return the linked document with PDFfiller",
      "date_created": 0,
      "date_signed": 0,
      "access": "signature"
    }
  ]
}

Scroll down in the console to confirm the operation completed successfully. A 200 response indicates that your document request was successful.

B. SendToGroup:

For 'sendtogroup' you'll need to modify the body field properties (using the below example – contains two recipients). Be sure to edit the fields highlighted in yellow with your own credentials:

{
  "document_id": 123456789,
  "method": "sendtogroup",
  "envelope_name": "EnvelopeAPI",
  "security_pin": "standard",
  "sign_in_order": true,
  "recipients": [
    {
      "email": "john@email.com",
      "name": "John",
      "order": 1,
      "message_subject": "Digital signature request from API Testing Letter",
      "message_text": "Please sign and return the linked document with PDFfiller",
      "date_created": 0,
      "date_signed": 0,
      "access": "signature"
    },
    {
      "email": "jane@email.com",
      "name": "Jane",
      "order": 2,
      "message_subject": "Digital signature request from API Testing Letter",
      "message_text": "Please sign and return the linked document with PDFfiller",
      "date_created": 0,
      "date_signed": 0,
      "access": "full"
    }
  ]
}

Scroll down in the console to confirm the operation completed successfully. A 200 response indicates that your document request was successful.

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

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:

https://developers.pdffiller.com/api_access?client_id=<client_id>&redirect_uri=<redirect_url>

Users will be asked to login to PDFfiller if needed. Following authorization dialog will be presented to user: When AUTHORIZE button clicked, user redirected to REDIRECT_URL from application setup with issued authorization_code :

https://REDIRECT_URL/?code=<authorization_code>&uri=https://api.pdffiller.com

Step3 – Obtain Access Token

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

curl -X "POST" "https://api.pdffiller.com/v1/oauth/access_token" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "{
           \"grant_type\":\"authorization_code\",
           \"code\":\"<your code>\",
           \"client_id\":\"<your client id>\",
           \"client_secret\":\"<your client secret>\",
           \"redirect_uri\":\"http://example.com/token\"
         }"

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:

Step 1

The application redirects the user to https://developers.pdffiller.com/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.

Examples

Signature request through PDFfiller

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

2. Upload a document to PDFfiller

curl -X "POST" "https://api.pdffiller.com/v1/document" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -F "file=@/path/to/file.pdf"

Save document ID from the upload response

{
  "id": 1111111,
  "name": "file.pdf",
  "type": "pdf",
  "created": 1457373425
}

3. Send a signature request

{
  "method": "sendtoeach",
  "document_id": DOCUMENT_ID_FROM_STEP_2,
  "security_pin": "standard",
  "recipients": [
    {
      "email": "jdoe@pdffiller.com",
      "name": "john",
      "message_subject": "Digital signature request from API Testing Letter",
      "message_text": "Please sign and return the linked document with PDFfiller",
      "access": "full",
      "require_photo": false
    }
  ]
}

|    curl https://api.pdffiller.com/v1/signature_request \
          -i \
          -H "Authorization: Bearer API_KEY_FROM_STEP1" \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d @- \
          -X POST

Save signature request ID from the response

4. Check signature status

curl -X "GET" "https://api.pdffiller.com/v1/signature_request/SIGNATURE_REQUEST_ID_FROM_STEP_3 \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json"

5. Download a signed document

curl -X "GET" "https://api.pdffiller.com/v1/signature_request/SIGNATURE_REQUEST_ID_FROM_STEP_3/signed_document \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" -o file.pdf

6. Download signature request cerificate

curl -X "GET" "https://api.pdffiller.com/v1/signature_request/SIGNATURE_REQUEST_ID_FROM_STEP_3/certificate \
     -H "Authorization: Bearer ACCESS_TOKEN_FROM_STEP2" -o file.pdf

Fill request from your website

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

2. Upload a document from URL

curl -X "POST" "https://api.pdffiller.com/v1/document" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json" \
     -d "{\"file\":\"https://some.url/somefile.pdf\"}"

Save ID from the JSON response for further steps

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

curl -X "POST" "https://api.pdffiller.com/v1/fill_request" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json" \
     -d "{\"document_id\":\"DOCUMENT_ID_FROM_STEP2\",\"access\":\"full\",\"status\":\"public\"}"

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 to receive automatic REST HTTP callbacks for a document signature or filling events.

4. List all completed PDF forms for a specific document

curl -X "GET" "https://api.pdffiller.com/v1/fill_request/DOCUMENT_ID_FROM_STEP3/filled_form" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json"

Save id of the document item from the response

{
  "items": [
    {
      "id": 56900,
      …
    }
  ]
}

5. Download a filled PDF form

curl -X "GET" "https://api.pdffiller.com/v1/fill_request/DOCUMENT_ID_FROM_STEP3/filled_form/ID_FROM_STEP4/download" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1"

*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

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

curl -X "GET" "https://api.pdffiller.com/v1/fillable_template/DOCUMENT_ID" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1"

3. Fill the template form

curl -X "POST" "https://api.pdffiller.com/v1/fillable_template" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1" \
     -H "Content-Type: application/json"

Currently, we support these fillable fields types: Text, Number, Date, Checkbox (or RadioButton ) We use the following JSON format to fill forms:

{
  "document_id": "DOCUMENT_ID",
  "fillable_fields": {
    "FIELD_NAME_1": "FIELD_VALUE_1",
    "FIELD_NAME_2": "FIELD_VALUE_2",
    "FIELD_NAME_N": "FIELD_VALUE_N"
  }
}

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

4. Download a filled PDF form

curl -X "GET" "https://api.pdffiller.com/v1/fillable_template/48250746/download" \
     -H "Authorization: Bearer API_KEY_FROM_STEP1"

File content will be sent back in the response body

API client libraries

PHP: https://github.com/pdffiller/pdffiller-php-api-client

Java: https://github.com/pdffiller/pdffiller-java-api-client

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)
2. Include JS library reference on your page:

<script src="//integrations-static.pdffiller.com/1.0.3/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, recommended 600",
    events: {
            opened: function () {
                //Function triggers when iframe is opened
            },
            error: function () {
                //Function triggers if error occured
            },
            closed: function () {
                //Function triggers when iframe is closed
            },
            completed: function () {
                //Function triggers when LinkToFill form is filled
            },
            in_progress: function () {
                //Function triggers when editor starts loading
            }
        }
});

parameters	info
client_id	Your application_id from step 1
url	A 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
events.opened	Function triggers when iframe is opened
events.closed	Function triggers when iframe is closed
events.error	Function triggers if error occured
events.completed	Function triggers when LinkToFill form is filled
events.in_progress	Function triggers when editor starts loading