Introduction

All calls to the Fill API should be made to https://www.fill.xyz/api/customer/v1, which remains current with the latest minor updates. For most calls, you will need to pass in your API key as parameters. You can find your API key on the “Settings” page of your dashboard. In fill, there are two types of credentials: Live and Test.

If you make an API call with a Live key, your balance will decrease if you perform operations that cost money (e.g. you request a document for signing). However, if you make calls with test keys, the Fill system will simulate documents being sent or received and your balance will not be affected.

All fill API responses are formatted in JSON. Need an XML response? Too bad. JSON is awesome! Click here to learn more about it.

HTTP Methods

Since our API is RESTful, each API call requires a specific HTTP method to indicate the type of operation to be performed. The method only has to be specified when interacting with the fill API at the HTTP level, such as when using curl:

	            	curl -X POST https://www.fill.xyz/api/customer/v1/createDocument\
-H 'accessToken:API_KEY'

Method Simulation

Some HTTP clients don’t support all HTTP methods. In such cases, the POST method can be used, with the method for the API call passed in the _method parameter:

	              curl https://www.fill.xyz/api/customer/v1/createDocument
-F '_method=POST' \
-H 'accessToken:API_KEY'

Authentication

Most API calls require authentication. The client libraries have built-in authentication handling, which will automatically authenticate each request when properly initialized.

HTTP Authentication

HTTP authentication may be used simply by using the API key. For example:

	              		cURL
curl https://www.fill.xyz/api/customer/v1/templateListing \
-H 'accessToken:API_KEY'

Formats

By default, all API calls return a JSON response. Click here to learn more.

Objects

Fill object

The fill object is a JSON object returned by the Fill API and represents a document fill job in the system. Its properties are described in the table below.

Name	Description
id	A unique ID is generated for each document created through the API. This can be used to retrieve the document, document status, send a document or delete a sent document.
name	A name of the document which appears on the sender and receiver side.
templateId	Id of the template which was used to create a request signature document.
isSortingOrder	It sets the order to send sign document mail based on the sorting order we set for signers(receivers).
message	A default message has already been set which we can change too.
docType	A document type is defined as which type of document we are creating for a sign. (e.g. Account payables, Application forms)
dueDate	A timeline to complete the document from the signer's side.
ccmail	The total number of people we need to keep in the thread for the document sign process.
pages	The parameter’s value should be in number format. It represents the no. Of pages in the document.

Example Fill Object

        {
  	   	"id": 12345,
  	   	"name": "Sample try it",
  	   	"templateId": 173,
  	   	"isSortingOrder": 1,
  	   	"message": “Please sign the document”,
  	   	"docType": “Account Playable”,
  	   	"dueDate": "145256398855",
  	   	"ccmail": "abc@gmail.com,xyz@gmail.com",
	    "pages": 10
        }

Webhooks

Webhooks allow Fill to update you in real-time about the status of your documents. Webhooks are triggered by events such as the completion of a document and transmit information about the state of that document to you via HTTP(S).

Specifying Webhook URLs

The first thing we need to send you a webhook is a destination URL. This should be a valid URI with an http, https scheme that points to a destination that you control. An example of a valid webhook URL is https://www.example.com/fill_webhook

For sent and received documents, you can set global webhook URLs on your webhook settings page. These apply to all documents on your Fill Account.

Specifying a Webhook Version

Coming Soon

Document status

Will receive the following possible status in API responses

Name	Description
Pending	The document is created and sent to signers (recipients).
Viewed	The document has been opened by the recipients.
Overdue	Document due date passed and the document has not yet been completed.
My Signature Required	User needs to sign the document.
Completed	The document has been completed by all the parties (recipients).

Error Messages

Error Code	Message
1	For the success of the API response.
0	For the failure of the API with the respective error message.

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred on client’s part

5XX - Error occurred on server’s part

