Getting signer attachments using the eSignature REST API

When sending an envelope to a recipient, sometimes you require that recipient to provide additional information in the form of identification or other records that you need for your business to process a contract. DocuSign offers a signer attachment tab that enables you to collect this information from recipients, which you can then also download using our eSignature REST API.

Signer attachments

The signer attachment tab works a lot like any other tab that you can designate for your signer, allowing them to select it and then prompting them to upload the required information. The file that they upload will then be converted to a PDF and appended to the envelope where the sender and all other recipients will be able to view it. The file must be a supported file type and be 25MB or less in size for the recipient to upload it.

You can specify one or more signer attachment tabs for your recipient. After they have uploaded their files and finished signing their portion of the envelope, the files are then added as documents to the envelope. There are a few steps to obtain the attachments if you would like to download them using our eSignature REST API.

Process

1. Create the envelope

We’ll start with creating the envelope for the recipient first. In this example, I’ll just specify a single signer attachment tab for the recipient; however, you can specify multiple tabs if required. You should take special note of the name that you specify for the attachment tab, as you can use this to help specify which attachment tab is which, if you have multiple tabs. You should make the name specific to the document type that you are looking to receive from the recipient, such as “identification” or “tax documents”.

{
  "status": "sent",   
  "documents": [{
      "documentId": "1",
      "name": "TestDocument.docx",
      "fileExtension": "docx",
      "documentBase64": "UEsDBBQABgAIAAAAIQCs5OaDpQEAAC4IAAATAAg…"
    }
  ],
  "recipients": {
    "signers": [{
        "name": "John Doe",
        "email": "johndoe@example.com",        
        "recipientId": "1",
        "tabs": {          
          "signerAttachmentTabs":[{
              "name": "Sample Attachment",
              "documentId": 1,
              "pageNumber": 1,
              "recipientId": 1,
              "xPosition": 200,
              "yPosition": 200
          }]
        }
      }
    ]
  }
}

2. Get the recipient’s tabs

After you have sent the envelope to the recipient and they have uploaded their attachment(s) and completed the rest of their tabs, you can then list their tabs by listing the tabs for their recipient.

GET https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/1/tabs

The response back will contain a signerAttmentTabs object listing all of the attachment tabs assigned to the recipient. What you will want to make note of here is the name that you specified for the tab as well as the tabId associated with it, as this will be used to find a specific attachment if you only want to download a certain one.

3. List the documents in the envelope

GET https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents

Calling this endpoint will list all of the documents in the envelope, which will now include the document(s) that your signer uploaded. The only identifying information that you will have for the document(s) that they uploaded will be the name of the document, but this is based on what the signer saved the file as, so it may not be helpful in identifying what the document is. Instead, you should reference the attachmentTabId against the tabId from the previous step, as this will help you identify which attachment is which if there are multiple attachments. Once you have located the attachment that you want, you will then use the documentId in the next step to download the attachment.

4. Get the attachment

GET https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}

After making the GET call to the endpoint for the attachment that you would like, you will have successfully fetched the attachment. You can repeat the above process for any other attachments that you may need from the envelope as well.

Additional resources

Author

Jonathan Sammons

Developer Support Engineer

Published

July 19, 2023