1. API Endpoints - signeasy/API GitHub Wiki

API Base URL

Base URL for all your API calls would be https://api-ext.getsigneasy.com/v1/

User APIs

End Point	Description
GET /user/	Fetch user information - name, email, account type and other user specific details
POST /user/	Create a new SignEasy user account

File APIs

End point	Description
GET /files/	Fetch all kinds of documents in the user's account

Original Documents

End point	Description
GET /files/original/	Fetch all the original documents of the user
GET /files/original/<:id>/	Retrieve a specific original document with id
GET /files/original/<:id>/download/	Download an original document with id
POST /files/original/	Import or upload a new original document
PUT /files/original/<:id>/	Rename an original document
DELETE /files/original/<:id>/	Delete an original document forever

Completed Documents

End point	Description
GET /files/signed/	Fetch all the signed documents of the user
GET /files/signed/<:id>/	Retrieve a specific signed or completed document with id
GET /files/signed/<:id>/download/	Download a completed document with id
PUT /files/signed/<:id>/	Rename a completed document
DELETE /files/signed/<:id>/	Delete a completed document forever
GET /audit-trail/<:id>/	Get Audit trail of a completed document

Pending Documents (Request Signatures)

End point	Description
GET /files/pending/	Fetch all pending documents of the user
GET /files/pending/<:id>/	Retrieve a specific pending document with id
POST /files/pending/	Initiate a new signature request
POST /files/pending/fields/	Initiate a new signature request with fields
POST /files/pending/<:id>/decline/	Decline a pending document or signature request
POST /files/pending/<:id>/cancel/	Void an existing signature request initiated by the user
POST /files/pending/<:id>/remind	Remind the signers of a signature request to sign the document
POST /files/pending/<:id>/download	Download pending file with id

Templates

End point	Description
GET /library/template/	Fetch all templates in the user's account
GET /library/template/<:id>/	Retrieve a specific template with id
POST /files/pending/template/	Initiate a request signature from a template

Webhooks

End point	Description
GET /callback/urls/	Fetch all the webhook URLs your app will receive for a user
POST /callback/urls/	Configure a new webhook URL for the user
DELETE /callback/urls/	Delete a webhook URL you had previously set

Embedded Sending and Self-Signing

End point	Description
POST /v2/signing/url/	Open an original document for signing - self sign or request signature (via fields or templates)

Embedded Signing

End point	Description
POST /files/pending/<pending_file_id>/signing/url	Get the signing link for a signer of a signature request

API return codes

You will usually receive these following return codes on using the APIs.

Status Code	Description
200	Your API request was successful, but there could be errors
201	Your API request was successful
204	On successful update or create. There won't be a response body, only headers
401	Authentication error. Your access tokens most likely expired please generate new access tokens using the refresh token
404	The API you are using does not exist
405	The HTTP method you are using is not supported for this API
500	There was a server side exception, please issue a technical support ticket for assitance
503	SignEasy API service is down, plesae issue a technical support ticket for assistance

GET /user

Retrieve information about a user.

Requires -

Authorization header.

GET /user

Success -

{
    "account_type": 0,
    "activation_time": 1395392655,
    "is_auto_renew": 0,
    "company": "signeasy",
    "company_size": null,
    "created_time": 1391545509,
    "document_credits": 0,
    "email": "[email protected]",
    "first_name": "asdfasdf",
    "id": 699829,
    "is_paid": 0,
    "last_name": null,
    "last_modified_time": 1395367450,
    "referrer_code": "gSwRXxut",
    "referrer_promo_left": 5,
    "subscription_expiry_time": null,
    "imported_file_count": 72,
    "signed_file_count": 16,
    "card_last4": null,
    "card_brand": null,
    "status": 1,
    "email_verified": 1
}

POST /user

Create a new account in SignEasy. This API also triggers a welcome email and a verification email from SignEasy. Post verification of the email address, you can make API calls on behalf of the user. Use the email_verified key in the GET /user API response to check if your users have verified their accounts.

Requires -

Authorization of the API app owner

form fields -

email (str) - Email address of the user, for whom the account is being created.
password_hash (str) - Use the value of sha256(base64(actual_password))
platform (str) - Use the value partner
login_source (str) - Use the value email
version (str) - Use a version of your app that the user is being created on

Optional -

form fields -

first_name (str) - First name of the user
last_name (str) - Last name of the user
company (str) - Company name of the user

POST /user

Success -

{
    "id": 123456,
    "access_token": "eyJhbGciOiJIUzI1NiIsImV4caWF0IjoxNDEwMjY4NTQ5fQ"
}

Failures - the Status code will be 200 in these cases.

There is already an account with the provided email

{
    "error_code": "account_exists",
    "message": "Account already exists"
}

GET /files/

Retrieves all the files of a user. Requires the authentication scope files:read.

Requires -

Authorization header.

GET /files/

Success -

