How to add attachments at envelope creation time

Question

I am creating an embedded solution. At some point in my app, the user can upload a file. I have a required attachment field in my template. If the user uploaded a file in my app, I want to attach it during envelope creation, otherwise I want the docusign signing view to force attachment. In either case, I want it to appear identical to the user receiving the final signed document (ie: as a separate attachment). I'm looking for XML examples of how to achieve this. This post had a recommended solution similar to what I'm looking to do, but there was no code: Attachments on iPad in iFrame docusign and this post referred to an example that might be what I want, but the link is broken: What is expected for the EnvelopeAttachment parameters of "Type" and "Label"?

or if someone could point me to the current location of:

http://www.docusign.com/content/e-signature-code-walkthrough-signer-attachments

Non-working example of what I'm looking for:

public void AddAttachment2Envelope(string envelopeID, byte[] attachment, string attachmentname)
{
    string url = baseURL + "/envelopes/" + envelopeID + "/documents";
    string requestBody =
    "--AAA" + "\r\n" +
    "Content-Type: application/xml" + "\r\n" +
    "Content-Disposition: form-data" +  "\r\n" +
    "<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">" +  "\r\n" +
    "<documents>" +  "\r\n" +
    "<document>" + "\r\n" +
    "<documentId>12345</documentId>" +  "\r\n" + //what is documentid here used for?
    "<name>" + attachmentname + "</name>" +  "\r\n" +
    "<order>1</order>" +  "\r\n" + 
    "</document>" +  "\r\n" +
    "</documents>" +  "\r\n" +
    "</envelopeDefinition>" +  "\r\n" +
    "--AAA" +  "\r\n" +
    "Content-Type: application/pdf" +  "\r\n" +
    "Content-Disposition: file; filename=\"String content\"; documentId=10" + "\r\n" + //what is documentid here used for?
    attachment.ToString() + "\r\n" +
    "--AAA";
    HttpWebRequest request = initializeRequest(url, "PUT", requestBody, email, password);
    request.ContentType = "multipart/form-data; boundary=AAA";
    string response = getResponseBody(request);
}

I've also tried the following without success:

public void AddAttachment2Envelope(string envelopeID, byte[] attachment, string attachmentname, Boolean bad)
{
    string ctype = "Content-Type: application/pdf";
    if (attachmentname.ToLower().EndsWith(".jpg"))
        ctype = "Content-Type: image/jpeg";
    else if (attachmentname.ToLower().EndsWith(".png"))
        ctype = "Content-Type: image/png";
    string url = baseURL + "/envelopes/" + envelopeID + "/documents/10";
    string requestBody =
    ctype + "\r\n" +
    "Content-Disposition: file; filename=\"" + attachmentname + "\"; documentId=10" + "\r\n" +
    System.Text.Encoding.Default.GetString(attachment) + "\r\n" + //System.Text.Encoding.Default.GetString(attachment)  //System.Convert.ToBase64String(attachment, 0, attachment.Length)
    "";
    HttpWebRequest request = initializeRequest(url, "PUT", requestBody, email, password);
    request.ContentType = ctype.Replace("Content-Type: ", "");
    request.Headers.Add("Content-Disposition", "file; filename=\"" + attachmentname + "\"; documentId=10");
    string response = getResponseBody(request);
}
public void AddAttachment2Envelope(string envelopeID, byte[] attachment, string attachmentname)
{
    string ctype = "Content-Type: application/pdf";
    if (attachmentname.ToLower().EndsWith(".jpg"))
        ctype = "Content-Type: image/jpeg";
    else if (attachmentname.ToLower().EndsWith(".png"))
        ctype = "Content-Type: image/png";
    string url = baseURL + "/envelopes/" + envelopeID + "/documents";
    string requestBody =
    "--AAA" + "\r\n" +
    "Content-Type: application/xml" + "\r\n" +
    "Content-Disposition: form-data" + "\r\n" +
    //"<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">" + "\r\n" +
    //"<documents>" + "\r\n" +
    "<document>" + "\r\n" +
    "<documentId>10</documentId>" + "\r\n" +
    "<name>" + attachmentname + "</name>" + "\r\n" +
    "<order>2</order>" + "\r\n" +
    //"<FileExtension>" + System.IO.Path.GetExtension(attachmentname).Replace(".", "").ToLower() + "</FileExtension>" + "\r\n" +
    "</document>" + "\r\n" +
    //"</documents>" + "\r\n" +
    //"</envelopeDefinition>" + "\r\n" +
    "--AAA" + "\r\n" +
    ctype + "\r\n" +
    "Content-Disposition: file; filename=\"" + attachmentname + "\"; documentId=10" + "\r\n" +
    System.Convert.ToBase64String(attachment, 0, attachment.Length) + "\r\n" + //System.Text.Encoding.Default.GetString(attachment)
    "--AAA--";
    HttpWebRequest request = initializeRequest(url, "PUT", requestBody, email, password);
    request.ContentType = "multipart/form-data; boundary=AAA";
    //request.Accept = "multipart/form-data;";
    string response = getResponseBody(request);
}
public void AddAttachment2Envelope(string envelopeID, byte[] attachment, string attachmentname, int bad)
{
    string url = baseURL + "/envelopes/" + envelopeID + "/documents";
    string requestBody =
    // "<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">" +  "\r\n" +
    // "<documents>" + "\r\n" +
    "<document>" + "\r\n" +
    "<documentId>10</documentId>" + "\r\n" +
    "<name>" + attachmentname + "</name>" + "\r\n" +
    "<order>2</order>" + "\r\n" +
    "<FileExtension>" + System.IO.Path.GetExtension(attachmentname).Replace(".", "").ToLower() + "</FileExtension>" + "\r\n" +
    "<documentBase64>" + System.Convert.ToBase64String(attachment, 0, attachment.Length) + "</documentBase64>" + "\r\n" +
    "</document>" + "\r\n" +
    // "</documents>" + "\r\n" +       
    // "</envelopeDefinition>" +  "\r\n" +
    "";
    //requestBody = requestBody.Replace("\r\n", "");
    HttpWebRequest request = initializeRequest(url, "PUT", requestBody, email, password);
    string response = getResponseBody(request);
}

