Docusign: Getting an embedded recipient view witho

Question

I have scenario where I need users coming on a web site to upload a document and another user has to sign this document.

What I have done till now:

Step1: Login through email,password and Integratorkey

function(next) {
        var url = "https://demo.docusign.net/restapi/v2/login_information";
        var body = "";  // no request body for login api call

        // set request url, method, body, and headers
        var options = initializeRequest(url, "GET", body, email, password);

        // send the request...
        request(options, function(err, res, body) {
            if(!parseResponseBody(err, res, body)) {
                return;
            }
            baseUrl = JSON.parse(body).loginAccounts[0].baseUrl;
            next(null); // call next function
        });
    },

I'm getting valid response including valid accountID.

Step2: Now I'm uploading a document through this api

function(next) {    
        var url = baseUrl + "/envelopes";
        // following request body will place 1 signature tab 100 pixels to the right and
        // 100 pixels down from the top left of the document that you send in the request
        var body = {
            "recipients": {
                "signers": [{
                    "email": recipientEmail,
                    "name": recipientName,
                    "recipientId": 1,
                    "tabs": {
                        "signHereTabs": [{
                            "xPosition": "100",
                            "yPosition": "100",
                            "documentId": "1",
                            "pageNumber": "1"                                                                                   
                        }]
                    }
                }]
            },
            "emailSubject": 'checkkkkkkkk API !!!!!',
            "documents": [{
                "name": "abc.pdf",
                "documentId": 1,
            }],
            "status": "sent",
        };

        // set request url, method, body, and headers
        var options = initializeRequest(url, "POST", body, email, password);

        // change default Content-Type header from "application/json" to "multipart/form-data"
        options.headers["Content-Type"] = "multipart/form-data";

        // configure a multipart http request with JSON body and document bytes
        options.multipart = [{
                    "Content-Type": "application/json",
                    "Content-Disposition": "form-data",
                    "body": JSON.stringify(body),
                }, {
                    "Content-Type": "application/pdf",
                    'Content-Disposition': 'file; filename="' + documentName + '"; documentId=1',
                    "body": fs.readFileSync(documentName),
                }
        ];

        // send the request...
        request(options, function(err, res, body) {
            parseResponseBody(err, res, body);
            envelopeId = JSON.parse(body).envelopeId;
            console.log(envelopeId);
            next(null);
        });

    }, 

Here in response I'm getting a valid EnvelopeID(for sure!!)

Step3: Now I want another user(as provided above recipientEmail/name) to sign this document in embed view on my website for this I'm using this API http://iodocs.docusign.com/APIWalkthrough/embeddedSigning#js but this requires a templateId and role which was not returned to us by the above used APIs. this needs manual effort to upload template and get templateID which is not possible in my scenario because I want everything to be automatic.

Can anyone direct me how to proceed with embedded signing.

DocuSignAPI

Answer 1

If you want the signer to access the Envelope via your site, then the signer needs to be specified as an "embedded/captive" signer when you create the Envelope. This is done by setting the clientUserId property on the Recipient object in the Create Envelope API Request. (This property can be set to whatever value you choose -- max length 100 characters, but your application needs to keep track of it, because you'll need it to launch the recipient's signing session when they come to your site.)

So, it works like this:

1. Your application creates the Envelope via the "Create Envelope" API request, setting the clientUserId property for the Recipient (Signer) to indicate that they'll be accessing the Envelope via your application. For the sake of this example, let's say you set clientUserId to 1234.

   "signers": [{ "email": "[e-mail]", "name": "Jane Doe", "recipientId": 1, "clientUserId": 1234 }]

2. Your application notifies the signer (via email) that their signature is required on document(s); the email provides information regarding how they can access the Envelope (i.e., sign the document(s)) via your site. (DocuSign will not send "signing invitation" emails to recipients that are specified as embedded/captive.)

3. Signer follows directions in the email your application sent them, and visits your site to sign their document(s). When the signer is ready to sign, your application submits a "POST Recipient View" API request to get the URL that will launch the DocuSign signing session for the specified recipient. The request looks like this:

.

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{{envelopeId}}/views/recipient

{
     "authenticationMethod": "Email",
     "clientUserId": "1234",
     "userName": "Jane Doe",
     "email": "[e-mail]",
     "returnUrl": "URLInYourAppThatDocuSignRedirectsToWhenDocuSignSessionIsCompleted"
}

The response to this request will contain a URL that your application can use to launch the recipient's signing session.

Answer 2