{
    "count": 5,
    "draft": {
        "count": 2,
        "files": [
            {
                "created_time": 1408950164,
                "file_size": 148838,
                "id": 1171,
                "last_modified_time": 1408950164,
                "name": "H000180CM010780_.pdf"
            },
            {
                "created_time": 1408951783,
                "file_size": 502169,
                "id": 1177,
                "last_modified_time": 1408951783,
                "name": "Try it now - demo.pdf"
            }
        ]
    },
    "original": {
        "count": 2,
        "files": [
            {
                "created_time": 1408948557,
                "id": 3114300,
                "last_modified_time": 1408948477,
                "name": "H000180CM010780_.pdf"
            },
            {
                "created_time": 1408947448,
                "id": 3114298,
                "last_modified_time": 1408947448,
                "name": "Try it now - demo.pdf"
            }
        ]
    },
    "signed": {
        "count": 1,
        "files": [
            {
                "created_time": 1409296771,
                "checksum": "bc3dc717816e9ef027600c57b8373d5fc50fe72d2b746d9",
                "id": 1085102,
                "last_modified_time": 1409296771,
                "name": "H000180CM010780_.pdf",
                "public_identifier": "9Bu9ULkQboiY2uB9Ff7Iig=="
            }
        ]
    },
    "pending": {
        "count": 1,
        "files": [
            {
                "created_time": 1439375702,
                "id": 46,
                "is_ordered": 1,
                "last_modified_time": 1439375711,
                "name": "a new file.pdf",
                "next": null,
                "owner_email": "[email protected]",
                "owner_first_name": "",
                "owner_last_name": "",
                "owner_company": "",
                "recipients": [
                    {
                        "created_time": 1439375703,
                        "email": "[email protected]",
                        "first_name": "P",
                        "last_name": "G",
                        "last_modified_time": 1439375703,
                        "order_id": 1,
                        "recipient_id": 65,
                        "status": "not_viewed"
                    },
                    {
                        "created_time": 1439375703,
                        "email": "[email protected]",
                        "first_name": null,
                        "last_name": null,
                        "last_modified_time": 1439375703,
                        "order_id": 2,
                        "recipient_id": 64,
                        "status": "not_viewed"
                    }
                ],
                "status": "canceled"
            }
        ]
    }
}

GET /files/original/

Retrieve information about all the original file of a user.

GET /files/original/

Success -

{
    "count": 3,
    "files": [
        {
            "created_time": 1408948557,
            "id": 3114300,
            "last_modified_time": 1408948477,
            "name": "H000180CM010780_.pdf"
        },
        {
            "created_time": 1408949190,
            "id": 3114302,
            "last_modified_time": 1408949111,
            "name": "intl_nuñez.pdf"
        },
        {
            "created_time": 1408947448,
            "id": 3114298,
            "last_modified_time": 1408947448,
            "name": "Try it now - demo.pdf"
        }
    ]
}

GET /files/original/<:int:original_file_id>/

Retrieve information about a original file of a user with id original_file_id

GET /files/original/3114302/

Success -

{
    "created_time": 1408949190,
    "id": 3114302,
    "last_modified_time": 1408949111,
    "name": "intl_nuñez.pdf"
}

GET /files/signed/

Retrieve information about all the signed files of a user.

GET /files/signed/

Success -

{
    "count": 2,
    "files": [
        {
            "created_time": 1409296771,
            "checksum": "bc3dc717816e9ef027600c57b8373bf6943e3407320b1bd5fc50fe72d2b746d9",
            "id": 1085102,
            "last_modified_time": 1409296771,
            "name": "H000180CM010780_.pdf",
            "pending_file": null,
            "public_identifier": "9Bu9ULkQboiY2uB9Ff7Iig=="
        },
        {
            "created_time": 1409223471,
            "checksum": "bc600c57b8373bf6943e3403dc71781d5fc50fe72d6e9ef0277320b1b2b746d9",
            "id": 1028510,
            "last_modified_time": 1409219677,
            "name": "Hello, How are you?.pdf",
            "pending_file":  {
                "created_time": 1441613193,
                "id": 283,
                "is_ordered": 1,
                "last_modified_time": 1441613208,
                "name": "冲盖机停开机调整要.pdf",
                "next": null,
                "owner_email": "[email protected]",
                "owner_first_name": "",
                "owner_last_name": "",
                "owner_company": "",
                "recipients": [
                    {
                        "created_time": 1441613193,
                        "email": "[email protected]",
                        "first_name": "",
                        "last_name": "",
                        "last_modified_time": 1441613208,
                        "order_id": 1,
                        "recipient_id": 522,
                        "status": "finalized"
                    }
                ],
                "status": "complete"
            },
            "public_identifier": "E740MX4j3vFOobTo7iWLZQ==" 
        }
   ]
}

GET /files/signed/<:int:signed_file_id>/

Retrieve information about a signed file of a user with id signed_file_id

GET /files/signed/1085102/

