Embedding

 

The DocuSign platform offers two methods of initiating workflows, both of which are available through the API. When you initiate signature requests by sending emails your recipients are known as Remote recipients. The alternative method of initiating requests is by navigating to a URL - which is referred to as Embedding or Captive recipients. With embedding URL tokens can be used to start the signing process, start the tag-and-send workflow, or access the DocuSign Console. This means that your users do not have to leave your website or app to utilize DocuSign functionality, nor do they have to wait for emails to arrive to begin workflows.

For instance, you could have a webpage that has a "Sign Now" button that starts the signing process for a given user by navigating them to a URL. And you can control which URL your recipients are redirected to once the signing is complete. (You can also control the redirect pages for other actions, such as declining to sign, viewed the envelope, etc.) Additionally, using Embedding you can start users off in the tag-and-send view where they can add Stick-eTabs and recipients to their envelopes before sending. Or you could start your users in the DocuSign Console - where they can create new envelopes, sign existing ones, change account settings, etc (all based on their permissions).

Embedding vs. Remote

API calls that use the Embedding method of initiating requests have some differences compared to Remote (email) based requests. One difference is that you do not have to wait for emails to arrive when using the Embedded method- you can initiate your workflows immediately by navigating to a URL.

Another main difference is that for embedded recipients there is a clientUserId element added to their recipient definitions in the request bodies. On a given envelope if a recipient does not have the clientUserId element defined then the recipient is a remote recipient, and requests to them will be initiated through email notifications. On the other hand, if the clientUserId is present and it's value is not null then the recipient is an embedded recipient, and they can access the envelope through a URL token instead of a hyperlink in an email. The value of the clientUserId element is user defined and is of type string, so you can supply whatever numbers or letters you'd like to identify your embedded recipients. All you have to do is keep track of which clientUserId values are used for which recipients, since you will need that value when time comes to request the signing (or sending) URLs.

Note: URL tokens have a TTL (time to life) and are only valid for 5 minutes at the time of this writing. New tokens need to be generated upon expiration. Please see the REST API Guide for more information.

The following JSON body contains an embedded recipient- which means they will start the signing process by navigating to a URL:

"recipients": {
    "signers": [
      {
        "tabs": {
          "signHereTabs": [
            {
              "name": "SignatureTab1",
              "pageNumber": "1",
              "documentId": "1",
              "yPosition": "100",
              "xPosition": "100"
            }
          ]
        },
        "routingOrder": "1",
        "recipientId": "1",
        "clientUserId": "1000",
        "name": "Sally Doe",
        "email": "test_1@email.com"
      }
    ]
}

As you can see the clientUserId element has been defined for this recipient, which means they are an embedded recipient. Future API calls that involve this envelope will need to specify a clientUserId with the value of 1000 to correctly reference this embedded recipient. If a future API call for this envelope specifies the same name and email address as this recipient but does not specify the clientUserId element, or they specify a value other than 1000, the system will not be able to identify the recipient and an error will be returned.

Once an envelope is sent its recipient types cannot be modified. So if you send an envelope with two embedded recipients and one remote recipient those two embedded recipients will always be embedded and you will need to use their clientUserId element to correctly reference them. Likewise, the one remote recipient will remain a remote recipient throughout the envelope's lifecycle and if you try to reference them with requests that contain the clientUserId property an error will be returned.

To change embedded recipients to remote ones and vice-versa you can remove the recipients from the envelope and add them back in as the desired type. Note though that once you remove a recipient their corresponding tabs are also removed, so you will probably have to add the tabs back in for your new recipient(s). For more information on recipients and recipient corrections and modifications please see the Recipients section.

API Walkthroughs 7, 8, 9

The last three API Walkthroughs all cover Embedding functionality. They demonstrate Embedded Sending, Embedded Signing, and Embedded DocuSign (i.e. launching the DocuSign Console). To recap, one of the main differences between Embedded recipients and remote (email based) ones are that embedded recipients do not have to wait for an email to begin sending or signing documents. Additionally, embedded recipients have a clientUserId element defined in their request bodies whereas remote recipients do not.

The Embedded Sending walkthrough demonstrates how to generate an authenticated URL token which, when navigated to in a webview, iFrame, or browser, opens the "tag-and-send" view for a given recipient. Similarly, the Embedded Signing walkthrough generates an URL token which, when navigated to, starts the signing view an envelope. Lastly, the Embedded DocuSign Console walkthrough starts users off in the DocuSign Console, where they can send and sign envelopes, change account settings, and perform other tasks based on their account permissions.

As always, please refer to the REST API Guide for more information.