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. 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.
- Two ways of creating the embedded signing URL
- Create the remote signing and embedded signing URLs simultaneously (also called hybrid signing)
- 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", ...Once the envelope is created, 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 (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.
CreateEnvelopePOST {{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" ...CreateRecipientViewPOST {{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, orclientUserId. You should match the value of theuserName,email, andclientUserIdproperties between theCreateEnvelopeandCreateRecipientViewAPI calls.