Error Code	Message
100	Continue
101	Switching Protocol
200	OK
201	Created
202	Accepted
203	Non-Authoritative Information
204	No Content
205	Reset Content
206	Partial Content
300	Multiple Choices
301	Moved Permanently
302	Found
303	See Other
304	Not Modified
305	Use Proxy
307	Temporary Redirect
-400	Bad Request
401	Unauthorized
402	Payment Required
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
407	Proxy Authentication Required
408	Request Timeout
409	Conflict
410	Gone
411	Length Required
412	Precondition Failed
413	Request Entity Too Large
414	Request-URI Too Large
415	Unsupported Media Large
416	Requested Range Not Satisfiable
417	Expectation Failed
422	Unprocessable Entity
429	Too Many Request
500	Internal Server Error
501	Not Implemented
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout
505	HTTP Version Not Supported

Create Document

This API will be used to create the document to receive for taking a signature of them. You need to pass the PDF file in base64 encoded format as a parameter and other required parameters to send the document.

Method: Post

Path: https://www.fill.xyz/api/customer/v1/createDocument

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	The API key will be unique for all users. It is available on the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
name	String	The name of the document name which displays to the receiver. This is a required field.
pages	Integer	The parameter’s value should be in number format. It represents the no. Of pages in the document. This is a required field.
docType	String	The parameter’s value should be passed in string format. It represents the document type. This field is required.
recipients	String	The parameters value should be passed in string format but the value of it should be an array object. This field is required.
dueDate	Date	The parameter’s value should be passed in date format. This field is required.
ccmail	String	The parameter’s value should be passed in string format. This is an optional value.
message	String	The parameter’s value should be passed in string format. The message owner needs to set for the receiver. This is an optional value.
isSignOrder	Boolean	The parameter’s value should be passed in boolean format. The default value will be 0. If you need to send documents by mail in orders then pass 1. This is an optional value.
templateId	Number	The parameter’s value should be in number format. When using a template for signature, pass the templateId. This is an optional value.
file	String	The parameter’s value should be passed in string format. This is a pdf file with based64 encoded content. This is a required field.

Sample Request Postman reference


                {
                 "name":"fw4",
                 "Pages":4,
                 "docType":"Accounts Payable",
                 "recipients":[
                    {
                       "email":"abc@gmail.com",
                       "firstName":"abc",
                       "lastName":"test",
                       "signingOrder":1
                    },
                    {
                       "email":"xyz@gmail.com",
                       "firstName":"xyz",
                       "lastName":"test",
                       "signingOrder":2
                    }
                 ],
                 "dueDate":"2021-12-31",
                 "ccmail":"ab@de.uk, de@jd.ui",
                 "message":"Message content",
                 "isSignOrder":1,
                 "templateId":11,
                 "file":“PDF based64 encoded content”,
                 "variables": [
                 {
                 	"id": "a7e30c10-3d6b-4f9f-8426-483aea8410f1",
                 	"name": "Date",
                 	"value": "2024-05-30"
                 },
                 {
                 	"id": "9baf37ef-9555-429a-9d93-d6a59c671ff5",
                 	"name": "Disclosing Party Name",
                 	"value": "test party name"
                 },
                 {
                 	"id": "6761b7f2-d027-4427-a8a7-1cf5e2358edc",
                 	"name": "Disclosing Party Address",
                 	"value": "test disclosing"
                 },
                 {
                 	"id": "e803a926-a91f-42c8-83d5-12f616626ab4",
                 	"name": "Purpose",
                 	"value": "test Purpose"
                 },
                 {
                 	"id": "1f632813-716d-4ba4-a7be-654416928a92",
                 	"name": "End Date",
                 	"value": "2024-06-25"
                 },
                 {
                 	"id": "05fd7962-4995-4890-8873-dbda481c3a17",
                 	"name": "Number",
                 	"value": "123456"
                 },
                 {
                 	"id": "01702627-f631-4497-a638-64cf7f09b24f",
                 	"name": "State",
                 	"value": "test state"
                 },
                 {
                 	"id": "b371c37c-de1f-438f-a7eb-60f2ede93f69",
                 	"name": "Disclosing Party Name",
                 	"value": "test disclosing"
                 },
                 {
                 	"id": "2da4df3c-0bad-4d23-9859-5611a5408fb2",
                 	"name": "Disclosing Party Representative Name",
                 	"value": "test Representative"
                 },
                 {
                 	"id": "a5589725-f16b-45b9-8563-3149db9064ba",
                 	"name": "Disclosing Party Representative Title",
                 	"value": "test Representative"
                 }
                 ]
               }