Success -

{
    "created_time": 1409296771,
    "checksum": "bc3dc717816e9ef027600c57b8370b1bd5fc50fe72d2b746d9",
    "id": 1085102,
    "last_modified_time": 1409296771,
    "name": "H000180CM010780_.pdf",
	"pending_file":  {
		"created_time": 1441613193,
		"id": 283,
		"is_ordered": 1,
		"last_modified_time": 1441613208,
		"name": "冲盖机停开机调整要.pdf",
		"next": null,
		"owner_email": "[email protected]",
		"owner_first_name": "",
		"owner_last_name": "",
		"owner_company": "",
		"recipients": [
			{
				"created_time": 1441613193,
				"email": "[email protected]",
				"first_name": "",
				"last_name": "",
				"last_modified_time": 1441613208,
				"order_id": 1,
				"recipient_id": 522,
				"status": "finalized"
			}
		],
		"status": "complete"
	},
	"public_identifier": "E740MX4j3vFOobTo7iWLZQ=="
}

GET /files/pending/

Retrieve information about all the pending files of a user, including all the pending files where s/he is the owner and recipient This API returns a response irrespective of whether the pending file is complete, incomplete, canceled or recipient_declined.

GET /files/pending/

Success -

{
    "count": 2,
    "files": [
        {
            "created_time": 1439460652,
            "id": 68,
            "is_ordered": 1, # if the signature request recipients have to sign in order or not
            "last_modified_time": 1439460652,
            "logo": null, # Use for enterprise accounts
            "name": "Testing.pdf",
            "next": 108, # The next recipient ID who is to sign/take action on the document
            "owner_email": "[email protected]",
            "owner_first_name": "PG",
            "owner_last_name": "2",
			"owner_company": "",
            "recipients": [
                {
                    "created_time": 1439460652,
                    "email": "[email protected]",
                    "first_name": "",
                    "last_name": "",
                    "last_modified_time": 1439460652,
                    "order_id": 1, # Order number of this recipient
                    "recipient_id": 108,
                    "status": "not_viewed"
                },
                {
                    "created_time": 1439460652,
                    "email": "[email protected]",
                    "first_name": "P",
                    "last_name": "G",
                    "last_modified_time": 1439460652,
                    "order_id": 2,
                    "recipient_id": 109,
                    "status": "not_viewed"
                }
            ],
            "status": "incomplete"
        },
        {
            "created_time": 1439460908,
            "id": 69,
            "is_ordered": 1,
            "last_modified_time": 1439460908,
            "logo": null,
            "name": "a new file.pdf",
            "next": 110,
            "owner_email": "[email protected]",
            "owner_first_name": "",
            "owner_last_name": "",
			"owner_company": "",
			"has_markers": 1,
            "recipients": [
                {
                    "created_time": 1439460908,
                    "email": "[email protected]",
                    "first_name": "",
                    "last_name": "",
                    "last_modified_time": 1439460908,
                    "order_id": 1,
                    "recipient_id": 110,
                    "status": "not_viewed"
                },
                {
                    "created_time": 1439460908,
                    "email": "[email protected]",
                    "first_name": "PG",
                    "last_name": "2",
                    "last_modified_time": 1439460908,
                    "order_id": 2,
                    "recipient_id": 111,
                    "status": "not_viewed"
                }
            ],
            "status": "incomplete"
        }
    ]
}

GET /files/pending/<:int:pending_file_id>/

Retrieve information about a pending file of a user with id pending_file_id

GET /files/pending/69/

Success -

{
    "created_time": 1439460908,
    "id": 69,
    "is_ordered": 1,
    "last_modified_time": 1439460908,
	"logo": "https://s3.amazonaws.com/selogos/700888/logo.png",
    "name": "a new file.pdf",
    "next": 110,
    "owner_email": "[email protected]",
    "owner_first_name": "",
    "owner_last_name": "",
	"owner_company": "",
	"has_markers": 1,
    "recipients": [
        {
            "created_time": 1439460908,
            "email": "[email protected]",
            "first_name": "",
            "last_name": "",
            "last_modified_time": 1439460908,
            "order_id": 1,
            "recipient_id": 110,
            "status": "not_viewed"
        },
        {
            "created_time": 1439460908,
            "email": "[email protected]",
            "first_name": "PG",
            "last_name": "2",
            "last_modified_time": 1439460908,
            "order_id": 2,
            "recipient_id": 111,
            "status": "not_viewed"
        }
    ],
    "status": "incomplete"
}

GET /library/template/

Returns all the templates available in the account.

Requires

Authorization Header

Response

