Confusion over defining recipients for generic DocuSign templates - docusignapi

Question

I have an embedded signing application where users going through a web interview have to sign certain documents at the end. The documents are generic templates, currently defined with the user name and email address left blank. I am providing the user name, email address and a clientUserId in the envelope creation, matching the role that is defined in the template. But I keep getting the error UNKNOWN_ENVELOPE_RECIPIENT - The recipient you have identified is not a valid recipient of the specified envelope. What constitutes a "valid recipient" of a generic template? Am I supposed put something in the user and email fields of the template? I'm confused.
In answer to Larry K below, that appears to be exactly what I have done. Here's the JSON for the create envelope request that results in the error:
{
"accountId":"1234567",
"emailSubject":"Certification Documents",
"status":"sent",
"compositeTemplates":[
{
"serverTemplates":[
{
"sequence":"1",
"templateId":"5ed3d600-5a57-4fee-931f-53233858dc65"
}
],
"inlineTemplates":[
{
"sequence":"1",
"recipients":{
"signers":[
{
"name":"John Doe",
"roleName":"Applicant",
"recipientId":"1",
"clientUserId":"62",
"email":"jd#mydomain.com",
"tabs":{
"textTabs":[
{
"tabLabel":"EmplName",
"value":"John Doe"
},{
"tabLabel":"SSN",
"value":"123456789"
},{
"tabLabel":"DoB",
"value":"08\/26\/1991"
}
]
}
}
]
}
}
]
}
]
}
Here is the Get Recipients response:
{
"signers": [
{
"isBulkRecipient": "false",
"name": "",
"email": "",
"recipientId": "63543029",
"recipientIdGuid": "29a731f6-2f82-490f-9589-f551727414d9",
"requireIdLookup": "false",
"smsAuthentication": {},
"routingOrder": "1",
"note": "",
"roleName": "Applicant",
"status": "created",
"declinedReason": "",
"deliveryMethod": "email",
"templateLocked": "false",
"templateRequired": "false"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [
{
"name": "Real Person",
"email": "rp#mydomain.com",
"recipientId": "83856197",
"recipientIdGuid":
"0f80a5ab-2050-472a-b072-7a18794a4726",
"requireIdLookup": "false",
"smsAuthentication": {},
"routingOrder": "1",
"note": "",
"roleName": "Mancon",
"status": "created",
"declinedReason": ""
}
],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "2"
}
I've got it. Too many iterations of messing with code, mixing live code with debug stuff. It looked like the error was coming from the envelope creation because I had stepped on a debug message. But in fact the code was going through to the signing view request, which actually was generating the error. And there, as you might guess, was a debug clientUserId, which did not match the envelope. I hate it! Thanks for the coaching. It eventually led me to the real problem.

Answer 1

To troubleshoot, I'd suggest executing a Get Template Recipients request for the Template you're using (GET /v2/accounts/{accountId}/templates/{templateId}/recipients), then compare the contents of that response with the recipients portion of your Create Envelope From Template request that's resulting in the error UNKNOWN_ENVELOPE_RECIPIENT. If you can't spot a difference, feel free to update your post (question above) with the trace of your original Create Envelope request as well as the response from Get Template Recipients (removing any sensitive info, of course), and perhaps someone here can spot the issue.

Answer 2

Another answer from a second DocuSign consultant:
He suggests that perhaps the reason you received the error was that you didn't use the exact same triplet of {recipient/signer name, email, client id} in both your call to Envelopes: create and to EnvelopeViews: createRecipient
The following should work:
Call to Envelopes: create:
{
"emailSubject":"My subject",
"emailBlurb":"My blurb",
"templateId":"My template id",
"templateRoles":[
{
"clientUserId":"123456789",
"roleName":"My role",
"name":"Name",
"email":"email"
}
],
"status":"sent"
}
Call to EnvelopeViews: createRecipient:
{
"authenticationMethod": "password",
"email": "email",
"returnUrl": "https://www.docusign.com",
"userName": "Name",
"clientUserId": "123456789"
}

Answer 3

A solution from one of our DocuSign consultants is below. He recommends compositing the recipient information with the template. Here's the json for the Envelopes: create call:
{
"emailSubject": "Create Envelope with embedded recipient",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "{Template ID}"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"clientUserId": "Unique Identifier",
"email": "signer1#example.com",
"name": "Signer One",
"recipientId": "1",
"roleName": "Customer"
}
]
}
}
]
}
]}