You can attach one or more Documents to a Signature Request

Once a Signature Request has been initiated, you can add it one or more Documents. The Signature Request must be in draft status.

A document attached to a Signature Request can be :

  • A document to sign.
  • An attachment which can be consulted by the Signers and Approvers during the Signing Flow but which doesn't require to be signed.

Here are some elements to have in mind when you manipulate documents with our API:

  • You can upload a PDF or a docx to a Signature Request.
    All documents in docx format will be automatically converted to PDF at upload. We will only store the PDF version of the document on our side.
  • The maximum document size is 50 MB and you can attach up to 50 documents to a Signature Request.
  • If you plan to use Smart Anchors in your document, it can't exceed 50 pages.
  • You can't upload a document already signed.

All the endpoints available to manage Documents can be found in our API Reference.

Technical aspects of document's upload

Document management

Once you upload a document a documentId will be provided. You are in charge to store this documentId and use it to attach files to the Signature Request.


To upload a document you will have to use the POST /documents endpoint.

Our upload system relies on the multipart form data mechanism. You have set the Content-Type to multipart/form-data when you call the document upload endpoint. You can refer to this code example to learn how you can achieve that.
This tutorial might also help you to upload your first document.


Be careful, we don't accept base64 files.

Yousign's API provides endpoints to manage your documents

Many actions can be done on a document. You can for example update a document, delete it or just get information about it.
All those possibilities are detailed in our API reference and rely on the documentId, so make sure to store it once you upload a document.

Order and re-order documents within a Signature Request in draft status

If you add several documents to your Signature Request, you may want to choose which one is first presented to the Signer.

By default, documents will be ordered - and presented - by the upload date, i.e. created_at date, from the oldest to the most recent.

It is also possible to override this rule by specifying after which document a specific document should be displayed. To do that, you need to use the parameter insert_after_id and pass the id of this document as value. This parameter is available in our endpoints to upload or update a document.