Sample Response


                {
                 "status":1,
                 "message":{
                    "title":"success",
                    "desc":""
                 },
                 "data":{
                    "id":5869,
                    "name":"fw4",
                    "type":"requestSignature",
                    "shareDocumentId":"5889",
                    "docKey":"81s2e7r51abe48r2b72b5uf9bdb18ea3",
                    "sharedUrl":"https://fill.page.link/WwmcsfhsdrtqwVro6",
                    "pages":0,
                    "isOwner":1,
                    "dueDate":"2021-12-24",
                    "recipient":[
                       {
                          "receiverEmail":"abc@gmail.com",
                          "firstName":"abc",
                          "lastName":"test",
                          "sortingOrder":1
                       },
                       {
                          "receiverEmail":"xyz@gmail.com",
                          "firstName":"xyz",
                          "lastName":"test",
                          "sortingOrder":2
                       }
                    ]
                 }
                }

Restrictions

Fill places some restrictions on the request document size and document page length in order to ensure timely processing of your documents and to ensure a high-performance rate.

The total request document size for sending a document may not exceed 20MB.
The total request document size of pages for any document may not exceed 100 pages.
The required fields validations for mandatory fields.
A maximum of 3 recipients may be submitted per document.

Document Listing

Here you will get all the documents that are sent to other receivers.

Method: GET

Path: https://www.fill.xyz/api/customer/v1/documentList

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Response

                {
                 "status":1,
                 "message":{
                    "title":"success",
                    "desc":""
                 },
                 "data":[
                    {
                       "id":1863,
                       "name":"Test abc xyz",
                       "status":"viewed",
                       "dateCreated":"2021-10-27 10:34:10",
                       "dateModified":"2021-10-27 10:34:10",
                       "expirationDate":"2021-11-01",
                       "version":"1"
                    }
                 ]
                }

Response

A JSON object with status, message, and data attributes. The data attribute contains one array of object data, which are the no. Of documents list.

Send Document

Method: Post

Path: https://www.fill.xyz/api/customer/v1/sendDocument/{id}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The parameters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Request Postman reference


                https://www.fill.xyz/api/customer/v1/sendDocument/1832

Sample Response

                {
                 "status":1,
                 "message":{
                    "title":"success",
                    "desc":""
                 },
                 "data":{
                        "id":"1832",
                        "name":"fw4",
                        "status":"sent",
                        "dateCreated":"2021-10-27 10:05:30",
                        "dateModified":"2021-10-27 10:05:30",
                        "expirationDate":null,
                        "version":"1"
                     }
                }

                {
                 "status":0,
                 "message":{
                    "title":"Oops!",
                    "desc":"No records found."
                 }
              }

              {
               "status": 0,
               "message": {
                   "title": "Oops!",
                   "desc": "Required id parameter"
               }
            }

Download Document

This API will download the document.

Method: GET

Path: https://www.fill.xyz/api/customer/v1/downloadDocument/{id}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
{id}	Integer	It is a unique id that you will get from the document listing. These query parameters need to pass in the given URL.

Sample Request Postman reference


	       https://www.fill.xyz/api/customer/v1/downloadDocument/1832

Sample Response

                {
                 "status": success,
                }

              {
               "status": 0,
               "message": {
                   "title": "Oops!",
                   "desc": "No records found."
               }
             }

            {
             "status": 0,
             "message": {
                 "title": "Oops!",
                 "desc": "Required id parameter"
             }
           }

Delete document

Method: DELETE

Path: https://www.fill.xyz/api/customer/v1/deleteDocument/{id}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Request Postman reference

	                https://www.fill.xyz/api/customer/v1/deleteDocument/1832

Sample Response

                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": "Record successfully deleted."
                 }
               }

              {
               "status": 0,
               "message": {
                   "title": "Oops!",
                   "desc": "No document found."
               }
             }

Document Status

Method: GET

Path: https://www.fill.xyz/api/customer/v1/documentStatus/{id}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Request Postman reference

	                https://www.fill.xyz/api/customer/v1/documentStatus/1832

