Invalid recipient from docusign API

Question

I'm trying to embed a docusign signature page into a website. but I get this error

Message=Error calling CreateRecipientView: {
  "errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
  "message": "The recipient you have identified is not a valid recipient of 
  the specified envelope."
}

I'm using the .Net nuget client and here's the code I'm using (note I've changed guids and emails)

Authenticate

string userId = "0570b3da-652e-4040-842e-65a0e6fc8133"; // use your userId (guid), not email address
string integratorKey = "cf73e7bb-e05d-4ce9-9cea-ac065dc894ac";
string host = "https://demo.docusign.net/restapi";

ApiClient apiClient = new ApiClient(host);

string username = "my@email.com";
string password = "[password]";

// initialize client for desired environment (for production change to www)
Configuration.Default.ApiClient = apiClient;

// configure 'X-DocuSign-Authentication' header
string authHeader = "{\"Username\":\"" + username + "\", \"Password\":\"" + password + "\", \"IntegratorKey\":\"" + integratorKey + "\"}";
Configuration.Default.AddDefaultHeader("X-DocuSign-Authentication", authHeader);

Find account id

this was part of the example code

// we will retrieve this from the login API call
string accountId = null;

AuthenticationApi authApi = new AuthenticationApi(apiClient.Configuration);
LoginInformation loginInfo = authApi.Login();

//find the default account for this user
foreach (LoginAccount loginAcct in loginInfo.LoginAccounts)
{
    if (loginAcct.IsDefault == "true")
    {
        accountId = loginAcct.AccountId;

        string[] separatingStrings = { "/v2" };

        // Update ApiClient with the new base url from login call
        apiClient = new ApiClient(loginAcct.BaseUrl.Split(separatingStrings, StringSplitOptions.RemoveEmptyEntries)[0]);
        break;
    }
}

Create Envelope from a template

EnvelopeDefinition envDef = new EnvelopeDefinition();
TemplateRole tRole = new TemplateRole();
tRole.Email = "recipient@email.com";
tRole.RoleName = "Leaseholder";
tRole.ClientUserId = tRole.Email;

List<TemplateRole> rolesList = new List<TemplateRole> { tRole };

envDef.TemplateRoles = rolesList;
envDef.TemplateId = "2504e3f0-f4d9-4eca-9fd3-3b26cfd6c086";

RecipientViewRequest viewOptions = new RecipientViewRequest()
{
    ReturnUrl = "http://localhost:64202/home/winning",
    ClientUserId = tRole.Email,  // must match clientUserId of the embedded recipient
    AuthenticationMethod = "email",
    UserName = tRole.Email,
    Email = tRole.Email
};

EnvelopesApi envelopesApi = new EnvelopesApi();
var summary = envelopesApi.CreateEnvelope(accountId, envDef);
var receipients = envelopesApi.ListRecipients(accountId, summary.EnvelopeId);
ViewUrl viewUrl = envelopesApi.CreateRecipientView(accountId, summary.EnvelopeId, viewOptions);

return Content($"<h2>hmm</h2><iframe width=\"100%\" height=\"100%\" src=\"{viewUrl.Url}\"/>");

Recipients on the template

Recipients

{
"agents": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"editors": [],
"inPersonSigners": [],
"intermediaries": [],
"recipientCount": "1",
"seals": [],
"signers": [
  {
    "clientUserId": "recipient@email.com",
    "creationReason": "sender",
    "deliveryMethod": "email",
    "email": "recipient@email.com",
    "isBulkRecipient": "false",
    "name": "",
    "note": "",
    "recipientId": "1",
    "recipientIdGuid": "52abdeea-2bd6-4108-97b9-170ca27d573a",
    "requireIdLookup": "false",
    "roleName": "Leaseholder",
    "routingOrder": "1",
    "status": "created",
    "userId": "0570b3da-652e-4040-842e-65a0e6fc8133"
  }
]
}

Answer 1

The UNKNOWN_ENVELOPE_RECIPIENT error usually means that one of the following three property values specified for the Recipient within the Envelope doesn't exactly match the corresponding value that's been specified in the Get Recipient View request:

• Name
• Email
• ClientUserId

In your case (based upon the code you posted), I suspect that the UNKNOWN_ENVELOPE_RECIPIENT error is being caused by the fact that the info you've specified for the recipient does not include a value for the Name property -- where as the info you've specified when creating the RecipientViewRequest object does include a value for the UserName property (as it must).

To fix this error, I'd suggest that you try adding this line to the portion of your code when you're specifying information for the TemplateRole object (where "RECIPIENT_NAME" is the first and last name of the recipient).

tRole.Name = "RECIPIENT_NAME;

And then specify the same value for the UserName property of the RecipientViewRequest object:

UserName = "RECIPIENT_NAME",

(The value you specify as RECIPIENT_NAME will be the name that the recipient signs in the doc(s), so you should specify first name / last name of the person, not an email address.)

---

UPDATE

Re the subsequent RECIPIENT_NOT_IN_SEQUENCE error that you've mentioned in your comment, this error occurs when you call Get Recipient View for a recipient either before the Envelope has been sent or before it's "their turn" in the routing order to receive the Envelope. In your case, I suspect this is occurring because you're not setting the status of the Envelope to sent -- the recipient can't receive/access the Envelope until it's been sent. To resolve this error, set the status of of the Envelope when you're composing the EnvelopeDefinition object:

envDef.Status = "sent";