DocuSign "ENVELOPE_HAS_DUPLICATE_RECIPIENTS" when applying a template

Fix DocuSign "ENVELOPEHASDUPLICATE_RECIPIENTS" when applying a template

TL;DR

Give each template role a distinct recipient, or restructure so one person fills one role. The error fires when two roles resolve to the same name and email. Decide whether the person genuinely signs twice; if not, split the roles across people or collapse them into one.

{
  "errorCode": "ENVELOPE_HAS_DUPLICATE_RECIPIENTS",
  "message": "The envelope has duplicate recipients."
}

1. Print the resolved recipient list before sending: every role with its name and email. Expected: you see the same person on two roles.

2. If the person only needs to act once, assign the second role to someone else or leave it unassigned. Expected: each role maps to a distinct recipient.

3. If one person must fill two roles, collapse the template to a single role for them instead of duplicating. Expected: the envelope creates with one recipient entry.

4. When using composite templates, check that server templates and inline templates do not each add the same recipient. Expected: the merged recipient list contains each person once.

Use this when

• a multi-role template fails via API but works when filled in by hand
• the same person legitimately appears in two roles
• composite templates merge recipients from multiple sources

Not for this skill when

• recipients are genuinely different people (check for a data bug doubling one entry)
• the error is about invalid emails rather than duplicates
• you want the same person to sign the same document twice in sequence (use routing order on one recipient)

Variant phrasings

• docusign ENVELOPEHASDUPLICATE_RECIPIENTS template roles same person
• docusign duplicate recipients applying template api
• docusign one signer two roles template error
• docusign composite template duplicate recipient

Why it happens

DocuSign identifies recipients by name plus email, and a template with two roles assigned to the same person produces two identical recipient entries. The API rejects the ambiguity; the UI avoids it because a human would not assign the same person twice without noticing.

Edge cases

• Same email with different names (or vice versa) can still trip related validation; keep both consistent.
• Carbon-copy recipients count too; a signer who is also CC'd can trigger it.
• Leaving a role unassigned is fine at creation; you can add the recipient afterward.
• After restructuring the template, re-test every role combination, not just the failing one.

Provenance

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