Answer 1

So being careful with the wording of your question here- as mentioned "attachments" are referred to as "Signer attachments" in the DocuSign platform and those can only be added through signer attachment tabs for individual recipients.

On the other hand, we usually refer to "documents" as "Envelope Documents" and as mentioned you can add documents to an envelope when the envelope is in draft state:

REST API v2 Guide - Add Documents to Draft Envelope

This is a PUT call you want to make to the /accounts/{accountId}/envelopes/{envelopeId}/documents URL. Here is a full C# code sample (copied from the DocuSign API Walkthroughs):

using System; 
using System.IO;
using System.Net;
using System.Xml;
using System.Xml.Linq;

namespace DocuSignAPITest
{
    public class AddDocumentToEnvelope
    {
        public static void Main ()
        {
            //---------------------------------------------------------------------------------------------------
            // ENTER VALUES FOR THE FOLLOWING 6 VARIABLES:
            //---------------------------------------------------------------------------------------------------
            string username = "***";            // your account email
            string password = "***";            // your account password
            string integratorKey = "***";           // your account Integrator Key (found on Preferences -> API page)
            string documentName = "***";            // copy document with same name and extension into project directory (i.e. "test.pdf")
            string envelopeId = "***";              // GUID of envelope we will add document to
            string contentType = "application/pdf";     // default content type is PDF
            //---------------------------------------------------------------------------------------------------

            // additional variable declarations
            string baseURL = "";            // - we will retrieve this through the Login API call

            try {
                //============================================================================
                //  STEP 1 - Login API Call (used to retrieve your baseUrl)
                //============================================================================

                // Endpoint for Login api call (in demo environment):
                string url = "https://demo.docusign.net/restapi/v2/login_information";

                // set request url, method, and headers.  No body needed for login api call
                HttpWebRequest request = initializeRequest( url, "GET", null, username, password, integratorKey);

                // read the http response
                string response = getResponseBody(request);

                // parse baseUrl from response body
                baseURL = parseDataFromResponse(response, "baseUrl");

                //--- display results
                Console.WriteLine("\nAPI Call Result: \n\n" + prettyPrintXml(response));

                //============================================================================
                //  STEP 2 - Add document to draft envelope
                //============================================================================

                // append "/envelopes/{envelopeId}/documents" to baseURL
                url = baseURL + "/envelopes/" + envelopeId + "/documents";

                // construct the request body 
                string jsonBody = 
                    "{\"documents\": [" + 
                        "{\"documentId\": \"2\"," +
                        "\"name\": \"test.pdf\"," + 
                        "\"order\": \"2\"" +
                        "}]" +
                    "}";

                Console.WriteLine("\nJSON: \n\n" + jsonBody);

                // set request url, method, headers.  Don't set the body yet, we'll set that separelty after
                // we read the document bytes and configure the rest of the multipart/form-data request
                request = initializeRequest( url, "PUT", null, username, password, integratorKey);

                // some extra config for this api call
                configureMultiPartFormDataRequest(request, jsonBody, documentName, contentType);

                // read the http response
                response = getResponseBody(request);

                //--- display results
                Console.WriteLine("\nAPI Call Result: \n\n" + prettyPrintXml(response));
//              Console.WriteLine("\nAPI Call Result: \n\n" + response);
            }
            catch (WebException e) {
                using (WebResponse response = e.Response) {
                    HttpWebResponse httpResponse = (HttpWebResponse)response;
                    Console.WriteLine("Error code: {0}", httpResponse.StatusCode);
                    using (Stream data = response.GetResponseStream())
                    {
                        string text = new StreamReader(data).ReadToEnd();
                        Console.WriteLine(prettyPrintXml(text));
                    }
                }
            }
        } // end main()

