Docusign does not let me add Recipients to Templates - docusignapi

Question

I created a Template on the UI and uploaded a doc. I then added a Recipient from the UI and mapped a few fields in the document.
I want to create an envelope based on this template and populate some of the fields before sending for a signature. The idea is, we have a portal where a user can fill up a form and a document is sent to him for signing.
Looking at the docs here. I am supposed to send and populate it like so:
{
...
"templateId": "68a89cdc-xxxx-xxxx-xxxx-fa2ab60713e3",
"recipients": {
"signers": [
{
...
"name": "Example Name",
"email": "examplename#example.com",
"roleName": "Signer One",
}
]
...
},
...
}
This however gives me an error back:
Status: 400 INVALID_REQUEST_PARAMETER: The request contained at least one invalid parameter. 'recipients' may not be specifed when 'templateId' is set. Use 'templateRoles'.
I proceeded to use templateRoles as suggested:
{
"accountId": "301424",
"emailSubject": "API Example - Populating Data in Templates",
"templateId": "44D9E888-xxxx-xxxx-xxxx-7071BC87A0DA",
"templateRoles": [{
"email": "john.doe#email.com",
"name": "John Doe",
"roleName": "Customer",
"tabs": {
"textTabs": [{
"tabLabel": "CustomerAddress",
"value": "123 Main St. San Francisco, CA 94105"
},
{
"tabLabel": "CustomerSSN",
"value": "12-345-6789"
}]
}
}],
"status": "sent"
}
But this did not populate any of the fields with the data I supplied.
What am I missing here?

Answer 1

I recently came across this issue and got hold of their support team. The docs using templateId and Recipients are just basically wrong. It will always fail. I think they'll change that soon.
{
"accountId": "301424",
"emailSubject": "API Example - Populating Data in Templates",
"templateId": "44D9E888-xxxx-xxxx-xxxx-7071BC87A0DA",
"templateRoles": [{
"email": "john.doe#email.com",
"name": "John Doe",
"roleName": "Customer",
"tabs": {
"textTabs": [{
"tabLabel": "CustomerAddress",
"value": "123 Main St. San Francisco, CA 94105"
},
{
"tabLabel": "CustomerSSN",
"value": "12-345-6789"
}]
}
}],
"status": "sent"
}
I created a Template on the UI and uploaded a doc. I then added a
Recipient from the UI and mapped a few fields in the document.
Apparently, you can supply an empty Recipient name and email despite the UI showing a red asterisk on the input field, as if implying it was required.
You only need to define the role field and you're good to go. So in this example, in your template (from the UI):
And you should be good to go.

Answer 2

Your JSON looks pretty good to me.
You don't need the accountId or emailSubject attributes and I'd recommend you leave them out.
Double-check that your tabLabel values are the exact same as the UI's Data Label setting.
As a test, you could also download the template by using the API. See Templates::get
Here's a PHP code example that sets template tab values.