Blog
Home/

From the Trenches: Chunked uploads

Matt King
Matt KingDeveloper Support Engineer
Summary3 min read

Learn how to work with document attachments larger than 25MB.

      • Creating a chunked upload
      • Using your chunked upload
      • Additional resources

      Table of contents

      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

      Matt King
      Matt KingDeveloper Support Engineer

      Matt King is a senior member of the Developer Support team and has been with Docusign for about 5 years. He specializes in assisting customers with our various APIs, SDKs, and code examples.

      More posts from this author

      Related posts

      • Developer Support Articles

        From the Trenches: Multiple chunked uploads

        Matt King
        Matt King
      • From the Trenches: API pagination

        Steve DiCicco
        Steve DiCicco
      • From the Trenches: Testing Docusign Connect with ngrok

        Ivan Dinkov
        Ivan Dinkov

      From the Trenches: Multiple chunked uploads

      Matt King
      Matt King

      From the Trenches: API pagination

      Steve DiCicco
      Steve DiCicco

      From the Trenches: Testing Docusign Connect with ngrok

      Ivan Dinkov
      Ivan Dinkov

      Discover what's new with Docusign IAM or start with eSignature for free

      Explore Docusign IAMTry eSignature for Free
      Person smiling while presenting