Sample Response

                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": ""
                 },
                 "data": [
                     {
                         "id": 1832,
                         "name": "Test sfdfdf",
                         "status": "completed",
                         "dateCreated": "2021-10-27 10:11:09",
                         "dateModified": "2021-10-27 10:11:13",
                         "expirationDate": "2021-11-01",
                         "version": "1"
                     }
                 ]
              }

Create Contact

This API is used to add new contacts

Method: POST

Path: https://www.fill.xyz/api/customer/v1/addContact

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
firstName	String	The parameters should be in string format. This field is required.
lastName	String	The parameters should be in string format. This field is required.
jobTitle	String	The parameters should be in string format. This field is required.
comapny	String	The parameters should be in string format. This field is required.
email	String	The parameters should be in string format. This email address will be used to send documents in request signature. This field is required.
phone	String	The parameter should be in string format. The phone number needs to pass with the country code. This is not a required field.
id	Integer	Need to pass an ID to update the document. This is not a required field.

Sample Request Postman reference

                {
                "id": "85",
                "firstName": "abc",
                "lastName": "xyz",
                "jobTitle": "aaaa",
                "company": 1,
                "email": "abc@aa.aa",
                "phone": "111111"
                }

Sample Response

                {
                 "status": 1,
                 "message": {
                     "title": "Success",
                     "desc": "Contact has been saved successfully"
                 },
                 "data": {
                     "id": 85,
                     "firstName": "test",
                     "lastName": "test",
                     "company": 1,
                     "jobTitle": "aaaa",
                     "email": "aaa2@yop.aa",
                     "phone": "1212111",
                     "isActive": "1",
                     "createdBy": 143
                 }
              }

Contact Listing

This API is used to get all the contacts added.

Method: POST

Path: https://www.fill.xyz/api/customer/v1/contactListing

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Response

              {
                status": 1,
                "message": {
                    "title": "Success",
                    "desc": ""
                },
                "data": {
                        "id": 1,
                        "firstName": "dsf",
                        "lastName": "dsf",
                        "company": "",
                        "jobTitle": "",
                        "email": "james55@gmail.com",
                        "profileImg": null,
                        "phone": "",
                        "createdAt": "2021-10-18 04:25:35",
                        "createdBy": 2,
                        "isActive": 1,
                        "isFavorite": null
                    }
             }

Create Template

This API is used to add new templates. Templates can be sent and reused to request signatures. Templates must be a PDF file in base64 encoded format.

Method: POST

Path: https://www.fill.xyz/api/customer/v1/templateAdd

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
name	String	The parameter’s value should be in string format. This field is required.
docKey	String	The parameter’s value should be in string format. A unique 32 length key is defined as a template key that is used to create a template. This field is required.
pages	Integer	The parameter’s value should be in integer format. This field is required.
file	String	The parameter’s value should be passed in string format. This is a pdf file with based64 encoded content. This field is required.
tempType	String	The parameter’s value should be passed in string format. This field is required.
signerRoles	String	At least, one signer details need to be added. This is a required field.
id	Integer	Need to pass this field for when need to update the template details. This is not a required field.

Sample Request Postman reference


               {
                "id":"85",
                "name":"testcopy2",
                "docKey":"a74d4ef465821ad55e0",
                "deepLink":"abcxyzmno",
                "Pages":1,
                "isBlank":0,
                "Annotations":"asasas",
                "tempType":"ada",
                "signerRoles":["Signer1","Signer2","Signer3"]
                }

Sample Response

                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": "Template Created Successfully!"
                 },
                 "data": {
                     "id": 85,
                     "name": "test",
                     "docKey": "test123",
                     "pages": 1,
                     "tempType": "test",
                     "annotations": "test",
                     "uploadedBy": "api"
                 }
              }

Template Listing

This API will give you a list of templates that you have added.

Method: POST

