Blog
Home/

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

Author Geoff Pfander
Geoff PfanderSenior Developer Support Engineer
Summary3 min read

In-person signers and embedded signers are two different things. Let us make sure you don't get confused.

    • Whose session is it, anyway?
    • Additional resources

    Table of contents

    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

    Author Geoff Pfander
    Geoff PfanderSenior Developer Support Engineer

    Beginning in the 1990s, Geoff's engineering career has followed the evolution of COM, Java and .NET on the machine and SOAP and REST in the cloud. Currently the Developer Support team's subject matter expert for the Apex Toolkit, Geoff has extensive experience as an engineer in support, test, and sales. You can find him on LinkedIn.

    More posts from this author

    Related posts

    • From the Trenches: Testing Docusign Connect with ngrok
      Developer Support Articles

      From the Trenches: Testing Docusign Connect with ngrok

      Author Ivan Dinkov
      Ivan Dinkov
    • From the Trenches: Controlling Sign on Paper options via the API

      From the Trenches: Controlling Sign on Paper options via the API

      Author Guilherme Flores
      Guilherme Flores
    From the Trenches: Testing Docusign Connect with ngrok

    From the Trenches: Testing Docusign Connect with ngrok

    Author Ivan Dinkov
    Ivan Dinkov
    From the Trenches: Controlling Sign on Paper options via the API

    From the Trenches: Controlling Sign on Paper options via the API

    Author Guilherme Flores
    Guilherme Flores

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting