From the Trenches: Don’t get embedded with your in-person signers!

Also by Laura Waite, Docusign Developer Support

In recent months, Docusign Support has seen a few cases where customers were confusing In-Person Signer recipients with embedded, or captive, recipients. The concepts are similar, but the differences are significant, as is the impact to your use case when one is substituted for the other. 

In-session recipients defined

When considering the recipient structure for envelopes, you have two choices for how recipients will access the signing ceremony: remote, in which the recipient receives an invitation to sign via email; or in-session. In-session signing refers to any signing ceremony that is not accessed via email invitation. There are several types of in-session signers, but the eSignature REST API focuses mainly on two types: embedded recipients and In-Person Signer recipients. 

Embedded recipients are the most common in-session recipient type used in envelopes sent via API. Embedded signing enables recipients to view and sign documents directly through your app or website without having to switch contexts to email. In this sense, your application hosts a signing session: no physical presence required or captured in the Certificate of Completion.

An In-Person Signer is a type of Docusign in-session recipient that allows a known user on a Docusign account who is in the physical presence of the intended signer to host a signing session on their behalf. The “session” for this in-session signing scenario is associated with your known user, and the signing ceremony itself is recorded on the Certificate of Completion as being conducted in person. 

Whose session is it, anyway?

Now that you understand the differences between these two in-session recipients, let’s talk about how to keep the lines from being blurred in your calls. When an In-Person Signer recipient is declared, you do not need to assign a value to the clientUserId property. The clientUserId property is reserved for defining embedded recipients. Embedded signers are account-less; therefore, the connection to your known account user is lost. The end result is that, if you define a clientUserId for an In-Person Signer, you will run into a host of unwelcome issues.

Customers have reported a variety of problems ranging from emails being sent to the wrong user or not at all, signatures not being matched to users, and Certificates of Completion not reflecting correct information—all related to conflating the embedded and In-Person signer types. 

Here is a JSON example of creating an In-Person Signer recipient as part of an envelope definition.

"recipients": {
    "inPersonSigners": [
          {
                 "hostEmail": "gxxx@example.com",
                 "hostName": "Geoff Test",
                 "inPersonSigningType": "inPersonSigner",
                 "recipientId": "1",
                 "requireIdLookup": "false",
                 "routingOrder": "1",
                 "signerEmail": "bobxxx@customer.com",
                 "signerName": "Bob",
                 "tabs": {
                        "signHereTabs": [],
                        "textTabs": []
                 }
          }
    ]
}

And here is the REST request with the JSON body for getting this recipient’s ViewUrl:

POST /restapi/v2.1/accounts/ACCOUNT_ID/envelopes/ENVELOPE_ID/views/recipient

{
    "authenticationMethod": "email",
    "email": "bobxxx@customer.com",
    "recipientId": "1",
    "returnUrl": "https://www.docusign.com",
    "userName": "Bob"
}

And finally, here is the C# code using the eSignature SDK to generate this JSON:

// Add an In-Person Signer recipient to sign the envelope
InPersonSigner inPersonSigner = new InPersonSigner();
inPersonSigner.HostEmail = "gxxx@example.com";
inPersonSigner.HostName = "Geoff Test";
inPersonSigner.InPersonSigningType = "inPersonSigner";
inPersonSigner.RecipientId = "1";
inPersonSigner.RequireIdLookup = "false";
inPersonSigner.RoutingOrder = "1";
inPersonSigner.SignerEmail = recipientEmail; //bobxxx@customer.com in our example
inPersonSigner.SignerName = recipientName; //Bob in our example
// Add the In-Person Signers to the envelope definition
envDef.Recipients.InPersonSigners = new List<InPersonSigner>();
envDef.Recipients.InPersonSigners.Add(inPersonSigner);
// Create the RecipientViewRequest for the In-Person Signer
RecipientViewRequest viewOptions = new RecipientViewRequest() {
    ReturnUrl = "https://www.docusign.com",
    RecipientId = "1",
    AuthenticationMethod = "email",
    UserName = recipientName,
    Email = recipientEmail             
};
// Use the RecipientViewRequest to get the ViewUrl
ViewUrl viewUrl = envelopesApi.CreateRecipientView(accountId, envelopeId, viewOptions);

Additional resources

• In Person Signing in the NDSE guide

• Embedded Signing Guide

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign Developer Newsletter