From the Trenches: Hybrid Captive/Remote signing with EmbeddedRecipientStartUrl

In general, it's best to choose early on in the workflow design whether each recipient should be captive or remote. And, while it's fine to have a mix of captive and remote recipients on an envelope, it may arise that a particular recipient could be signing in a captive session through your application, but may instead need an email invitation to access the envelope. 

In this case, the EmbeddedRecipientStartUrl parameter can be added to the recipient definition with a value of SIGN_AT_DOCUSIGN to flag them as a special kind of hybrid recipient. When that parameter is set on a recipient, an email invitation to sign will be delivered, but your application can still use their ClientUserId to request the captive signing session.

For example: let's say I've built an application that runs on my in-store kiosks using captive signing. Recently, I've run into situations where all the kiosks are in use, so I want to allow my customers to sign on their phones as well. In this case, I'll use the same envelope definition as before, with a slight change to the signing recipient. In C# I might do this:

String signerEmail = ""
String signerName = "Example Signer"
String SignerUserId = "999"

var signer = new Signer()
             ClientUserId = signerUserId,
             Email = signerEmail,
             EmbeddedRecipientStartURL = "SIGN_AT_DOCUSIGN"
             Name = signerName,
             RoutingOrder = "1",
             RecipientId = "1",

Which would result in this raw JSON:

"signers": [
    "clientUserId": "999",
    "email": "",
    "embeddedRecipientStartURL": "SIGN_AT_DOCUSIGN",
    "name": "Example Signer",
    "recipientId": "1",
    "routingOrder": "1"

Now my signer will receive an email with a link directly to the envelope, but if a kiosk is available, my application can still request a captive signing session for them with no change to the RequestRecipientView call.

As an additional customization step, it's possible to define a landing page the signer is taken to instead of directly into the envelope. Let's say I want my signer to sign in to my portal and watch a short video prior to signing the envelope. First, I would need to set up the landing page on my website and confirm that the landing page is able to make a RequestRecipientView call when the user is ready to sign. That landing page will need to be exposed to the open internet (to allow the signer to access on their personal device), so I'll want to make sure I have my own system of authentication prior to showing anything confidential. 

Once I have my portal up and running, I'll change the EmbeddedRecipientStartUrl parameter to point to my login page. Once the signer has logged in to my application and completed the required tasks, my application makes a RequestRecipientView call and directs the user to sign.

Important: While an email invitation to sign is delivered, this kind of captive envelope will not show up in the signer's Docusign inbox, nor will they receive automated reminders or expiration notifications. The signer is still a captive recipient, so the envelope is not associated with the signer's Docusign account. As always, we recommend you test thoroughly in the demo environment prior to implementation.

Additional resources

Drew Martin
Drew Martin
Developer Support Engineer