Path: https://www.fill.xyz/api/customer/v1/templateListing

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Response

                {
                 "status": 1,
                 "data": {
                         "id": 284,
                         "name": "Sample - Try It!",
                         "docKey": "517357ce080a45ceb3d82d50b35fbda6",
                         "sent": "0",
                         "completed": "0",
                         "conversion": 0,
                         "industryRate": 41.67,
                         "lastUpdatedDate": 1635326617,
                         "pages": 2,
                         "tempType": "Adhesion Agreement",
                         "signerDetails": "[{\"receiverEmail\":\"\",\"firstName\":\"Signer   1\",\"lastName\":\"\",\"sortingOrder\":1},{\"receiverEmail\":\"\",\"firstName\":\"Signer 2\",\"lastName\":\"\",\"sortingOrder\":2}]",
                         "isBlank": 1,
                         "annotations": "[{\"fields\":[{\"DA\":\"0 0 0 rg\\nF0 0 Tf\\n\",\"widget_type\":\"Tx\",\"tl\":[34.4653,153.021],\"br\":[579.Tf\\n\",\}],\"beads\":null,\"lastmod\":null,\"rotate\":0,\"pagenum\":1,\"height\":841.64,\"width\":595}]"
                     }
              }

Template Details

This API will give you particular template details.

Method: GET

Path: https://www.fill.xyz/api/customer/v1/templateDetails/{id?}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Request Postman reference

               https://www.fill.xyz/api/customer/v1/templateDetails/619

Sample Response

                {
                 "status": 1,
                 "data": {
                     "id": 619,
                     "name": "bbagb",
                     "docKey": "bb",
                     "sent": "0",
                     "completed": "0",
                     "conversion": 0,
                     "industryRate": 0,
                     "lastUpdatedDate": 1636697690,
                     "pages": "0",
                     "tempType": "ada",
                     "signerDetails": "[{\"receiverEmail\":\"ada@ad.gh\",\"firstName\":\"adad\",\"lastName\":\"ada\",\"sortingOrder\":2},{\"receiverEmail\":\"ada@ada.gh\",\"firstName\":\"asf\",\"lastName\":\"dad\",\"sortingOrder\":1},{\"receiverEmail\":\"aa@aa.aa\",\"firstName\":\"asf\",\"lastName\":\"ada\",\"sortingOrder\":3}]",
                     "isBlank": 0,
                     "annotations": "asasas",
                     "variables": [
                     {
                     	"id": "a7e30c10-3d6b-4f9f-8426-483aea8410f1",
                     	"name": "Date"
                     },
                     {
                     	"id": "9baf37ef-9555-429a-9d93-d6a59c671ff5",
                     	"name": "Disclosing Party Name"
                     },
                     {
                     	"id": "6761b7f2-d027-4427-a8a7-1cf5e2358edc",
                     	"name": "Disclosing Party Address"
                     },
                     {
                     	"id": "e803a926-a91f-42c8-83d5-12f616626ab4",
                     	"name": "Purpose"
                     },
                     {
                     	"id": "1f632813-716d-4ba4-a7be-654416928a92",
                     	"name": "End Date"
                     },
                     {
                     	"id": "05fd7962-4995-4890-8873-dbda481c3a17",
                     	"name": "Number"
                     },
                     {
                     	"id": "01702627-f631-4497-a638-64cf7f09b24f",
                     	"name": "State"
                     },
                     {
                     	"id": "b371c37c-de1f-438f-a7eb-60f2ede93f69",
                     	"name": "Disclosing Party Name"
                     },
                     {
                     	"id": "2da4df3c-0bad-4d23-9859-5611a5408fb2",
                     	"name": "Disclosing Party Representative Name"
                     },
                     {
                     	"id": "a5589725-f16b-45b9-8563-3149db9064ba",
                     	"name": "Disclosing Party Representative Title"
                     }
						        ]
                 }
              }

Template Delete

This API will delete the template from your list.

Method: GET

Path: https://www.fill.xyz/api/customer/v1/templateDelete/{id?}

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Sample Request Postman reference

               https://www.fill.xyz/api/customer/v1/templateDelete/85

Sample Response

                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": "Successfully delete record."
                 }
               }

API Documentation

Introduction

HTTP Methods

Method Simulation

Authentication

HTTP Authentication

Formats

Objects

Fill object

Webhooks

Specifying Webhook URLs

Specifying a Webhook Version

Document status

Error Messages

Create Document

Document Listing

Send Document

Download Document

Delete document

Document Status

Create Contact

Contact Listing

Create Template

Template Listing

Template Details

Template Delete