[
    {
        "created_time": 1504088042,
        "id": 1450,
        "is_ordered": false,
        "message": "",
        "metadata": {
            "fields": [
                {
                    "additional_info": "MM/DD/YY",
                    "id": 1,
                    "required": true,
                    "role_id": 2,
                    "type": "signature"
                },
                {
                    "additional_info": "MM/DD/YY",
                    "id": 4,
                    "required": true,
                    "role_id": 1,
                    "type": "date"
                }
            ],
            "roles": [
                {
                    "color": "(255, 165, 0, 0.35)",
                    "fields": [
                        4
                    ],
                    "id": 1,
                    "name": "Student"
                },
                {
                    "color": "(56, 185, 174, 0.35)",
                    "fields": [
                        1
                    ],
                    "id": 2,
                    "name": "Teacher"
                }
            ]
        },
        "modified_time": 1504088070,
        "name": "anishhegde"
    },
    {
        "created_time": 1504087737,
        "id": 1449,
        "is_ordered": false,
        "message": "",
        "metadata": {
            "fields": [
                {
                    "additional_info": "",
                    "id": 1,
                    "required": true,
                    "role_id": 1,
                    "type": "text"
                },
                {
                    "additional_info": "",
                    "id": 2,
                    "required": true,
                    "role_id": 2,
                    "type": "text"
                }
            ],
            "roles": [
                {
                    "color": "[255, 165, 0, 0.35]",
                    "fields": [
                        1
                    ],
                    "id": 1,
                    "name": "client"
                },
                {
                    "color": "[56, 185, 174, 0.35]",
                    "fields": [
                        2
                    ],
                    "id": 2,
                    "name": "manager"
                }
            ]
        },
        "modified_time": 1504087873,
        "name": "for13"
    }
]

GET /library/template/<:id>/

Fetch details of a particular template, identified by id.

Requires

Authorization Header

{
    "created_time": 1504087737,
    "id": 1449,
    "is_ordered": false,
    "message": "",
    "metadata": {
        "fields": [
            {
                "additional_info": "",
                "id": 1,
                "required": true,
                "role_id": 1,
                "type": "text"
            },
            {
                "additional_info": "",
                "id": 2,
                "required": true,
                "role_id": 2,
                "type": "text"
            }
        ],
        "roles": [
            {
                "color": "[255, 165, 0, 0.35]",
                "fields": [
                    1
                ],
                "id": 1,
                "name": "client"
            },
            {
                "color": "[56, 185, 174, 0.35]",
                "fields": [
                    2
                ],
                "id": 2,
                "name": "manager"
            }
        ]
    },
    "modified_time": 1504087873,
    "name": "for13"
}

GET /files/(original/signed/pending)/<:id>/download/

Download the actual file contents of file with id

Requires

Authorization Header

Optional form fields -

attachment (bool) - If the download should be as an attachment. If true, then the Content-Disposition would be attachment and filename would be present in the headers for the browser to pick up.

GET files/original/1172/download/

Success - Stream of file content

Headers -

Cache-Control →public, max-age=43200
Connection →keep-alive
Content-Encoding →gzip
Content-Type →application/pdf
Date →Thu, 09 Oct 2014 07:15:36 GMT
Expires →Thu, 09 Oct 2014 19:15:36 GMT
Last-Modified →Mon, 25 Aug 2014 13:12:42 GMT
Server →nginx/1.4.6 (Ubuntu)
Transfer-Encoding →chunked

Make sure you handle the compressed file body (gzip). You can request a decompressed file by setting Accept-Encoding header to deflate.

Failures

When the file is not present. Status code will be 200

{
    "error_code": "file_not_found",
    "message": "File not found"
}

PUT /files/original/<:id>/

Update a original file. Use this API to either rename an original file or update the contents of an original file.

Requires

Authorization Header

Optional

form fields -

name (str) - New name of the file (make sure you include extension of the file)
file (actual file) - Actual file to be uploaded

PUT /files/original/631/

with form fields -

name -> "Testing only Name change.pdf"

Success - 204, no response body

Status code - 204,

Failures - Status code will be 200 in these cases.

File name already exists

{
    "error_code": "filename_exists",
    "message": "There is already a file with the same name. Please use a different name."
}

PUT /files/signed/<:id>/

Rename a file. Pass the new name as a form parameter.

form fields -

name (str) - New name of the file (make sure you include extension of the file)

PUT /files/signed/3114298/

Success -

Status code - 204, no response body.

Failures - Status code will be 200 in these cases.

File name already exists

{
    "error_code": "filename_exists",
    "message": "There is already a file with the same name. Please use a different name."
}

GET /audit-trail/<:signed_file_id>/

Generates and downloads the audit trail of the signed file based on signed_file_id as per provided.

Requires

Authorization header

Success

Will generate and download the audit trail for the asked signed file.

Failures

When signed_file_id is invalid, response status code will be: 400

When signed file doesn't belongs to the user who requested, response status code will be: 400

DELETE /files/(original/signed)/<:id>/

Delete a file.

Requires

Authorization Header

DELETE /files/original/3114298/

Success -

Status code - 204, no response body.

Failure scenarios

