From the Trenches: Applying templates in Sender View

A common use case for integrations leveraging the DocuSign eSignature API is to create a draft envelope and open Sender View. We will refer to integration users as the person using the integration to send an envelope to their recipients. Within DocuSign Sender View, the integration user is able to edit the draft envelope prior to sending the envelope. One aspect of Sender View that we often receive support cases for is the ability to apply templates to the draft envelope within Sender View. In particular, integration users notice that recipients seem to be duplicated after a template is applied. Resolving this scenario of duplicate recipients when applying templates within Sender View can be simpler than building full support for applying templates with an API call directly and can make the integration user's experience much better.

Duplicate recipients

Once your integration user is inside of Sender View, they will be presented with options for modifying the envelope’s documents, recipients, tabs and other properties prior to sending it.

Sender View with options

One option presented in Sender View is Use A Template. This option can allow integration users to add additional documents from templates that already exist within their DocuSign account. However, when integration users choose that option, they may notice that their recipients are duplicated:

Sender View: adding a template can produce duplicate recipients

In this scenario, there is one recipient that came from the createEnvelope API call with a name and email address filled out, and another recipient from the template with no name or email address.

Why do the recipients duplicate?

One potential reason the recipients are duplicated is because the recipient created by the integration does not have a roleName property defined. A roleName allows you to define a placeholder recipient in a DocuSign template. To merge the recipient in the envelope with the one defined in your template, the roleName properties must align in order for the DocuSign platform to recognize that they are the same recipient.

What can the Integration user do?

Typically, the only option available to the integration user would be to manually merge these recipients. Setting the name, email, and routing order of the recipients to the same value will trigger DocuSign to recognize the two recipients as the same:

Sender View: Duplicate recipients detected by DocuSign

What can the integration developer do?

One potential option for integration developers is to allow their integration users to specify a value for the roleName property prior to sending the API call to create the envelope. In that case, your application can pass the specified roleName in the recipient definition of the envelope during the API call to create the envelope.

"recipients": {
    "signers": [
    {
        "email": "...student@gmail.com",
        "name": "Andy Singh",
        "recipientId": "1",
        "routingOrder": "1",
        "roleName": "Candidate",
      }
    ]
  }

As long as the integration user ensures that the roleName used is the same one specified in their templates, then the recipient definition should merge.

Sender View: Duplicate recipients merged into one

This result provides a better user experience for the integration user.

Additional resources

Andy Singh
Author
Andy Singh
Developer Support Engineer
Published