When DocuSign users request signatures from their recipients, they typically just send the recipient an email requesting that they select a link and sign the document. This is what we call remote signing. We all know that emails can be compromised, so if you are sending signature requests on sensitive documents, you may want to consider adding another layer of authentication to help ensure that the recipients are who they say they are.

DocuSign’s recipient authentication methods address this problem by providing an additional method of authentication to verify the identity of your recipient(s). This combination of the email itself and an additional recipient authentication method is called two-factor authentication or multi-factor authentication.

Adding multi-factor recipient authentication to envelopes can be done by the sender via our web application, or it can be done programmatically by developers building integrations using the eSignature API. One way to get up to speed quickly about using recipient authentication in your application is to download our code examples and try them right away. For this blog post, I assume you chose our C# Authorization Code Grant code examples, so my examples are in C# below. However, we also provide code examples for Node.js, Java, PHP, Python, and Ruby, as well as raw API calls using Curl in Bash shell scripts.

Note: The term Authorization Code Grant refers to a specific type of OAuth authentication your app uses to call the DocuSign API itself. This should not be confused with the recipient authentication that is used to verify the identity of document signers (recipients).

The sample code is organized into separate use cases or scenarios, each being referenced by a unique number. Examples 19-23 are the ones that show you how to implement the different recipient authentication methods. Examples 19-22 only require the DocuSign eSignature REST API v2, but example 23 requires DocuSign eSignature REST API v2.1. We recommend you consider using DocuSign eSignature REST API v2.1 for all your integrations.

In each of the examples I show in this post, most of the code required is the same for each recipient authentication method, except for the few lines of code highlighted in yellow. This makes it very easy for you to implement recipient authentication, or to even select the desired method(s) in your code based on business rules.

Example 19 – Access code authentication

With Access Code Authentication, the sender and the user share a secret code that is required for the recipient to gain access to the envelope. You specify Access Code authentication in the Signer object in your code like this:

Signer signer1 = new Signer()
{
    Name = signerName,
    Email = signerEmail,
    RoutingOrder = "1",
    Status = "Created",
    DeliveryMethod = "Email",
    RecipientId = "1", //represents your {RECIPIENT_ID}
    Tabs = signer1Tabs, // variable with tabs for this signer
    RequireIdLookup = "true", //will use recipient auth
    AccessCode = "$3B453" //represents your {ACCESS_CODE}
};

One challenge with this authentication method is that the sender needs to provide the access code to recipients securely; DocuSign will not send it. Sending the access code to the same email address as the envelope was sent is not recommended. If the recipient’s email is compromised, doing so would not provide additional security over not using recipient authentication at all. You should provide it separately if possible, or you can use a different method. (You can provide it verbally in a phone call or in person, you can send it in a text message, WhatsApp message, Slack message or any other means that is not tied to the same email address).

Example 20 – SMS (text message) authentication

This method of recipient authentication also requires the recipient to enter a code, but the code will be provided to the recipient via a text message to their mobile device. When SMS authentication is specified, DocuSign auto-generates a numeric code at the time the envelope is sent and sends it to the recipient via text message. You specify SMS authentication in the Recipient object in your code like this:

RecipientSMSAuthentication smsAuth = new RecipientSMSAuthentication();

smsAuth.SenderProvidedNumbers = new List<String>();

smsAuth.SenderProvidedNumbers.Add(phoneNumber); //variable for the phone number.

Signer signer1 = new Signer()
{
    Name = signerName,
    Email = signerEmail,
    RoutingOrder = "1",
    Status = "Created",
    DeliveryMethod = "Email",
    RecipientId = "1", //represents your {RECIPIENT_ID}
    Tabs = signer1Tabs, // variable with tabs for this signer
    RequireIdLookup = "true", // will use recipient auth
    IdCheckConfigurationName = "SMS Auth $", //indicates SMS auth
    SmsAuthentication = smsAuth //sets the phone number
};

Note: You need to provide the phone number of the recipient for this method to work. If the recipient does not have a phone capable of receiving text messages, you can use Phone authentication instead, as shown in example 21.

Example 21 – Phone authentication

This method is very similar to the SMS method. Instead of sending a text message, however, DocuSign provides the secret code to the recipient using an automated phone call to the selected number. You specify Phone Authentication in the Recipient object in your code like this:

phoneAuthNumber.SenderProvidedNumbers.Add(phoneNumber); //variable for the phone number.
RecipientPhoneAuthentication phoneAuth = new RecipientPhoneAuthentication()
{
    RecordVoicePrint = "false",
    ValidateRecipProvidedNumber = "false",
    RecipMayProvideNumber = "true",
};
phoneAuth.SenderProvidedNumbers = phoneAuthNumber.SenderProvidedNumbers;
Signer signer1 = new Signer()
{
    Name = signerName,
    Email = signerEmail,
    RoutingOrder = "1",
    Status = "Created",
    DeliveryMethod = "Email",
    RecipientId = "1", //represents your {RECIPIENT_ID}
    Tabs = signer1Tabs, // variable with tabs for this signer
    RequireIdLookup = "true", // will use recipient auth
    IdCheckConfigurationName = "Phone Auth $", //indicates Phone auth
    PhoneAuthentication = phoneAuth //sets the phone number
};

If you don’t want to rely on having a phone number or remembering a code, you have more options available below.

Example 22 – Knowledge-based authentication (or KBA)

KBA authentication requires the recipient to answer detailed questions about themselves based on data available in public records (such as their current and former addresses). DocuSign’s eSignature KBA uses an identity verification service from LexisNexis Risk Solutions that validates user identities in real time. You specify KBA in the Recipient object in your code like this:

Signer signer1 = new Signer()
{
    Name = signerName,
    Email = signerEmail,
    RoutingOrder = "1",
    Status = "Created",
    DeliveryMethod = "Email",
    RecipientId = "1", //represents your {RECIPIENT_ID}
    Tabs = signer1Tabs, // variable with tabs for this signer
    RequireIdLookup = "true", //will use recipient auth
    IdCheckConfigurationName = "ID Check" //indicates KBA Auth
};

When the recipient clicks the link in the email, he or she will first be asked to provide an address. This information, together with the recipient’s name, will be used to generate the list of challenge questions that establishes identity.

Example 23 – Identity Verification (or IDV)

IDV is our newest recipient authentication technology that verifies the identity of recipients based on government photo IDs (such as a driver’s license or passport) and electronic IDs. IDV verifies authenticity via visible security features, watermarks, and machine-readable barcodes. To use IDV, you have to enable this feature on your DocuSign account (either sandbox or production) by contacting your DocuSign Account Manager or Partner Manager. If you’d like to get a better idea of what IDV is, see the link in the Additional Resources section at the end of this post.

Note: IDV is not yet fully functional in every country and region of the world.

You specify IDV authentication in the Recipient object in your code like this:

AccountsApi workflowDetails = new AccountsApi(config);
AccountIdentityVerificationResponse wfRes = workflowDetails.GetAccountIdentityVerification(accountId);
String workflowId = wfRes.IdentityVerification[0].WorkflowId;
RecipientIdentityVerification workflow = new RecipientIdentityVerification()
{
    WorkflowId = workflowId
};
Signer signer1 = new Signer()
{
    Name = signerName,
    Email = signerEmail,
    RoutingOrder = "1",
    Status = "Created",
    DeliveryMethod = "Email",
    RecipientId = "1", // represents your {RECIPIENT_ID}
    Tabs = signer1Tabs, // variable with tabs for this signer
    RequireIdLookup = "true", // will use recipient auth
    IdentityVerification = workflow //add the IDV workflow
};

Additional resources