If user doesn't have access to a particular file, a 401 is returned
If a file with the id is not present, a 401 is returned as the API assumes the user is trying to delete a file that he doesn't have access to.

DELETE /files/(original/signed)/

Delete multiple files at once.

Requires

Authorization Header

Form fields or Query string

id (comma separated list): list of ids to be deleted, separated by commas.

DELETE /files/original/

with id as 234,253425,263634

Success -

Status code - 204, no response body.

Failure scenarios

If user doesn't have access to a particular file, a 401 is returned
If a file with the id is not present, a 401 is returned as the API assumes the user is trying to delete a file that he doesn't have access to.

In both the cases, the execution stops and even the valid files are not deleted.

POST /files/delete/

Delete multiple files of any type at once.

Requires

Authorization Header

Form fields or Query string (Optional)

signed (comma separated list): list of signed file ids to be deleted, separated by commas
original (comma separated list): list of original file ids to be deleted, separated by commas

POST /files/delete/

with original as 1085509, 1085510, 1085511

signed as 10855, 10855, 10855

Success -

Status code - 204, no response body.

Failure scenarios

If user doesn't have access to a particular file, a 401 is returned
If a file with the id is not present, a 401 is returned as the API assumes the user is trying to delete a file that he doesn't have access to.

In both the cases, the execution stops and even the valid files are not deleted.

POST /files/(original/signed)/delete/

Delete multiple files at once.

Requires

Authorization Header

Form fields or Query string

id (comma separated list): list of ids to be deleted, separated by commas.

POST /files/original/delete/

with id as 234,253425,263634

Success -

Status code - 204, no response body.

Failure scenarios

If user doesn't have access to a particular file, a 401 is returned
If a file with the id is not present, a 401 is returned as the API assumes the user is trying to delete a file that he doesn't have access to.

POST /files/original/

Import or upload a new document into SignEasy to open it for signing (either yourself or requesting signatures).

Requires

Authorization Header

Form fields

name (str): Display name of the file (make sure you include the extension of the file.)
file (actual file): The actual file being imported or uploaded.

Optional

size (int): Size of the file being uploaded
rename_if_exists (bool): Use this flag, if you want to rename the imported document in case there is already one with the same name. Defaults to false and returns filename_exists error in a case where the document name already exists.

The file can be gzip compressed and uploaded to speed up the upload. Make sure you set the Content-Encoding header as 'gzip' for the server to recognize the compression. If you do not pass any Content-Encoding header, the server assumes an uncompressed file upload.

POST /files/original/ with name - TDonate.pdf size - 23434 file - actual_file

Success -

{
    "created_time": 1413798221,
    "id": 3092010,
    "last_modified_time": 1413798221,
    "name": "TDonate.pdf"
}

Failures - Status code will be 200 in these cases.

File name already exists

{
    "error_code": "filename_exists",
    "message": "There is already a file with the same name. Please use a different name."
}

File could not be converted

{
    "error_code": "file_conversion_failure",
    "message": "File could not be converted to PDF."
}

POST /files/pending/

Initiate a new signature request.

Requires -

Authorization header.
Content-Type : application/json

JSON - (Only JSON is supported in this API). Do not forget to set the Content-Type header as application/json

recipients (json) - List of recipients with each recipient in this format - [{"email": "[email protected]", "first_name": "Patrick", "last_name": "Schmidt"}, {"email": "[email protected]", "first_name": "Allie", "last_name": "Benson"}]
original_file_id - The original file ID, that the signers should sign.
is_ordered - set to 0 for parallel signing (each recipient is notified to sign at once) and 1 for sequential signing (recipient is notified after the previous one has signed)

Optional -

message(str) - If the owner (sender of the signature request) wants to add a message to the signers to sign the document.
cc (json) - List of emails to be cced in this format - [{"email": "[email protected]", "first_name": "P", "last_name": "ரூம் சர்வீஸ்"}, {"email": "[email protected]", "first_name": "A", "last_name": "BC"}]
embedded_signing (bool) - If this signature request should be enabled for use in embedded signing. Enabling this suppresses all emails that the signers receive, including the emails with links to sign the document.

POST /files/pending/ with request body -

{
    "recipients": [
        {
            "email": "[email protected]",
            "first_name": "Patrick",
            "last_name": "Schmidt"
        },
        {
            "email": "[email protected]",
            "first_name": "Allie",
            "last_name": "Benson"
        }
    ],
    "original_file_id": 3092402,
    "is_ordered": 1,
    "message": "Folks, please sign this document to kick off the purchase and complete the order.",
    "cc": [
        {
            "email": "[email protected]",
            "first_name": "Jan",
            "last_name": "The Manager"
        }
    ],
    "platform" : "webapp",
    "app_version": "4.0.0.1",
    "embedded_signing": 0
}

Success - 201

{
    "pending_file_id": 345
}

Failures - Status code will be 200.

If an invalid original file id is used - status code of 401.

{
    "message": "Unauthorized",
    "error_code": "unauthorized_resource"
}

