Skip to main content
arrow-left Back to Docusign.com
Solved

Reducing JSON Payload Duplication for Multi-Template DocuSign Envelopes with Shared Signers

  • November 17, 2025
  • 1 reply
  • 21 views
R
New Voice
Forum|alt.badge.img+1

I need to send an envelope that is made from multiple server templates (compositeTemplates). There is a fixed set of signers (4) across the business process — each signer should only sign the templates that are assigned to them (not every signer signing every template).


My goals are:

  • Avoid repeating signer details (name/email/custom emailNotification) inside every composite template so the request JSON stays small and non-redundant.

  • Reuse “global” signer definitions (by recipientId / recipientIdGuid) and reference those signer IDs wherever a template role needs that person.

  • Achieve faster envelope creation / better API performance by reducing payload size and duplication.

When I try to use global signers and reference their recipientId (or recipientIdGuid) from inlineTemplates, DocuSign rejects the envelope with an error such as:

400: “The envelope is not complete and a  complete envelope requires document recipients, tab and a subject line.”

I need to know:

  1. What is the correct, supported way to keep signers global and reference them (if possible) !! and

  2. Whether doing so will improve API performance and best practices to achieve that !

{
  "emailSubject": "Please sign the documents",
  "status": "sent",

  "recipients": {
    "signers": [
      {
        "recipientId": "1",
        "recipientIdGuid": "11111111-1111-1111-1111-111111111111",
        "routingOrder": "1",
        "email": "alice.signer@example.com",
        "name": "Alice Signer",
        "emailNotification": {
          "emailSubject": "Alice — Please sign your documents",
          "emailBody": "Hello Alice,\n\nYou have documents to sign. Please complete your signing.\n\nThanks,\nTeam"
        }
      },
      {
        "recipientId": "2",
        "recipientIdGuid": "22222222-2222-2222-2222-222222222222",
        "routingOrder": "1",
        "email": "bob.signer@example.com",
        "name": "Bob Signer",
        "emailNotification": {
          "emailSubject": "Bob — Documents need your signature",
          "emailBody": "Hi Bob,\n\nA document requires your signature. Kindly review and sign.\n\nRegards,\nTeam"
        }
      },
      {
        "recipientId": "3",
        "recipientIdGuid": "33333333-3333-3333-3333-333333333333",
        "routingOrder": "2",
        "email": "carol.signer@example.com",
        "name": "Carol Signer",
        "emailNotification": {
          "emailSubject": "Carol — Signature requested",
          "emailBody": "Dear Carol,\n\nPlease sign the assigned documents.\n\nBest,\nTeam"
        }
      },
      {
        "recipientId": "4",
        "recipientIdGuid": "44444444-4444-4444-4444-444444444444",
        "routingOrder": "2",
        "email": "dave.signer@example.com",
        "name": "Dave Signer",
        "emailNotification": {
          "emailSubject": "Dave — Please complete pending signature",
          "emailBody": "Hello Dave,\n\nYour signature is required on the attached documents.\n\nTeam"
        }
      }
    ],
    "carbonCopies": [
      {
        "recipientId": "99",
        "recipientIdGuid": "99999999-9999-9999-9999-999999999999",
        "routingOrder": "99",
        "email": "admin@example.com",
        "name": "Admin Reviewer"
      }
    ]
  },

  "compositeTemplates": [
    {
      "compositeTemplateId": "1",
      "serverTemplates": [
        { "sequence": "1", "templateId": "TEMPLATE_ID_1" }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "recipientId": "1",
                "recipientIdGuid": "11111111-1111-1111-1111-111111111111",
                "roleName": "Seller"
              },
              {
                "recipientId": "3",
                "recipientIdGuid": "33333333-3333-3333-3333-333333333333",
                "roleName": "ApproverA"
              }
            ]
          }
        }
      ]
    },

    {
      "compositeTemplateId": "2",
      "serverTemplates": [
        { "sequence": "1", "templateId": "TEMPLATE_ID_2" }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "recipientId": "2",
                "recipientIdGuid": "22222222-2222-2222-2222-222222222222",
                "roleName": "Buyer"
              },
              {
                "recipientId": "4",
                "recipientIdGuid": "44444444-4444-4444-4444-444444444444",
                "roleName": "ApproverB"
              }
            ]
          }
        }
      ]
    },

    {
      "compositeTemplateId": "3",
      "serverTemplates": [
        { "sequence": "1", "templateId": "TEMPLATE_ID_3" }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "recipientId": "3",
                "recipientIdGuid": "33333333-3333-3333-3333-333333333333",
                "roleName": "FinalSigner"
              },
              {
                "recipientId": "1",
                "recipientIdGuid": "11111111-1111-1111-1111-111111111111",
                "roleName": "CoSigner"
              }
            ]
          }
        }
      ]
    },

    {
      "compositeTemplateId": "4",
      "serverTemplates": [
        { "sequence": "1", "templateId": "TEMPLATE_ID_4" }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "recipientId": "4",
                "recipientIdGuid": "44444444-4444-4444-4444-444444444444",
                "roleName": "Verifier"
              },
              {
                "recipientId": "2",
                "recipientIdGuid": "22222222-2222-2222-2222-222222222222",
                "roleName": "Seller"
              }
            ]
          }
        }
      ]
    }
  ]
}

 

