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.
- Two ways of creating the embedded signing URL
- Create the remote signing and embedded signing URLs simultaneously
- Problem: I’m seeing the envelope without any tabs on it
- 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:
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:
CreateEnvelope
payloadPOST {{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.
CreateRecipientView
payloadPOST {{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:
CreateEnvelope
POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes ... "recipients": { "signers": [ { "routingOrder": 1, "name": "Robert", "email": "example@gmail.com", "clientUserId": "123", "deliveryMethod": "email", "recipientId": "1", ...
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.
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.
CreateEnvelope
POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes ... "recipients": { "signers": [ { "routingOrder": 1, "name": "Robert", "email": "example@gmail.com", "deliveryMethod": "email", "recipientId": "1", ...
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
, orclientUserId
. You should match the value of theuserName
,email
, andclientUserId
properties between theCreateEnvelope
andCreateRecipientView
API calls.