        //***********************************************************************************************
        // --- HELPER FUNCTIONS ---
        //***********************************************************************************************
        public static HttpWebRequest initializeRequest(string url, string method, string body, string email, string password, string intKey)
        {
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create (url);
            request.Method = method;
            addRequestHeaders( request, email, password, intKey );
            if( body != null )
                addRequestBody(request, body);
            return request;
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static void addRequestHeaders(HttpWebRequest request, string email, string password, string intKey)
        {
            // authentication header can be in JSON or XML format.  XML used for this walkthrough:
            string authenticateStr = 
                "<DocuSignCredentials>" + 
                    "<Username>" + email + "</Username>" +
                    "<Password>" + password + "</Password>" + 
                    "<IntegratorKey>" + intKey + "</IntegratorKey>" + 
                    "</DocuSignCredentials>";
            request.Headers.Add ("X-DocuSign-Authentication", authenticateStr);
            request.Accept = "application/xml";
            request.ContentType = "application/xml";
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static void addRequestBody(HttpWebRequest request, string requestBody)
        {
            // create byte array out of request body and add to the request object
            byte[] body = System.Text.Encoding.UTF8.GetBytes (requestBody);
            Stream dataStream = request.GetRequestStream ();
            dataStream.Write (body, 0, requestBody.Length);
            dataStream.Close ();
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static void configureMultiPartFormDataRequest(HttpWebRequest request, string jsonBody, string docName, string contentType)
        {
            // overwrite the default content-type header and set a boundary marker
            request.ContentType = "multipart/form-data; boundary=BOUNDARY";

            // start building the multipart request body
            string requestBodyStart = "\r\n\r\n--BOUNDARY\r\n" +
                "Content-Type: application/json\r\n" +
                    "Content-Disposition: form-data\r\n" +
                    "\r\n" +
                    jsonBody + "\r\n\r\n--BOUNDARY\r\n" +   // our json formatted request body
                    "Content-Type: " + contentType + "\r\n" +
                    "Content-Disposition: file; filename=\"" + docName + "\"; documentId=2\r\n" +
                    "\r\n";
            string requestBodyEnd = "\r\n--BOUNDARY--\r\n\r\n";

            // read contents of provided document into the request stream
            FileStream fileStream = File.OpenRead(docName);

            // write the body of the request
            byte[] bodyStart = System.Text.Encoding.UTF8.GetBytes(requestBodyStart.ToString());
            byte[] bodyEnd = System.Text.Encoding.UTF8.GetBytes(requestBodyEnd.ToString());
            Stream dataStream = request.GetRequestStream();
            dataStream.Write(bodyStart, 0, requestBodyStart.ToString().Length);

            // Read the file contents and write them to the request stream.  We read in blocks of 4096 bytes
            byte[] buf = new byte[4096];
            int len;
            while ((len = fileStream.Read(buf, 0, 4096) ) > 0) {
                dataStream.Write(buf, 0, len);
            }
            dataStream.Write(bodyEnd, 0, requestBodyEnd.ToString().Length);
            dataStream.Close();
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static string getResponseBody(HttpWebRequest request)
        {
            // read the response stream into a local string
            HttpWebResponse webResponse = (HttpWebResponse)request.GetResponse ();
            StreamReader sr = new StreamReader(webResponse.GetResponseStream());
            string responseText = sr.ReadToEnd();
            return responseText;
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static string parseDataFromResponse(string response, string searchToken)
        {
            // look for "searchToken" in the response body and parse its value
            using (XmlReader reader = XmlReader.Create(new StringReader(response))) {
                while (reader.Read()) {
                    if((reader.NodeType == XmlNodeType.Element) && (reader.Name == searchToken))
                        return reader.ReadString();
                }
            }
            return null;
        }
        /////////////////////////////////////////////////////////////////////////////////////////////////////////
        public static string prettyPrintXml(string xml)
        {
            // print nicely formatted xml
            try {
                XDocument doc = XDocument.Parse(xml);
                return doc.ToString();
            }
            catch (Exception) {
                return xml;
            }
        }
    } // end class
} // end namespace