DocuSign envelope created via API has no recipients - the template roles weren't mapped

TL;DR

The envelope was created with no recipients because the template roles were never mapped to people. List the template's roles, then pass each roleName with its recipient name and email in the API call. Verify the created envelope lists the recipients before sending.

The symptom

DocuSign envelope created via API has no recipients  -  the template roles weren't mapped

Steps

1. List the template roles

Call the template-recipients endpoint (or read the template) to get each roleName the template expects. Expected: The template's roleName list.

2. Map roles to recipients

In the envelope definition, include a templateRoles array: each entry has roleName plus the recipient's name and email. Expected: Every roleName paired with a real recipient.

3. Create and verify

Create the envelope, then read it back and check the recipients list is populated. Expected: Recipients present on the envelope.

4. Send only after verification

Do not send until the recipient list is confirmed; an envelope with no recipients cannot be routed. Expected: Verified recipients before sending.

When to use

• Created envelope shows no recipients
• Template-based creation via API
• The template works in the UI (where roles get filled manually)

When not to use

• Recipients were provided but rejected (check emails and role names for typos)
• The envelope is not template-based (add recipients directly)
• The API call itself failed (fix the call first)

Why it happens

In the UI, template roles are filled by the sender interactively. Via API there is no interactive step: roleName entries without recipient details create placeholders, and placeholders with no mapping resolve to nothing. The envelope builds successfully but has nobody to send to.

Edge cases

• roleName is case-sensitive: match the template exactly.
• Multiple recipients in one role: use signing groups or add each recipient.
• CC roles: they need mapping too, or they silently vanish.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yAIti7KzxzX7iinMBbNHFg