Common API Tasks🐈: Downloading Documents
Welcome to the sixth installment of our Common API Tasks blog series. I hope by now you had a chance to read any of the prior posts in the Common API Tasks series. This series is all about helping you, the developers using DocuSign APIs, to complete popular tasks that are commonly used in applications. In this post, I’m going to talk about how you use our eSignature REST API to retrieve documents from a completed envelope.
First, let’s review some basics. An envelope in DocuSign must contain one or more documents and specify one or more recipients. When all recipients are finished acting on the documents (signing, viewing, etc.) and no one has declined or voided the envelope, the envelope status is changed to completed. A completed envelope is an important concept in DocuSign. Completed envelopes cannot be modified; they are locked. They can still be voided, but that’s about the only way to change their status. When the envelope is completed, the most common thing you may wish to do with it is retrieve the signed documents.
Decisions, decisions
When downloaded individually, the signed documents are always downloaded as PDF files. Even if you used responsive signing so that the recipients signed an HTML form instead of PDF, the DocuSign system still produces a PDF as the final artifact of the eSignature process. There are a couple of things you still get to choose. First, you need to decide if you want to select a specific document or you want to download all of them. Second, you have the option of downloading the documents separately or combined. If you choose to download a combined file, you can either get a single large PDF file that includes all your signed documents one after the other, or you can get a ZIP file that contains the documents inside. In either case the Certificate of Completion (CoC) is also included as the final document. The Certificate of Completion is a document that outlines all the activity pertaining to this particular envelope. It is commonly used to ensure the legality of the signatures.
More details about the specific API endpoint used to download documents from an envelope can be found in our Developer Center.
Code Time
As usual in this blog series, I will provide code snippets in our six SDK languages. This code shows three different calls to the GetDocument() method. The first one is used to obtain a ZIP file containing all signed documents including the CoC. The second one is used to produce a PDF that is a combined file including all signed documents as well as the CoC. The third shows how to retrieve a single document based on the documentId.
C#
// You would need to obtain an accessToken using your chosen auth flow
var apiClient = new ApiClient(basePath);
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
var envelopesApi = new EnvelopesApi(apiClient);
string accountId; // accountId for your DocuSign account
string envelopeId; // envelopeId that you are working on
// produce a ZIP file with all documents including the CoC
Stream results1 = envelopesApi.GetDocument(accountId, envelopeId, "archive");
// produce a PDF combining all signed documents as well as the CoC
Stream results2 = envelopesApi.GetDocument(accountId, envelopeId, "combined");
// produce a particular document with documentId "1"
Stream results3 = envelopesApi.GetDocument(accountId, envelopeId, "1");
//TODO - use Stream to write or send the file for your use
Java
// You would need to obtain an accessToken using your chosen auth flow
Configuration config = new Configuration(new ApiClient(basePath));
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(config);
String accountId; // accountId for your DocuSign account
String envelopeId; // envelopeId that you are working on
// produce a ZIP file with all documents including the CoC
byte[] results1 = envelopesApi.GetDocument(accountId, envelopeId, "archive");
// produce a PDF combining all signed documents as well as the CoC
byte[] results2 = envelopesApi.GetDocument(accountId, envelopeId, "combined");
// produce a particular document with documentId "1"
byte[] results3 = envelopesApi.GetDocument(accountId, envelopeId, "1");
//TODO - use byte array to write or send the file for your use
Node.js
// You would need to obtain an accessToken using your chosen auth flow
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
var accountId; // accountId for your DocuSign account
var envelopeId; // envelopeId that you are working on
// produce a ZIP file with all documents including the CoC
let results1 = await envelopesApi.GetDocument(accountId, envelopeId, 'archive', null);
// produce a PDF combining all signed documents as well as the CoC
let results2 = await envelopesApi.GetDocument(accountId, envelopeId, 'combined', null);
// produce a particular document with documentId '1'
let results3 = await envelopesApi.GetDocument(accountId, envelopeId, '1', null);
//TODO - use byte array to write or send the file for your use
PHP
# You would need to obtain an accessToken using your chosen auth flow
$api_client = new \DocuSign\eSign\client\ApiClient($base_path);
$config = new \DocuSign\eSign\Model\Configuration($api_client);
$config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
$envelopes_api = new \DocuSign\Api\EnvelopesApi($config);
$account_id; # accountId for your DocuSign account
$envelope_id; # envelopeId that you are working on
# produce a ZIP file with all documents including the CoC
$results1 = $envelopes_api->getDocument($account_id, $envelope_id, 'archive');
# produce a PDF combining all signed documents as well as the CoC
$results2 = $envelopes_api->getDocument($account_id, $envelope_id, 'combined');
# produce a particular document with documentId '1'
$results3 = $envelopes_api->getDocument($account_id, $envelope_id, '1');
#TODO - use results file to write or send the file for your use
Python
# You would need to obtain an accessToken using your chosen auth flow
api_client = ApiClient()
api_client.host = base_path
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
envelopes_api = EnvelopesApi(api_client)
account_id # accountId for your DocuSign account
envelope_id # envelopeId that you are working on
# produce a ZIP file with all documents including the CoC
results1 = envelopes_api.get_document(account_id, 'archive', envelope_id)
# produce a PDF combining all signed documents as well as the CoC
results2 = envelopes_api.get_document(account_id, 'combined', envelope_id)
# produce a particular document with documentId '1'
results3 = envelopes_api.get_document(account_id, '1', envelope_id)
#TODO - use results file to write or send the file for your use
Ruby
# You would need to obtain an accessToken using your chosen auth flow
config = DocuSign_eSign::Configuration.new
config.host = base_path
api_client = DocuSign_eSign::ApiClient.new config
api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
envelopes_api = DocuSign_eSign::EnvelopesApi.new api_client
account_id # accountId for your DocuSign account
envelope_id # envelopeId that you are working on
# produce a ZIP file with all documents including the CoC
results1 = envelopes_api.get_document(account_id, 'archive', envelope_id)
# produce a PDF combining all signed documents as well as the CoC
results2 = envelopes_api.get_document(account_id, 'combined', envelope_id)
# produce a particular document with documentId '1'
results3 = envelopes_api.get_document(account_id, '1', envelope_id)
#TODO - use results file to write or send the file for your use
Note: You can call these API endpoints on envelopes that are not yet complete and you will be able to retrieve these documents as well, showing their in-progress view. However, the most common use of these calls is to retrieve signed documents.
Until we meet again, if you have any questions or suggestions feel free to email me.
