API Documentation

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

Post
https://www.fill.xyz/api/customer/v1/createDocument
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
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.		 

                {
                 "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”
               }


	            

                {
                 "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
                       }
                    ]
                 }
                }

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.

GET
https://www.fill.xyz/api/customer/v1/documentList
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 
                {
                 "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"
                    }
                 ]
                }

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

Post
https://www.fill.xyz/api/customer/v1/sendDocument/{id}
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 

                https://www.fill.xyz/api/customer/v1/sendDocument/1832
	            
                {
                 "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.

GET
https://www.fill.xyz/api/customer/v1/downloadDocument/{id}
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
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. 

	       https://www.fill.xyz/api/customer/v1/downloadDocument/1832
	            
                {
                 "status": success,
                }
	        	
              {
               "status": 0,
               "message": {
                   "title": "Oops!",
                   "desc": "No records found."
               }
             }

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

Delete document

DELETE
https://www.fill.xyz/api/customer/v1/deleteDocument/{id}
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 
	                https://www.fill.xyz/api/customer/v1/deleteDocument/1832
	            
                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": "Record successfully deleted."
                 }
               }
	        	
              {
               "status": 0,
               "message": {
                   "title": "Oops!",
                   "desc": "No document found."
               }
             }

Document Status

GET
https://www.fill.xyz/api/customer/v1/documentStatus/{id}
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 
	                https://www.fill.xyz/api/customer/v1/documentStatus/1832
	            
                {
                 "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

POST
https://www.fill.xyz/api/customer/v1/addContact
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
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.		 
                {
                "id": "85",
                "firstName": "abc",
                "lastName": "xyz",
                "jobTitle": "aaaa",
                "company": 1,
                "email": "abc@aa.aa",
                "phone": "111111"
                }
	            
                {
                 "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.

POST
https://www.fill.xyz/api/customer/v1/contactListing
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 
              {
                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.

POST
https://www.fill.xyz/api/customer/v1/templateAdd
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
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.
signerDetails 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.		 

               {
                "id":"85",
                "name":"testcopy2",
                "docKey":"a74d4ef465821ad55e0",
                "deepLink":"abcxyzmno",
                "Pages":1,
                "isBlank":0,
                "Annotations":"asasas",
                "tempType":"ada",
                "signerDetails":[{"receiverEmail":" test1@gmail.com","firstName":"Signer 1","lastName":"","sortingOrder":1}]
                }
             
                {
                 "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.

POST
https://www.fill.xyz/api/customer/v1/templateListing
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 
                {
                 "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.

GET
https://www.fill.xyz/api/customer/v1/templateDetails/{id?}
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 
               https://www.fill.xyz/api/customer/v1/templateDetails/619
             
                {
                 "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"
                 }
              }

Template Delete

This API will delete the template from your list.

GET
https://www.fill.xyz/api/customer/v1/templateDelete/{id?}
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 
               https://www.fill.xyz/api/customer/v1/templateDelete/85
             
                {
                 "status": 1,
                 "message": {
                     "title": "success",
                     "desc": "Successfully delete record."
                 }
               }