Blog
Home/

Deep dive into the embedded signing recipient view

Byungjae Chung
Byungjae ChungDeveloper Support Engineer
Summary4 min read

Discover details of how to set up the embedded signing recipient view and troubleshoot problems with your envelopes.

Table of contents

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. 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 troubleshooting issues you encounter. As the Docusign Developer Center covers the concept of embedded signing and how you can create the embedded signing recipient view, I’m going to explain the things that aren’t being covered with our examples.

  1. Two ways of creating the embedded signing URL

  2. Create the remote signing and embedded signing URLs simultaneously (also called hybrid signing)

  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",
    ...

    Once the envelope is created, 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 (also called hybrid signing)

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 embedded signing-only scenario described above.

The only difference this scenario has from the embedded-signing only scenario is adding the embeddedRecipientStartURL property with the value SIGN_AT_DOCUSIGN.

Once you create the envelope with CreateEnvelope, an email notification will be sent to your recipient. If you want to create the embedded signing URL in addition to the email notification, you can get it 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",
    			"clientUserId": "123",
                    "deliveryMethod": "email",
                    "recipientId": "1",
    			"embeddedRecipientStartURL": "SIGN_AT_DOCUSIGN"
    ...
    

  2. CreateRecipientView

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

Note: 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.

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
Byungjae ChungDeveloper Support Engineer

Byungjae Chung has been a Developer Support Engineer for Docusign since 2022. He specializes in helping developers resolve issues they encounter when developing applications using Docusign APIs. You can reach Byungjae on LinkedIn.

More posts from this author

Related posts

  • Developers

    What Are API Services? Benefits & Uses

    Docusign Contributor
  • Fast-Track Your Extension Apps with Reference Implementations

    Karissa Jacobsen
    Karissa Jacobsen
  • Paige Rossi
    Paige Rossi

Fast-Track Your Extension Apps with Reference Implementations

Karissa Jacobsen
Karissa Jacobsen
Paige Rossi
Paige Rossi

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

Explore Docusign IAMTry eSignature for Free
Person smiling while presenting