How do I send an accessCode to a recipient and override the email using a template via the DocuSignAPI?

Question

I have tried just about everything that I can think of and cannot get this to work.

I am trying to set an access code in my code and send it to a templateRole using the RequestSignatureFromTemplate call. Right now, all of my configuration info is in XML. I am NOT adverse to using JSON but not all of my developers know JSON.

Here is a snippet of my XML.

<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">
    accountId>12345</accountId>
    <status>sent</status>                        
    <emailSubject>Test Form</emailSubject>
    <emailBlurb>This is a template test.</emailBlurb>
    <templateId>####-########</templateId>
    <templateRoles>
        <templateRole>
            <accessCode>AccessCode124</accessCode>" +
            <addAccessCodeToEmail>true</addAccessCodeToEmail>" +
            <email>jevans@eclarifire.com</email>
            <name>Test User</name>
            <roleName>RoleOne</roleName>
            <emailNotification>
                <emailSubject>This is RoleOne's subject</emailSubject>
                <emailBody>This is RoleOne's email.</emailBody>
                <addAccessCodeToEmail>true</addAccessCodeToEmail>
            </emailNotification>
        </templateRole>
        <templateRole>
            <accessCode>AccessCode246</accessCode>
            <email>jevans@eclarifire.com</email>
            <name>Test User2</name>
            <roleName>RoleTwo</roleName>
            <emailNotification>
                <emailBody>Your access code is 24680</emailBody>
            </emailNotification>
        </templateRole>
    </templateRoles>
</envelopeDefinition>

You'll notice that I have two different implementations in the templateRole nodes. This is intentional since I'm trying everything that I can think of. In templateRole(1), I have added the addAccessCodeToEmail node in two different places and it doesn't work in either. I have also attempted to override the emailBlurb node in templateRole(1) and it doesn't work either.

I've been through the documentation and it says that you should be able to add anything that the Recipients format follows but I can't get it to work.

Any one got any ideas?

score 0 · Answer 1 · answered Oct 22 '13 at 16:04

I've never used the addAccessCodeToEmail property in a "Create/Send Envelope" API request, because including the Access Code in the email that the recipient receives entirely nullifies the effect of using Access Code for authentication in the first place. i.e., the entire point of requiring the Recipient to enter an Access Code is to add another layer of assurance -- beyond the fact that someone merely has access to an email inbox -- before granting access to the envelope. If you're going to include the access code in the email that the Recipient receives, then using Access Code as the form of authentication isn't providing any additional security benefit whatsoever -- whoever has access to that email inbox will be able to easily access the envelope (same result as if you don't use Access Code at all).

That being said, there is a property that (for whatever reason) should allow you to have Access Code included in the email that the recipient receives -- I can't get this to work either. Maybe a bug, but someone at DocuSign will need to confirm. According to the documentation, this should result in the email containing the access code:

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"        : "JohnsEmail@outlook.com",
      "roleName"     : "Signer1",
      "accessCode"   : "1234",
      "addAccessCodeToEmail": "true"
   }]
}

This request results in the recipient being required to enter an Access Code before he can access the Envelope, but the addAccessCodeToEmail property isn't having the expected effect, as the Access Code doesn't appear anywhere in the email that the recipient receives.

Alternative Approach (Best Practice): Instead of adding the plain-text access code to the email, best practice when using the API to create/send an Envelope and require Access Code as the form of recipient authentication would be to do the following:

Programmatically set accessCode using a piece of data that your application knows about the recipient.
Set the "Email Blurb" (i.e., body of the email) to provide a hint as to the Access Code.

For example, let's say your application knows the Recipient's social security number. When you make the "Create Envelope" API request:

Set the value of accessCode to the last 4 digits of the Recipient's SSN.
Set the value of emailBlurb to include the messaging "Your access code is the last 4 digits of your SSN."

Doing things this way is much more secure than simply including the Access Code (in plain text) in the Email itself.

Finally, regarding your question about overriding the email subject & body for recipients -- see definition of emailNotification property on page 290-291 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf):

IMPORTANT: If this is enabled for one recipient, it overrides the Envelope Subject and EmailBlurb. Also, you must enable emailNotification for all recipients.

Sounds like you need to set emailNotification for each and every recipient if you want it to have any effect.

I understand about sending the access code in the email. However, I don't have any access to any of the other verification methods that the documentation shows. I have email and that's it. Probably because it's only a developer account and that's only in demo mode right now. I would prefer to send a separate email, send a text, or something else. I just couldn't get this documented option to work. — JamminJimE, Oct 22 '13 at 17:03
I believe all Developer accounts get authentication methods ID Check and Phone Auth enabled by default, perhaps SMS Auth as well -- so you should have access to those auth methods (at no cost in Demo environment -- but at least some of these methods DO cost $ per use in the Prod environment). If you're creating the Envelope from a Template, why not just select the auth method for each recipient in the DocuSign "Edit Template" UI? (Contact DocuSign to have auth methods enabled if you don't see "ID Check" and "Phone Auth" and "SMS Auth" in the "Identify" dropdown-list for each recipient.) — Kim Brandl, Oct 22 '13 at 18:14
Also, even if you DO verify that ID Check, Phone Auth, and SMS Auth are enabled for your account -- I don't believe it's possible to specify any Recipient Authentication method other than Access Code when you're creating the envelope via the "Create Envelope from Template" API request. (See definition of "templateRoles" on pages 108-109 of the REST API guide for list of valid recipient properties.) Instead you'll need to create the envelope using "Composite Templates" in your API request -- Composite Templates will enable you to create the envelope via a Template using any recip auth methods. — Kim Brandl, Oct 22 '13 at 18:19

score 0 · Answer 2 · answered Oct 22 '13 at 18:32

Here are a couple of examples that use "Composite Templates" in the Create Envelope API request to create an envelope with either ID Check or Phone Authentication as the method of recipient authentication.

Recipient Authentication = ID Check

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign",
  "emailBlurb": "Please sign...thanks!",
  "status": "sent",
  "compositeTemplates": [
  {
    "serverTemplates": [
    {
        "sequence" : 1,
        "templateId": "TEMPLATE_ID"
    }],
    "inlineTemplates": [
    {
        "sequence" : 2,
        "recipients": {
            "signers" : [{
                "email": "SallysEmail@outlook.com",
                "name": "Sally Adamson",
                "recipientId": "1",
                "roleName": "ROLE_NAME",
                "requireIdLookup": "true",
                "idCheckConfigurationName": "ID Check $"
            }]
        }
    }]
  }]  
}

Recipient Authentication = Phone Auth

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign",
  "emailBlurb": "Please sign...thanks!",
  "status": "sent",
  "compositeTemplates": [
  {
    "serverTemplates": [
    {
        "sequence" : 1,
        "templateId": "TEMPLATE_ID"
    }],
    "inlineTemplates": [
    {
        "sequence" : 2,
        "recipients": {
            "signers" : [{
                "email": "SallysEmail@outlook.com",
                "name": "Sally Adamson",
                "recipientId": "1",
                "roleName": "ROLE_NAME",
                "requireIdLookup": "true",
                "idCheckConfigurationName": "Phone Auth $",
              "phoneAuthentication": {
                "recipMayProvideNumber": "false",
                "senderProvidedNumbers": ["206-444-5555"]
              }
            }]
        }
    }]
  }]  
}

How do I send an accessCode to a recipient and override the email using a template via the DocuSignAPI?

2 Answers2