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:
CreateEnvelopepayloadPOST {{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.
CreateRecipientViewpayloadPOST {{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:
CreateEnvelopePOST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes ... "recipients": { "signers": [ { "routingOrder": 1, "name": "Robert", "email": "example@gmail.com", "clientUserId": "123", "deliveryMethod": "email", "recipientId": "1", ...listRecipientsGET {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipientsTake the userId of the recipient from the response and save it, as you are going to use it in the next API call.
CreateRecipientViewAdd 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.
CreateEnvelopePOST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes ... "recipients": { "signers": [ { "routingOrder": 1, "name": "Robert", "email": "example@gmail.com", "deliveryMethod": "email", "recipientId": "1", ...CreateRecipientViewPOST {{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, andclientUserIdproperties between theCreateEnvelopeandCreateRecipientViewAPI calls.