If the user is not allowed to create a pending file.

{
    "message": "User does not have access to create a pending file", 
    "error_code": "not_allowed"
}

POST /files/pending/fields/

Initiate a new signature request.

Requires -

Authorization header.
Content-Type : application/json

JSON - (Only JSON is supported in this API). Do not forget to set the Content-Type header as application/json

recipients (json) - List of recipients with each recipient in this format - [{"email": "[email protected]", "first_name": "Patrick", "last_name": "Schmidt"}, {"email": "[email protected]", "first_name": "Allie", "last_name": "Benson"}]
original_file_id - The original file ID, that the signers should sign.
is_ordered - set to 0 for parallel signing (each recipient is notified to sign at once) and 1 for sequential signing (recipient is notified after the previous one has signed)
fields_payload - list of fields with format [{'height': 150, 'width': 100, 'page_number': 1, 'y': 0, 'x': 0, 'required': True, 'type': 'date', 'email': '[email protected]', 'additional_info': {'format': 'DD/MM/YYYY'}}, {'height': 150, 'width': 100, 'page_number': 1, 'y': 200, 'x': 200, 'required': True, 'type': 'signature', 'email': '[email protected]', 'additional_info': {}}]

Optional -

message(str) - If the owner (sender of the signature request) wants to add a message to the signers to sign the document.
cc (json) - List of emails to be cced in this format - [{"email": "[email protected]", "first_name": "P", "last_name": "ரூம் சர்வீஸ்"}, {"email": "[email protected]", "first_name": "A", "last_name": "BC"}]
embedded_signing (bool) - If this signature request should be enabled for use in embedded signing. Enabling this suppresses all emails that the signers receive, including the emails with links to sign the document.

POST /files/pending/fields/ with request body -

{
    "recipients": [
        {
            "email": "[email protected]",
            "first_name": "Patrick",
            "last_name": "Schmidt"
        },
        {
            "email": "[email protected]",
            "first_name": "Allie",
            "last_name": "Benson"
        }
    ],
    "fields_payload": [
         {
            "email":"[email protected]",
            "additional_info": {"format": "DD/MM/YYYY"},
            "type":"date",
            "required":True,
            "page_number":1,
            "x":0,
            "y":0,
            "width":100,
            "height":150
         },
         {
            "email":"[email protected]",
            "additional_info": {},
            "type":"signature",
            "required":True,
            "page_number":1,
            "x":200,
            "y":200,
            "width":100,
            "height":150
         }
    ],
    "original_file_id": 3092402,
    "is_ordered": 1,
    "message": "Folks, please sign this document to kick off the purchase and complete the order.",
    "cc": [
        {
            "email": "[email protected]",
            "first_name": "Jan",
            "last_name": "The Manager"
        }
    ],
    "platform" : "webapp",
    "app_version": "4.0.0.1",
    "embedded_signing": 0
}

Success - 201

{
    "pending_file_id": 345
}

Failures - Status code will be 200.

If an invalid original file id is used - status code of 401.

{
    "message": "Unauthorized",
    "error_code": "unauthorized_resource"
}

If the user is not allowed to create a pending file.

{
    "message": "User does not have access to create a pending file", 
    "error_code": "not_allowed"
}

Status code will be 400.

If fields assigned to users who are not recipients: Status code will be 400.

{
    "msg": "Fields assigned to users who are not recipients",
    "error_code": "wrong_assigned_field"
}

If fields not assigned to all recipients: Status code will be 400.

{
    "msg": "Fields not assigned to all recipients",
    "error_code": "un_assigned_field"
}

If field payload page number exceeds document page number: Status code will be 400.

{
    "msg": "The field payload page number exceeds document page number",
    "error_code": "page_out_of_bound"
}

POST /files/pending/template/

Initiate a new signature request using a template.

Requires Headers -

Authorization Header
Content-Type : application/json

JSON body - (Only JSON is supported in this API). Do not forget to set the Content-Type header as application/json

{
	"template_file_id": 46,
	"is_ordered": false,
	"recipients": [{
		"email": "[email protected]",
		"first_name": "John",
		"last_name": "Smith",
		"role_id": 1
	}, {
		"email": "[email protected]",
		"first_name": "Jack",
		"last_name": "Wells",
		"role_id": 2
	}, {
		"email": "[email protected]",
		"first_name": "William",
		"last_name": "Horde",
		"role_id": 3
	}],
	"cc": [],
	"message": "Please sign the document",
	"name": "NDA.pdf",
	"file_password": ""
}

**Optional** -

- embedded_signing (bool) - If this signature request should be enabled for use in embedded signing.
- aadhaar_enabled (bool) - If you would like to add Aadhaar based verification for signatures (this feature is available in the Indian subcontinent only).

Response

{
    "pending_file_id": 9700
}

Note

role_id has to be incremented for each subsequent signer, if the template has more than one signer roles.
If your request has more recipients (signers) than the template was built for, you will get an error.