Best answer by Mahmoud.Essam

Hello ​@RKS0 


With composite Templates in Docusign, the platform expects recipients (signers, carbon copies, etc.) to be defined specifically inside each inlineTemplate that is used to “apply” roles to a given serverTemplate.

Recipients must be mapped to template roles at the compositeTemplate/inlineTemplate level, not only once globally at the envelope root.


Docusign does NOT allow you to set recipients globally (at the envelope level) and reference them only by recipientId or recipientIdGuid within inlineTemplates. At present, this reference-only pattern will be rejected as incomplete, resulting in errors like:
400: “The envelope is not complete and a complete envelope requires document recipients, tab and a subject line.”

Regarding your question about best practices:

1-You can minimize redundancy by only including minimal necessary recipient fields inside each inlineTemplate:

2-Use the exact same recipientId, name, and email for the same person in each appearance—they must match across all references.
3-You can omit optional fields in the inlineTemplate, such as emailNotification, unless you need template-level customization.

4-Envelope-Level Customization:
If you need custom email notifications or other recipient options, set those at the envelope or first appearance, not redundantly each time, unless a per-template notification is needed.

5-Template Role Mapping:
Always ensure the recipient’s roleName in inlineTemplates matches exactly the role set in the serverTemplate.

6-Payload Considerations & Performance:
While duplication is somewhat unavoidable when using compositeTemplates, modern payload sizes for recipient definitions are small relative to attached documents. Performance gains from trimming recipient detail duplication are generally minimal compared to optimizing the number and size of attached documents.
Avoid unnecessary fields or empty parameters in recipient definitions to reduce JSON size.

 

 

1 reply

M
Docusign Employee
Forum|alt.badge.img+5
  • Mahmoud.EssamDocusign Employee
  • Docusign Employee
  • Answer
  • November 18, 2025

Hello ​@RKS0 


With composite Templates in Docusign, the platform expects recipients (signers, carbon copies, etc.) to be defined specifically inside each inlineTemplate that is used to “apply” roles to a given serverTemplate.

Recipients must be mapped to template roles at the compositeTemplate/inlineTemplate level, not only once globally at the envelope root.


Docusign does NOT allow you to set recipients globally (at the envelope level) and reference them only by recipientId or recipientIdGuid within inlineTemplates. At present, this reference-only pattern will be rejected as incomplete, resulting in errors like:
400: “The envelope is not complete and a complete envelope requires document recipients, tab and a subject line.”

Regarding your question about best practices:

1-You can minimize redundancy by only including minimal necessary recipient fields inside each inlineTemplate:

2-Use the exact same recipientId, name, and email for the same person in each appearance—they must match across all references.
3-You can omit optional fields in the inlineTemplate, such as emailNotification, unless you need template-level customization.

4-Envelope-Level Customization:
If you need custom email notifications or other recipient options, set those at the envelope or first appearance, not redundantly each time, unless a per-template notification is needed.

5-Template Role Mapping:
Always ensure the recipient’s roleName in inlineTemplates matches exactly the role set in the serverTemplate.

6-Payload Considerations & Performance:
While duplication is somewhat unavoidable when using compositeTemplates, modern payload sizes for recipient definitions are small relative to attached documents. Performance gains from trimming recipient detail duplication are generally minimal compared to optimizing the number and size of attached documents.
Avoid unnecessary fields or empty parameters in recipient definitions to reduce JSON size.

 

 

R
Code of ConductAccessibility statement

Docusign Community

Code of Conduct