Code Walkthrough _ Retrieving Documents from DocuSign

nicholasareed edited this page Aug 2, 2011 · 1 revision

In this walkthrough we will cover the different methods that you can use to retrieve documents from DocuSign.
You should already be comfortable with working with webservices to follow along here. There will be code samples displayed in both C# (using .net 3.5) and PHP, but you should already know how to get your local proxy class setup and your credentials entered.

The Documents

Once you send a DocuSign envelope, and the Recipients sign it, the next step is usually to retrieve the signed documents. While you can leave them in the DocuSign account, many implementors want their systems to keep copies locally. Additionally, DocuSign provides a document called the Envelope Certificate that displays key data about the signing ceremony, and this document is often kept locally along with the signed documents to provide evidence of the transaction.


The first method we’ll discuss is the RequestPDF method. This method takes an EnvelopeID as a parameter, and returns a structure that contains the EnvelopeID and a PDF file. The PDF File contains the entire contents of the envelope, so if you sent in an envelope with five different documents in it, the resulting PDF will contain all five documents in order.

Here’s an example of using the RequestPDF method:

	APIServiceSoapClient apiService = new APIServiceSoapClient();
	apiService.ClientCredentials.UserName.UserName = "Your DocuSign UserName here";
	apiService.ClientCredentials.UserName.Password = "Your DocuSign Password here";
	string envelopeID = "Some EnvelopeID";
	EnvelopePDF envPDF = apiService.RequestPDF(envelopeID);

For the php code, we are assuming that we have the wsdl file cached locally in the indicated location.

	$api_endpoint= "";
	$api_wsdl = "api/APIService.wsdl";
	$api_options =  array('location'=>$api_endpoint,'trace'=>true,'features' => SOAP_SINGLE_ELEMENT_ARRAYS);
	$api = new APIService($api_wsdl, $api_options);
	$api->setCredentials("Your DocuSign UserName here", "Your DocuSign Password here");

	$RequestPDFParam = new RequestPDF();
	$RequestPDFParam->EnvelopeID = $envelopeID;
	$result = $api->RequestPDF($RequestPDFParam);
	$envPDF = $result->RequestPDFResult;

Now that you have the EnvelopePDF object, you can access the raw bytes via the EnvelopePDF.PDFBytes accessor and write them out to a file ( or a database blob field, etc)

	System.IO.File.WriteAllBytes(AppDomain.CurrentDomain.BaseDirectory + @"\envelope.pdf", envPDF.PDFBytes);
	file_put_contents("./envelope.pdf", $envPDF->PDFBytes);


The RequestDocumentPDFs is used when you want to get all of the Envelope’s contents back as individual documents. This is very useful when you have a package of documents that are signed and then need to be routed to different departments after signing. For example, using the Auto Insurance example, you might have an Electronic Funds Transfer authorization form in the Envelope along with the Insurance Application, and post signing you need to send the EFT form to finance and the Application to whereever Insurance applications go to.
This method also includes the Envelope Certificate, so if you want this you have to use this method rather than RequestPDF.

The returned data from this call is a DocumentPDFs object, which contains the EnvelopeID and an array of DocumentPDF objects – 1 for each original document, plus the Envelope Certificate.

Assuming that you already have your api proxy setup, here’s the code:

	string envelopeID = "Some EnvelopeID";
	DocumentPDFs docPDFs = apiService.RequestDocumentPDFs(envelopeID);
	$RequestDocumentPDFsParam = new RequestDocumentPDFs();
	$RequestDocumentPDFsParam->EnvelopeID = $envelopeID;
	$result = $api->RequestDocumentPDFs($RequestDocumentPDFsParam);
	$docPDFs = $result->RequestDocumentPDFsResult;

With the DocumentPDFs object, you will need to iterate the array of DocumentPDF objects, and access the PDFBytes property on each DocumentPDF. You will also see some other properties there – like ‘Name’, which will contain the name of the file when it was sent in the envelope. For the Envelope Certificate, the Name will be ‘Summary’. Remember that the name will be whatever it was set to, so if you are saving it out to the filesystem you will need to add the ‘pdf’ extension to the Name.

	foreach (DocumentPDF doc in docPDFs.DocumentPDF)
		System.IO.File.WriteAllBytes(AppDomain.CurrentDomain.BaseDirectory + @"\" + doc.Name + ".pdf", doc.PDFBytes);
	foreach($docPDFs->DocumentPDF as $doc){
		file_put_contents("./" . $doc->Name . ".pdf", $doc->PDFBytes);

You will also see a couple of properties – currently DocumentID and DocumentType – that will not be populated. This is because the DocumentPDFs object is used as the return value both for the RequestDocumentPDFs method and the RequestDocumentPDFsEx method.


This method is a variant of the RequestDocumentPDFs method that returns additional elements in the response. The exact elements that can be returned will change over time, so if you are using this method you need to be sure that your code won’t break if it encounters an unexpected property here. Currently the DocumentID and DocumentType properties are being returned but there may be additional elements here in the future.
Also note that these additional elements return data that would have been supplied at the time the envelope was created. If you did not specifically add this data to the envelope, it will not be there when you call this method.

Account Options

You may also have your account configured to pass back additional information in the metadata elements of the PDF file. Please see the API documentation for more information about this ( see the Rules for Using RequestDocumentPDFs on page 79).

So that’s how to get your documents back out of DocuSign. If you have trouble using these API methods, please use the DocuSign DevCenter forums for assistance.