POST /files/pending/<:id>/decline/

API to be used for a recipient to decline signing a file. On success, an email is sent to the owner stating the same.

Only the recipient of this pending file who has not yet finalized this file can perform this action.

Requires

Authorization Header

Form fields or Query string (Optional)

message (str) - Recipient can choose to send a message as to why they declined. message will be used, if present.

POST /files/pending/69/decline/

Success -

Status code - 204, no response body.

POST /files/pending/<:id>/cancel/

API to be used for an owner to cancel an existing pending file. An email will be sent to all recipients stating the same.

Only the pending file owner can perform this action.

Requires

Authorization Header

Form fields or Query string (Optional)

message (str) - Owner can choose to send a message as to why they canceled. message will be used, if present.

POST /files/pending/69/cancel/

Success -

Status code - 204, no response body.

POST /files/pending/<:id>/remind/

API to be used for an owner to remind the next recipient to sign the document. If it is not ordered, then all recipients who have not signed will get the reminder.

Only the pending file owner can perform this action.

Requires

Authorization Header

Form fields or Query string (Optional)

message (str) - Owner can choose to send a message asking them to sign. If present, will be sent in the reminder email.

POST /files/pending/69/remind/

Success -

Status code - 204, no response body.

Failures - Status code will be 200.

If no recipient is available to be reminded

{
    "message": "No recipient available to remind",
    "error_code": "recipient_unavailable"
}

POST /files/pending/template/

Creates a request signature from a template.

Requires

Authorization Header
Content-Type : application/json

json body -

{
	"template_file_id": 46,
	"is_ordered": false,
	"recipients": [{
		"email": "[email protected]",
		"first_name": "",
		"last_name": "",
		"role_id": 1
	}, {
		"email": "[email protected]",
		"first_name": "Rajith",
		"last_name": "",
		"role_id": 2
	}, {
		"email": "[email protected]",
		"first_name": "Rajith2",
		"last_name": "",
		"role_id": 3
	}],
	"cc": [],
	"message": "",
	"name": "Anish Template Test",
	"file_password": ""
}

Response

{
    "pending_file_id": 9700
}

POST /v2/signing/url/

This API is used for embedded sending and self signing of an original file. This API returns an URL which lets you either open the document for signing it yourself or for request signature. If you choose request signature, you will also be able to add fields, or use templates to initiate the signature request.

Requires

Authorization Header

Form fields or Query string

file_id (str) - id of the original document

Optional Fields

type (str) - rs or self_sign
message (str) - message for type rs
recipients (json str) - recipients information for type rs
cc (json str) - cc information for type rs
redirect_url (url) - Coming Soon!

recipients json

[
    {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
    },
    {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe"
    }
]

cc json

[
    {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
    },
    {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe"
    }
]

POST /signing/url/

Success -

Status code - 200.

{
 "url": "https://app-beta.getsigneasy.com/#/embedded-signing?
 hash=27ba125d6c6f458b9116d8f8df08f33ce3619ffc72cd41e59edf1029dfdsdfb&file_id=2", "file_id": "2"
}

Failures - Status code will be 200.

GET /library/template/

This API lists all the templates for the user.

Requires

Authorization Header

Response

[
    {
        "created_time": 1504088042,
        "id": 1450,
        "is_ordered": false,
        "message": "",
        "metadata": {
            "fields": [
                {
                    "additional_info": "MM/DD/YY",
                    "id": 1,
                    "required": true,
                    "role_id": 2,
                    "type": "signature"
                },
                {
                    "additional_info": "MM/DD/YY",
                    "id": 4,
                    "required": true,
                    "role_id": 1,
                    "type": "date"
                }
            ],
            "roles": [
                {
                    "color": "(255, 165, 0, 0.35)",
                    "fields": [
                        4
                    ],
                    "id": 1,
                    "name": "Student"
                },
                {
                    "color": "(56, 185, 174, 0.35)",
                    "fields": [
                        1
                    ],
                    "id": 2,
                    "name": "Teacher"
                }
            ]
        },
        "modified_time": 1504088070,
        "name": "anishhegde"
    },
    {
        "created_time": 1504087737,
        "id": 1449,
        "is_ordered": false,
        "message": "",
        "metadata": {
            "fields": [
                {
                    "additional_info": "",
                    "id": 1,
                    "required": true,
                    "role_id": 1,
                    "type": "text"
                },
                {
                    "additional_info": "",
                    "id": 2,
                    "required": true,
                    "role_id": 2,
                    "type": "text"
                }
            ],
            "roles": [
                {
                    "color": "[255, 165, 0, 0.35]",
                    "fields": [
                        1
                    ],
                    "id": 1,
                    "name": "client"
                },
                {
                    "color": "[56, 185, 174, 0.35]",
                    "fields": [
                        2
                    ],
                    "id": 2,
                    "name": "manager"
                }
            ]
        },
        "modified_time": 1504087873,
        "name": "for13"
    }
]

