Deep dive into the embedded signing recipient view

While you can send an envelope to recipients through email notification (also called remote signing), you can also embed the signing session into your application to enable the user to view and sign documents at the same website. As embedded signing can only be created via the DocuSign eSignature REST API and requires multiple API calls to implement, it’s quite hard to understand the flow of implementing embedded signing and troubleshoot issues you encounter. As the DocuSign Developer Center covers the concept of embedded signing and how you can create the embedded signing, I’m going to explain the thing that isn’t being covered with examples.

  1. Two ways of creating the embedded signing URL
  2. Create the remote signing and embedded signing URLs simultaneously
  3. Problem: I’m seeing the envelope without any tabs on it
  4. Troubleshooting the error

Let’s start!

Two ways of creating an embedded signing URL

When it comes to creating the embedded signing URL, you should call the APIs below in sequence:

  1. CreateEnvelope API
  2. CreateRecipientView API

While you call these APIs, the recipient’s information should be matched between the two API calls. There are two ways to match the recipient information.

Matching email, user name, and clientUserId

Let’s say you create the envelope with the recipient shown below:

  1. CreateEnvelope payload
    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes
    
    ...
    "recipients": {
            "signers": [
                {
                    "routingOrder": 1,
                    "name": "Robert",
                    "email": "example@gmail.com",
                    "clientUserId": "123",
                    "deliveryMethod": "email",
                    "recipientId": "1",
    ...
    

    After you create the envelope, then you should match the value of the name, email, and clientUserId properties with the CreateRecipientView API payload.

  2. CreateRecipientView payload
    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient
    
    {
        "email": "example@gmail.com",
        "clientUserId": "123",
        "AuthenticationMethod": "none",
        "userName": "Robert",
        "returnUrl": "https://www.google.com"
    }
    

    As you can see in the payload, the email, clientUserId, and name(userName) have the same value.

Matching userId and clientUserId

You can also create the embedded signing URL by matching the userId and clientUserId properties. In this case, you need to call the listRecipients API between the CreateEnvelope and CreateRecipientView API calls to retrieve the userId of the recipient. So the sequence of calls should be like this:

  1. CreateEnvelope
    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes
    
    ...
    "recipients": {
            "signers": [
                {
                    "routingOrder": 1,
                    "name": "Robert",
                    "email": "example@gmail.com",
                    "clientUserId": "123",
                    "deliveryMethod": "email",
                    "recipientId": "1",
    ...
    
  2. listRecipients
    GET {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipients

    Take the userId of the recipient from the response and save it, as you are going to use it in the next API call.

  3. CreateRecipientView

    Add the userId retrieved from step 2 and the clientUserId to the payload.

    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient
    
    {
        "AuthenticationMethod": "none",
        "userId": "f9c04a5a-xxxx-xxxx-xxxx-fbdbc94673d7",
        "clientUserId": "123",
        "returnUrl": "https://www.google.com"
    }
    

Create the remote signing and embedded signing URLs simultaneously

Depending on your application’s architecture, you may want to use remote signing and embedded signing simultaneously. You can do this with the DocuSign eSignature REST API and it’s not that different from the above process. 

Note: This only works with a recipient who already has a DocuSign account, so the recipient’s name and email specified in the CreateEnvelope API call should match the DocuSign credential.

The only difference this method has from the above example is the absence of the clientUserId property. Removing the clientUserId from the CreateEnvelope and CreateRecipientView API calls is enough to get the embedded signing URL.

After you create the envelope with CreateEnvelope, the email notification will be sent to your recipient. However, you can also get an embedded signing URL by calling the CreateRecipientView API with the same envelope ID.

  1. CreateEnvelope
    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes
    
    ...
    "recipients": {
            "signers": [
                {
                    "routingOrder": 1,
                    "name": "Robert",
                    "email": "example@gmail.com",
                    "deliveryMethod": "email",
                    "recipientId": "1",
    ...
    
  2. CreateRecipientView
    POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient
    
    {
        "email": "example@gmail.com",
        "AuthenticationMethod": "none",
        "userName": "Robert",
        "returnUrl": "https://www.google.com"
    }
    

You can create the embedded signing URL using the userId property instead of the userName and email properties as well.

Problem: I’m seeing the envelope without any tabs on it

In the case of the embedded signing–only scenario, this happens when you forget to add the clientUserId property, but provide the recipient’s other information (email/userName or userId). Since this call is considered as the request for viewing the envelope, you cannot sign or see the tab. To solve this issue, add the matching clientUserId property in the CreateEnvelope API call payload.

In the case of creating remote signing and embedded signing URLs simultaneously, this happens when the recipient doesn’t have a DocuSign account. As I mentioned earlier, the recipient must have a DocuSign account to create the remote signing and embedded signing URLs simultaneously.

Troubleshooting the error

Below is the error you might get while you call the CreateRecipientView API.

  • UNKNOWN_ENVELOPE_RECIPIENT This error means you have input the wrong userName, email, or clientUserId. You should match the value of the userName, email, and clientUserId properties between the CreateEnvelope and CreateRecipientView API calls.

Additional resources

Byungjae Chung
Author
Byungjae Chung
Developer Support Engineer
Published