Code Walkthrough _ Signer Attachments

nicholasareed edited this page Aug 2, 2011 · 1 revision
  1. Signer Attachment Overview
    In this electronic signature code walkthrough, we will cover a powerful aspect of the DocuSign API: signer attachments. Signer attachments allow the sender to indicate that the signer has an important document to contribute to the envelope. Once the signer receives the envelope for signing, the signer clicks on a SignerAttachment tab and is allowed to upload or fax in the document. Once the signer(s) complete signing, the completed envelope includes the signer’s attachments!

Let’s start with an example of when you would use this feature. Consider the scenario of signing a contract for the sale of a house. The buyer wants to make sure that the house is in good condition, so the buyer would like the seller to provide the inspection document with the contract. Therefore, the executor of the contract requires the seller to upload the inspection document as a signer attachment when creating the envelope. As long as the routing order specifies that the seller must sign before the buyer, the buyer will be able to review the house inspection document and decide whether or not to sign. The process might look something like this:

Creating a signer attachment using the member console is easy – just add it like you would any other document, and add a signer attachment tab! However, let’s examine how to do this programmatically.

##The Code
You will want to create your envelope with recipients as you normally do (for a review of how to create envelopes, please look at this DocuSign API code walkthrough). The difference comes when adding your documents to the envelope. For the purposes of the code walkthrough, envelope will be the envelope you constructed, the recipient with an ID of 1 will be the seller, and the recipient with an ID of 2 will be the buyer.

First, we will create one document with the primary content. In the scenario above, this would be the sales contract.

DocuSignWeb.Document primaryContract = new DocuSignWeb.Document();
primaryContract.PDFBytes = System.IO.File.ReadAllBytes(Server.MapPath("resources/primaryContract.pdf"));
primaryContract.ID = "1";
primaryContract.Name = "Primary Contract";

Second, we will add a signer attachment. In the scenario above, this would be the house inspection document. We create the document as we did above, and use a placeholder PDF for the look and feel of the document. However, pay close attention to the AttachmentDescription; this is required for the signer to be able to upload a document. You will want to give your signers specific instructions on what they should attach to the document.

DocuSignWeb.Document signerAttachment = new DocuSignWeb.Document();
signerAttachment.PDFBytes = System.IO.File.ReadAllBytes(Server.MapPath("resources/attachmentPlaceholder.pdf"));
signerAttachment.ID = "2";
signerAttachment.Name = "Attachment Section";
signerAttachment.AttachmentDescription = "Please attach the home inspection here.";

Now that we have our documents, let’s attach them to the envelope.

envelope.Documents = new DocuSignWeb.Document[] { primaryContract, signerAttachment };

However, providing an attachment description is not quite enough. You also must construct a SignerAttachment tab for the signer attachment document, as shown below. Please note the SignerAttachment TabTypeCode. Clicking on this tab opens up a dialog for the signer, prompting them to include their document.

DocuSignWeb.Tab attachTab = new DocuSignWeb.Tab();
attachTab.RecipientID = "1";
attachTab.PageNumber = "1";
attachTab.Name = "Signer Attachment";
attachTab.DocumentID = "2";
attachTab.TabLabel = "Signer Attachment";
attachTab.Type = DocuSignWeb.TabTypeCode.SignerAttachment;
attachTab.XPosition = "250";
attachTab.YPosition = "50";

For good measure, let’s construct two SignHere tabs for the seller and the buyer on the primary contract.

DocuSignWeb.Tab signTabSeller = new DocuSignWeb.Tab();
signTabSeller.RecipientID = "1";
signTabSeller.PageNumber = "1";
signTabSeller.Name = "Sign Here";
signTabSeller.DocumentID = "1";
signTabSeller.TabLabel = "Sign Here";
signTabSeller.Type = DocuSignWeb.TabTypeCode.SignHere;
signTabSeller.XPosition = "125";
signTabSeller.YPosition = "670";

DocuSignWeb.Tab signTabBuyer = new DocuSignWeb.Tab();
signTabBuyer.RecipientID = "2";
signTabBuyer.PageNumber = "1";
signTabBuyer.Name = "Sign Here";
signTabBuyer.DocumentID = "1";
signTabBuyer.TabLabel = "Sign Here";
signTabBuyer.Type = DocuSignWeb.TabTypeCode.SignHere;
signTabBuyer.XPosition = "200";
signTabBuyer.YPosition = "670";

Lastly, add these tabs to the envelope that you constructed beforehand, and then send the envelope using the API Proxy.

envelope.Tabs = new DocuSignWeb.Tab[] { attachTab, signTabSeller, signTabBuyer };

DocuSignWeb.APIServiceSoapClient apiService = new DocuSignWeb.APIServiceSoapClient();
apiService.ClientCredentials.UserName.UserName = "Your DocuSign UserName here";
apiService.ClientCredentials.UserName.Password = "Your DocuSign Password here";
DocuSignWeb.EnvelopeStatus envStatus = apiService.CreateAndSendEnvelope(envelope);

After sending, the recipient should have received an email from DocuSign with a link that will initiate the signing process. With the above code, the first recipient (the seller) will be prompted to sign the primary contract, and upload the house inspection.

##Words of note about Signer Attachments:

For each signer attachment document, you may only place one signer attachment tab for each recipient. Feel free to add more signer attachment documents to accommodate additional signer attachment tabs.

You must assign a value to the PDFBytes field of a signer attachment document. Think of it as a document where you can place extra information, or include your company’s branding.

Now you’re all set to start sending envelopes out with signer attachments. Happy attaching!