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.
• A sealed document (see Re-use a sealed document).

Upload rules

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

• The document must be in the following formats:
  • If nature = signable_document: PDF or DOCX.
  • If nature = attachment: PDF, DOCX, JPEG, JPG, or PNG.
• For documents in PDF format:
  • If nature = signable_document: the PDF version must be 1.6 or higher.
  • If nature = attachment: any PDF version is accepted.
  • The document must be properly formatted such that our system is be able to extract the PDF version metadata correctly.
  • The document must allow modifications and form filling. This is controlled by the certification level in the PDF security settings.
• The document must not exceed 50 MB in size.
• If the document is already signed, it cannot contain any Fields other than signature Fields.
• If you intend to parse Smart Anchors in your document, it must not exceed 50 pages.
• If the document is protected with a password, you must provide the password with the password parameter.
• You can add up to 50 Documents to a Signature Request.

→ All documents in DOCX, PNG, JPEG, and PNG format will be automatically converted to PDF at upload. Only the PDF version will be stored on our side.

Name or rename a Document

The name parameter can be used to change the name of the Document when it is uploaded or updated. Only Documents name from Signature Requests in draft status can be changed.

The name parameter must match the following naming pattern to ensure consistent and valid Documents name: /^(?!\s)[^\/\\]+(?<!\s)$/. It means that:

• Names cannot start or end with a space.
• Names can contain any character except / or \.

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

Technical aspects of document 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.

Upload

To upload a document you will have to use the POST /signature_requests/{signatureRequestId}/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.