These docs are for v2.1. Click to read the latest docs for v3.

Pending (Signature Requests)

Any document that has a signature pending, is a pending document

Once you have imported your first document, you are now ready to get your hands dirty with requesting signatures from your signers and having them signed.

What is a Signature Request?

With Signeasy, you can request your customers or users to fill and sign on any document that you have imported (Read more about importing files here).

You can also add fields to the document to guide the document recipients to fill and sign the document the way you want. Signeasy ensures that your document recipients (signers) will be guided through the document pages to fill and sign at the appropriate places.

You can mark certain fields as required and the document signers will not be able to finish signing until they fill in those fields. You can save original documents with fields as a template so that you can re-use them for sending out signature requests on multiple occasions. You can read more about templates here.

Through the rest of this documentation, pending files and signature requests will be used interchangeably.

Creating a Signature Request

Once you have identified a document to have filled and signed by your users (or customers or stakeholders), you can initiate a signature request without markers using the Pending File API.

You will need the original_file_id of the document in question, email addresses & names of your document signers ready. Once the signature request is sent out, you will receive a pending_file_id in the API response which can be used to track the status of that signature request going forward.

The document in the original format will continue to live as an Original, in your account. You can reuse these original documents to send as many signature requests as you want and each signature request comes with its own ID, which is the pending_file_id.

Signature Request Status

A signature request in the pending stage goes through a series of status changes, indicating the state of completion of the document by its signers.

The current state of the signature request is mentioned in the Pending File API response, as the status of the pending file.

A signature request can have the following statuses.

incompleteThe signature request is yet to be signed by all signers.
canceledThe user voided the signature request. Only the initiator (owner) of the document can void the signature request.
recipient_declinedOne of the recipients declined to sign the document. None of the other document recipients will be allowed to sign the document in this case and the signature request is effectively voided.
completeAll the recipients have filled and signed the document. Upon completion, a new completed document is added in the initiator's account which is the final signed and completed document by all recipients.

Recipient Status

Similar to the pending file document (or signature request) status, you have similar statuses for each of the recipients. This is useful information if you would like to perform actions based on the activity of the users on your document. E.g., you can trigger reminders to recipients who have viewed the document but haven't signed it yet.

If a signature request was declined by a recipient, this status indicates who was the recipient who declined the document as well.

Here are the different recipient statuses.

not_viewedThe recipient hasn't viewed the document yet.
viewedThe recipient has viewed the document.
declinedThe recipient declined to sign the document. The signature request cannot be signed by the other recipients either when this happens.
finalizedThe recipient signed the document.

Signature Request Completion

Once all the document recipients have filled, signed and finalized the document, all the parties involved (initiator, recipients, CC recipients) receive the final signed and completed document along with the audit trail. If the signature request was initiated with embedded_signing turned on, then no emails are sent from Signeasy to either the sender or the signer. You will be responsible for sharing the completed documents with the signers using your own app.

A new Completed Document is added to the initiator's Signeasy account as well. This is a new document which has its own ID, and is different from the pending file ID. The API response does contain a reference to the pending file that the completed document originated from.

The pending file ceases to show up in the file list, and in the API responses as well.

Here is a diagram depicting the transitions. Each of these documents are independent entities and are not the same.


Document transitions in Signeasy


Envelopes are signature requests which are formed using multiple originals. Some requests might require the user to sign in multiple documents such as real estate agreements where sending a single request for every document can complicate tracking and also signing for your clients.

An envelope can be treated as a pending document and hence all the document states and recipient status will remain unchanged.

Initiating an envelope request

Initiating an envelope request requires the original document ids, the recipient details such as (email, first name and last name) along with the page numbers to add the locations for signing.

More about the request here: (

Tracking an envelope request

Webhook calls can be used to track the status of the envelope document such as recipient viewed/ recipient signed/recipient declined.

For more about webhook calls and how to register one : ( ).

Downloading a completed envelope.

The rs.completed webhook
( )

returns the "signed_file_id" which can be used to download the signed document as a zip comprising of individual pdfs using


or individual documents using

( ).

When required to print the documents we can also download a merged PDF which is a single PDF containing all the documents using

( ).

What’s Next

How to quickly send signature requests using Templates?