Docusign: creating envelopes through templates with the REST API and prefilling tags

Question

I'm integrating Docusign so that recipients can see their envelopes embedded on my site. I first create the envelope with the api, and I'm attempting to prefill Data Fields using dynamic data.

As far as I can tell, there's nothing wrong with my json that I'm using to create the envelopes. None of the other solutions on StackOverflow to this issue have helped. My json looks like this (which I send to https://demo.docusign.net/restapi/v2/accounts/360734/envelopes):

{
   "status": "sent",
   "emailBlurb": "Please sign the document.",
   "emailSubject": "Please sign your agreement",
   "templateId": "TEMPLATE_ID",
   "templateRoles": [
     {
       "clientUserId": "EMAIL",
       "name": "NAME",
       "email": "EMAIL",
       "roleName": "Signer1",
       "tabs": {
         "textTabs": [
           {
             "tabLabel": "address",
             "value": "ADDRESS "
           },
           {
             "tabLabel": "multi_address",
             "value": "ADDRESSES"
           }
         ]
       }
     },
     {
       "name": "ANOTHER NAME",
       "email": "ANOTHER EMAIL",
       "roleName": "Random1"
     }
   ]
 }

And I get the following response:

{
   "envelopeId": "ENVELOPE_ID",
   "uri": "/envelopes/ENVELOPE_ID",
   "statusDateTime": "2013-10-25T01:20:55.6750772Z",
   "status": "sent"
}

I then get the link to show the client by posting to https://demo.docusign.net/restapi/v2/accounts/360734/envelopes/ENVELOPE_ID/views/recipient

{
  "authenticationMethod": "email",
  "clientUserId": "EMAIL",
  "email": "EMAIL",
  "returnUrl": "MYURL",
  "userName": "NAME"
}

And I get this response:

 {
   "url": "https://demo.docusign.net/Member/StartInSession.aspx?t=REDACTED"
 }

This follows the example seen here: https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013/blob/master/example2.json

After creating the envelope this way, it appears that the tags do not prefill. When I view the envelope embedded on my site, nothing is filled. I'm certain the tabLabels are correct. Everything otherwise seems to be working okay. Is there some kind of setting I'm missing?

UPDATE Looks like it could be a bug! All I change is the role name and it works!

 {
   "status": "sent",
   "emailBlurb": "Please sign the document.",
   "emailSubject": "Please sign your agreement",
   "templateId": "TEMPLATE_ID",
   "templateRoles": [
     {
       "clientUserId": "EMAIL",
       "name": "NAME",
       "email": "EMAIL",
       "roleName": "Signer1",
       "tabs": {
         "textTabs": [
           {
             "tabLabel": "address",
             "value": "ADDRESS "
           },
           {
             "tabLabel": "multi_address",
             "value": "ADDRESSES"
           }
         ]
       }
     },
     {
       "name": "ANOTHER NAME",
       "email": "ANOTHER EMAIL",
       "roleName": "Signer2"
     }
   ]
 }

And it populated! It seems if I start the role name with anything other than Signer it doesn't work. Weird!

And yes, I'm changing the role name on Docusign from Random1 to Signer2, in this case. For example, Signer3 also worked.

Answer 1

Your question says your submitting that JSON to the "Get Recipient View" resource:

https://demo.docusign.net/restapi/v2/accounts/ACCOUNT_ID/envelopes/ENVELOPE_ID/views/recipient)

...but that JSON looks like what you use in the "Create Envelope" request, not the "Get Recipient View" request. So, let me start by clarifying the process of facilitating Embedded/captive signing (i.e., presenting the recipient's envelope within your site). Doing so is a two-step process:

STEP 1: Create the envelope (request includes data to pre-populate fields for each recipient, if needed).

POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes

See "Creating an Envelope From a Template" section that starts on p27 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for detailed info about request and response.

STEP 2: Retrieve the URL that can be used to launch the recipient's envelope (signing session).

POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes/{envelopeId}/views/recipient

{
"authenticationMethod":"Email",
"clientUserId":"CLIENT_USERID_SPECIFIED_IN_REQUEST",
"email":"RECIPIENT_EMAIL",
"returnUrl":"URL_TO_REDIRECT_TO_WHEN_SIGNING_COMPLETE",
"userName":"RECIPIENT_NAME"
}

The response will contain the URL that can be used to launch the Recipient's Envelope:

{
"url":"URL_THAT_WILL_LAUNCH_ENVELOPE"
}

See the "Post Recipient View" section that starts on p160 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for more detailed info about request and response.

Now, assuming you're doing all this correctly (step 1 and step 2) -- let's get back to the issue you're reporting: difficulty pre-populating fields for the recipient. A few comments about the "Create Envelope from Template" JSON that you included in your question:

• You don't need accountId in request.
• You don't need to include documentId and pageNumber in the request for the tab.
• You DO need to include clientUserId for the recipient in the request, if you want the recipient to sign embedded/captive within your site.

So, here's a "Create/Send Envelope From Template" example request (step 1 above) that pre-populates the tab named "FIELD_1" with the value "VALUE_A" anywhere that it appears in the envelope:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
    "status"        : "sent",
    "emailBlurb"    : "please sign",
    "emailSubject"  : "Please sign your document",
    "templateId"    : "TEMPLATE_ID",
    "templateRoles" : [{
      "name"         : "John Doe",
      "email"        : "[email protected]",
      "roleName"     : "Signer1Role",
      "clientUserId" : "123",
      "tabs"         :
         {"textTabs":[{
            "tabLabel":"\\*FIELD_1",
            "value":"VALUE_A"}
         ]}
   }]
}

Then, you'd take the Envelope Id that's returned in the response and call the "Get Recipient View" resource (step 2 above) to get the URL to launch the signing session:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
     "authenticationMethod": "Email",
     "clientUserId": "123",
     "userName": "John Doe",
     "email": "[email protected]",
     "returnUrl": "http://www.google.com"
}

Finally, one last comment (but an important one): if you're just wanting to inject the recipient's "full name" in the document -- use the "Full Name" tab when creating the Template and DocuSign will automatically inject the recipient's name in place of that tag, anywhere that it appears (instead of you using a Text Tab and having to populate it via the API request). Here's the Full Name tag in the DocuSign UI tagger view:

Another Create Envelope Example (with screenshot of data field properties):

If I submit this request:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign this",
  "emailBlurb": "Please sign...thanks!",
  "templateId": "TEMPLATE_ID",
  "envelopeIdStamping": "false",
  "templateRoles": [
   {
      "roleName": "Signer1",
      "name": "John Doe",
      "email": "[email protected]",
      "recipientId": "1",
      "tabs":{
            "textTabs":[
               {
                  "tabLabel":"\\*address",
                  "value":"123 Main Street"
               },
            ],
         }
    }
  ],
  "status": "sent"
}

And the Data Field properties (when Editing the Template via the DocuSign UI) look like this:

Then the result is that field(s) with Label = address that are assigned to Recipient Role Signer1 will be prepopulated with the value "123 Main Street" when the signer views their envelope. If this isn't working for you, I suggest that you:

• Verify that the value of roleName in the API request exactly matches the Recipient value I've highlighted in the prior screenshot (in my example, "Signer1").
• Verify that the value of tabLabel in the API request exactly matches the Label value I've highlighted in the prior screenshot (in my example, "address).

Note: Values are case-sensitive, so be sure values in your request are an exact match (including upper-case/lower-case) with the values in the Data Field Tag Properties.