Here is a FULL working sample in Node.js of what you are trying to accomplish. What you want to do is combine the API Walkthrough that sends a signature request on a document (so that it's not using template) and combine that with the third call in the Embedded Signing api walkthrough.

To add an Embedded recipient to an envelope you need to set their clientUserId property to any user-configurable value. For instance, you could set it to just "1", or "1234", or "1a2b3c". In my code below I have set it to "1001" to highlight that you can set it to whatever you like, you just need to keep track of it. One important note: You must make sure that when requesting the Embedded Signing URL for the recipient that you reference the same exact clientUserId that you set when you initially added them to the envelope (1001 in the below example).

Here's the code:

// To run this sample
//  1. Copy the file to your local machine and give .js extension (i.e. example.js)
//  2. Change "***" to appropriate values
//  3. Install async and request packages
//     npm install async
//     npm install request
//  4. execute
//     node example.js 
//

var     async = require("async"),       // async module
        request = require("request"),       // request module
        fs = require("fs");         // fs module

var     email = "***",              // your account email
        password = "***",           // your account password
        integratorKey = "***",      // your Integrator Key (found on the Preferences -> API page)
        recipientName = "***",      // recipient (signer) name
        recipientEmail = "***",     // recipient email address  
        documentName = "***",       // copy document with this name into same directory!
        envelopeId = "",            // will retrieve this from second api call
        baseUrl = "";               // retrieved through the Login call

async.waterfall(
  [
    /////////////////////////////////////////////////////////////////////////////////////
    // Step 1: Login (used to retrieve your accountId and baseUrl)
    /////////////////////////////////////////////////////////////////////////////////////
    function(next) {
        var url = "https://demo.docusign.net/restapi/v2/login_information";
        var body = "";  // no request body for login api call

        // set request url, method, body, and headers
        var options = initializeRequest(url, "GET", body, email, password);

        // send the request...
        request(options, function(err, res, body) {
            if(!parseResponseBody(err, res, body)) {
                return;
            }
            baseUrl = JSON.parse(body).loginAccounts[0].baseUrl;
            next(null); // call next function
        });
    },

    /////////////////////////////////////////////////////////////////////////////////////
    // Step 2: Create Envelope with Embedded Recipient (need to set |clientUserId| property)
    /////////////////////////////////////////////////////////////////////////////////////
    function(next) {    
        var url = baseUrl + "/envelopes";
        // following request body will place 1 signature tab 100 pixels to the right and
        // 100 pixels down from the top left of the document that you send in the request
        var body = {
            "recipients": {
                "signers": [{
                    "email": recipientEmail,
                    "name": recipientName,
                    "recipientId": 1,
                    "clientUserId": "1001",     //Required for embedded recipient
                    "tabs": {
                        "signHereTabs": [{
                            "xPosition": "100",
                            "yPosition": "100",
                            "documentId": "1",
                            "pageNumber": "1"                                                                                   
                        }]
                    }
                }]
            },
            "emailSubject": 'DocuSign API - Signature Request on Document Call',
            "documents": [{
                "name": documentName,
                "documentId": 1,
            }],
            "status": "sent"
        };

        // set request url, method, body, and headers
        var options = initializeRequest(url, "POST", body, email, password);

        // change default Content-Type header from "application/json" to "multipart/form-data"
        options.headers["Content-Type"] = "multipart/form-data";

        // configure a multipart http request with JSON body and document bytes
        options.multipart = [{
                    "Content-Type": "application/json",
                    "Content-Disposition": "form-data",
                    "body": JSON.stringify(body),
                }, {
                    "Content-Type": "application/pdf",
                    'Content-Disposition': 'file; filename="' + documentName + '"; documentId=1',
                    "body": fs.readFileSync(documentName),
                }
        ];

        // send the request...
        request(options, function(err, res, body) {
            if(!parseResponseBody(err, res, body)) {
                return;
            }
            envelopeId = JSON.parse(body).envelopeId;
            next(null); // call next function
        });
    }, // end function    

    /////////////////////////////////////////////////////////////////////////////////////
    // Step 3: Generate the Embedded Signing URL
    /////////////////////////////////////////////////////////////////////////////////////

    function(next) {
        var url = baseUrl + "/envelopes/" + envelopeId + "/views/recipient";
        var method = "POST";
        var body = JSON.stringify({
                "returnUrl": "http://www.docusign.com/devcenter",
                "authenticationMethod": "email",                    
                "email": email,                 
                "userName": recipientName,      
                "clientUserId": "1001", // must match clientUserId in step 2!
            });  

        // set request url, method, body, and headers
        var options = initializeRequest(url, "POST", body, email, password);

        // send the request...
        request(options, function(err, res, body) {
            if(!parseResponseBody(err, res, body))
                return;
            else
                console.log("\nNavigate to the above URL to start the Embedded Signing workflow...");
        });
    }
]);

//***********************************************************************************************
// --- HELPER FUNCTIONS ---
//***********************************************************************************************
function initializeRequest(url, method, body, email, password) {    
    var options = {
        "method": method,
        "uri": url,
        "body": body,
        "headers": {}
    };
    addRequestHeaders(options, email, password);
    return options;
}

///////////////////////////////////////////////////////////////////////////////////////////////
function addRequestHeaders(options, email, password) {  
    // JSON formatted authentication header (XML format allowed as well)
    dsAuthHeader = JSON.stringify({
        "Username": email,
        "Password": password, 
        "IntegratorKey": integratorKey  // global
    });
    // DocuSign authorization header
    options.headers["X-DocuSign-Authentication"] = dsAuthHeader;
}

///////////////////////////////////////////////////////////////////////////////////////////////
function parseResponseBody(err, res, body) {
    console.log("\r\nAPI Call Result: \r\n", JSON.parse(body));
    if( res.statusCode != 200 && res.statusCode != 201) { // success statuses
        console.log("Error calling webservice, status is: ", res.statusCode);
        console.log("\r\n", err);
        return false;
    }
    return true;
}