GET /library/template/<:id>/

Lists the template corresponding to the template id provided.

Requires

Authorization Header

{
    "created_time": 1504087737,
    "id": 1449,
    "is_ordered": false,
    "message": "",
    "metadata": {
        "fields": [
            {
                "additional_info": "",
                "id": 1,
                "required": true,
                "role_id": 1,
                "type": "text"
            },
            {
                "additional_info": "",
                "id": 2,
                "required": true,
                "role_id": 2,
                "type": "text"
            }
        ],
        "roles": [
            {
                "color": "[255, 165, 0, 0.35]",
                "fields": [
                    1
                ],
                "id": 1,
                "name": "client"
            },
            {
                "color": "[56, 185, 174, 0.35]",
                "fields": [
                    2
                ],
                "id": 2,
                "name": "manager"
            }
        ]
    },
    "modified_time": 1504087873,
    "name": "for13"
}

GET /callback/urls/

Lists all callback urls for the particular user and client

Requires

Authorization Header
Client ID : X-Client-ID : 5igAbZSN2rIdsfMJ0dv8QTSF1ZwSWRtefq5sdfl (your client ID)

Success - 200

{
    "callback_urls": [
        "https://getsigneasy.in/1igo0sg1"
    ]
}

Failures - 200

{
    "error_msg": "wrong client id supplied"
}

POST /callback/urls/

Adds the callback urls for the particular user and client

Requires

Authorization Header
Client ID : X-Client-ID : 5igAbZSN2rIdsfMJ0dv8QTSF1ZwSWRtefq5sdfl (your client ID)

Form fields or Query string (JSON is not supported for this API)

urls (str) - comma-separated urls

POST /callback/urls/

Success - 200

{
    "callback_urls": [
        "https://getsigneasy.in/1igo0sg1"
    ]
}

Failures - 200

{
    "error_msg": "wrong client id supplied"
}

DELETE /callback/urls/

Deletes the callback urls for the particular user and client

Requires

Authorization Header
Client ID : X-Client-ID : 5igAbZSN2rIdsfMJ0dv8QTSF1ZwSWRtefq5sdfl (your client ID)

Form fields or Query string (JSON is not supported for this API)

urls (str) - comma-separated urls to be deleted

POST /callback/urls/

Success - 202

{
    "callback_urls": [
        "https://getsigneasy.in/1igo0sg1"
    ]
}

Failures - 200

{
    "error_msg": "URL does not exist"
}

Failures - 200

{
    "error_msg": "wrong client id supplied"
}

POST /files/pending/<pending_file_id>/signing/url

Get the signing link for a signer of a particular signature request. You can use this link to get documents signed on your own website or mobile app.

Requires

Authorization Header

Form Field

recipient_email - [email protected]
redirect_url (url) - Coming Soon!

Success - 200

{
	"url": "https://app.getsigneasy.com/signrequest?hash=01d9c13da88b449e8444177dd08ad830b2e304406f4439af30f66ff4c262acbc8bd6639c524bc2884cd4a14928a6d5"
}

Failures - 401

{
	 "error_code": "unauthorized_resource",
	 "message": "Unauthorized"
}

Failures - 200

{
	"error_code": "rs_canceled/rs_declined/rs_complete/not_allowed", 
	"message": "The pending file has been modified"
}

1. API Endpoints - signeasy/API GitHub Wiki

API Base URL

User APIs

File APIs

Original Documents

Completed Documents

Pending Documents (Request Signatures)

Templates

Webhooks

Embedded Sending and Self-Signing

Embedded Signing

API return codes

GET /user

POST /user

GET /files/

GET /files/original/

GET /files/original/<:int:original_file_id>/

GET /files/signed/

GET /files/signed/<:int:signed_file_id>/

GET /files/pending/

GET /files/pending/<:int:pending_file_id>/

GET /library/template/

GET /library/template/<:id>/

GET /files/(original/signed/pending)/<:id>/download/

PUT /files/original/<:id>/

PUT /files/signed/<:id>/

GET /audit-trail/<:signed_file_id>/

DELETE /files/(original/signed)/<:id>/

DELETE /files/(original/signed)/

In both the cases, the execution stops and even the valid files are not deleted.

POST /files/delete/

In both the cases, the execution stops and even the valid files are not deleted.

POST /files/(original/signed)/delete/

POST /files/original/

POST /files/pending/

POST /files/pending/fields/

POST /files/pending/template/

POST /files/pending/<:id>/decline/

POST /files/pending/<:id>/cancel/

POST /files/pending/<:id>/remind/

POST /files/pending/template/

POST /v2/signing/url/

GET /library/template/

GET /library/template/<:id>/

GET /callback/urls/

POST /callback/urls/

DELETE /callback/urls/

POST /files/pending/<pending_file_id>/signing/url

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️