Envelope Recipient not matching when requesting view - docusignapi

Question

When creating envelopes which are used later to generate a view URL for the signer to use instead of receiving an email, we are running into a problem where the user we are specifying isn't valid.
For example, here is an envelope with one recipient, "Peter Hughes Jr."
Request URL: https://na2.docusign.net/restapi/v2/accounts/4476693/envelopes/f3a45945-f1ff-4731-a407-963a32378d77/recipients
------
{"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
Request headers:
X-DocuSign-Authentication : {"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
Host : na2.docusign.net
Connection : Keep-Alive
------
Request body:
------
Response headers:
Strict-Transport-Security : max-age=7776000; includeSubDomains
Content-Length : 696
Cache-Control : no-cache
Content-Type : application/json; charset=utf-8
Date : Thu, 18 Dec 2014 15:26:42 GMT
------
Response body:
{
"signers": [
{
"name": "Peter Hughes Jr.",
"email": "pwhughes#verizon.net",
"recipientId": "1",
"recipientIdGuid": "2461be9a-69d3-420d-b5f3-2c327af2f5f6",
"requireIdLookup": "false",
"userId": "0d5035dc-b70f-4026-8283-5c8d8903385a",
"clientUserId": "1",
"routingOrder": "1",
"note": "",
"roleName": "Applicant",
"status": "sent",
"templateLocked": "false",
"templateRequired": "false"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "1",
"currentRoutingOrder": "1"
}
When we attempt to set up a view for this user, the following exception occurs:
Request URL: https://na2.docusign.net/restapi/v2/accounts/4476693/envelopes/f3a45945-f1ff-4731-a407-963a32378d77/views/recipient
------
{"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
------
EXCEPTION
System.Net.WebException: The remote server returned an error: (400) Bad Request.
at System.Net.HttpWebRequest.GetResponse()
at DocusignView.Request.Send[T](String body) in C:\Users\johnathank\Desktop\docusigntest\DocusignView.cs:line 293
------
Request headers:
X-DocuSign-Authentication : {"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
Content-Type : application/json
Host : na2.docusign.net
Content-Length : 143
Expect : 100-continue
------
Request body:
{"authenticationMethod":"email","clientUserId":"1","email":"pwhughes#verizon.net","returnUrl":"www.impellam.com","userName":"Peter Hughes Jr."}
------
Response headers:
Strict-Transport-Security : max-age=7776000; includeSubDomains
Content-Length : 152
Cache-Control : no-cache
Content-Type : application/json; charset=utf-8
Date : Thu, 18 Dec 2014 15:28:31 GMT
------
Response body:
{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the specified envelope."
}
We've actually identified the problem, but haven't found a good way to implement a solution yet. When inspecting the envelope within Docusign, I can see that this user has adopted the name "Peter W. Hughes Jr".
So I attempted sending another view request with the name "Peter W. Hughes Jr." instead, and it worked...
However this poses a problem. How are we able to find out what the adopted name of the user is? It is not in the original envelope data, and from browsing the API at iodocs.docusign.com, none of the methods there seem to give me the user's adopted name.
I have read an alternate solution that says we can provide a userId in the view request instead of the userName, but when I attempt to do that, I receive an error indicating that userName is required.
Request URL: https://na2.docusign.net/restapi/v2/accounts/4476693/envelopes/f3a45945-f1ff-4731-a407-963a32378d77/views/recipient
------
{"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
------
EXCEPTION
System.Net.WebException: The remote server returned an error: (400) Bad Request.
at System.Net.HttpWebRequest.GetResponse()
at DocusignView.Request.Send[T](String body) in C:\Users\johnathank\Desktop\docusigntest\DocusignView.cs:line 295
------
Request headers:
X-DocuSign-Authentication : {"IntegratorKey":"***","Password":"***","Username":"onboarding#impellam.com"}
Content-Type : application/json
Host : na2.docusign.net
Content-Length : 191
Expect : 100-continue
------
Request body:
{"authenticationMethod":"email","clientUserId":"1","email":"pwhughes#verizon.net","returnUrl":"www.impellam.com","userId":"2461be9a-69d3-420d-b5f3-2c327af2f5f6","userName":"Peter Hughes Jr."}
------
Response headers:
Strict-Transport-Security : max-age=7776000; includeSubDomains
Content-Length : 167
Cache-Control : no-cache
Content-Type : application/json; charset=utf-8
Date : Thu, 18 Dec 2014 15:52:06 GMT
------
Response body:
{
"errorCode": "INVALID_REQUEST_PARAMETER",
"message": "The request contained at least one invalid parameter. A value was not found for parameter 'userName'."
}

Answer 1

This is only an issue when multiple envelopes are sent in flight to the same recipient name, email and clientUserId combination.
Once you send the recipienttoken and they sign with a different name, using the same request for the second envelope will fail because of the name change.
Best practice would be to generate a new clientUserId for each envelope or prevent the recipient from changing their name within the DocuSign Account Features. The feature is called "Signature Adoption Configuration".