From the Trenches: Chunked uploads

If you’re ever found yourself in a situation where you’re handling large PDFs, chances are you’ve also discovered Docusign’s limitations for maximum file sizes. Docusign limits the overall size of the document packets that you can upload for a number of reasons: API processing time, storage, scalability, send durations, and more. However, Docusign offers a separate mechanism that allows you to go beyond those limits: chunked uploads.

Essentially, chunked uploads let you send larger documents in pieces, or chunks. Before I show you how, let’s go over some ground rules for the system:

• Chunked uploads expire after 20 minutes or on use.

• Chunked uploads have an optional checksum parameter to do a final integrity check. 

• Chunked uploads can have a total file size accumulation of 1GB at any given time. This limit is for your account, not for individual envelopes. 

• The maximum file size for an accumulated chunked upload is 52MB.

Creating a chunked upload

Chunked uploads can be uploaded in pieces using the following API request:

POST ../v2.1/accounts/{account_ID}/chunked_uploads

{
    "data" : "Base64String"
}

Example response:

{
    "chunkedUploadId":  "3216E4B2-XXXX-XXXX-XXXX-34CC91813EA2",
    "chunkedUploadUri":  "docusignchunkedupload://3216E4B2-XXXX-XXXX-XXXX-34CC91813EA2",
    "expirationDateTime":  "2020-08-25T02:01:12Z",
    "committed":  "False",
    "chunkedUploadParts":  [
                               {
                                   "sequence":  "0",
                                   "size":  "18"
                               }
                           ],
    "totalSize":  "18",
    "maxChunkedUploadParts":  "129",
    "maxTotalSize":  "52428800"
}

If the upload is added successfully, Docusign will return two values that you’ll want to track: chunkedUploadId and chunkedUploadUri. To continue interacting with said chunk, you’ll need to append the chunkedUploadId to your calls. Also note that continued interactions with this chunk will require your HTTP method to be shifted from POST to PUT:

PUT .../v2.1/accounts/{account_ID}/chunked_uploads/{chunkedUploadId}

At this point you can either continue adding data to the chunk up to 52MB worth of total file accumulation, or commit the chunk to be used. You do this by making a final PUT call with the query parameter ?action=commit. Once the chunk has been committed, the response from the eSignature REST API will include an update to reflect the flag for “commited” has shifted to "true".

Now that you’ve committed the chunked upload, it’s time to use it. Keep in mind that once this chunk has reached an age of 20 minutes or is referenced as part of an envelope, the chunked upload is consumed and cannot be reused without starting the process over.

Using your chunked upload

To reference the chunked upload in your envelope, you’re going to need to add it as a document. The main caveat with this feature is that the file extension in your document’s name is what denotes the file type and how it is processed. Using a property like fileExtension will result in the file extension being ignored and an error message returned.

The chunkedUploadUri will be referenced in your envelope definitions.

"documents": [
 {
    "remoteUrl": “docusignchunkedupload://3216E4B2-XXXX-XXXX-XXXX-34CC91813EA2",
    "documentId": "1",
    "name": "TestDocument.txt"
 }

That's all you need to attach the chunked upload to your envelope.  Using this feature, you should be able to add documents to your envelopes ranging from 25 to 50MB. To see the potential of this feature, learn how to manage multiple chunked uploads for a single envelope. 

Additional resources

• eSignature REST API Reference: ChunkedUploads resource

• Docusign Developer Center

• Docusign Developers Community

• @DocusignDevs on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter