How to remove specific roles when sending a document from a Template using BoldSign API?

When working with templates that include multiple roles, there are scenarios where not all roles are required for a particular use case. For instance, if a template is designed with two roles but the document needs to be sent to only one signer, you can dynamically remove the unnecessary role when sending the document.

Follow these steps to remove some roles when sending a document from template:

Create a template in your account

In order to send a document from template, you first need to have a template created in your account. If you dont have one, follow this steps to create:

To create a template in the BoldSign web application, refer to the article Create Template.
To create a template using the API, follow the steps outlined in the article Create template through API.

Send the document with some role removed

When sending the document, you can remove the role from the template by specifying the roleRemovalIndices property and give the role index value of the role to be removed as was specified when creating a template.

Notes

If in your template, there are 3 roles: Tenat1, Tenant2 and Tenant3(index 1, 2 and 3, respectively). After removing the role at index 2 (i.e., Tenant 2), the remaining template role indices are reset, with Tenant1 remaining at index 1 and Tenant3 moving to index 2. Now, to update the Tenant3 details, you need to pass the roleIndex as 2 instead of 3

Use the following codes to send document from template with role removal indices:

Code snippet

curl -X 'POST' \ 'https://api.boldsign.com/v1/template/send?templateId=cda4932f-xxxx-4502-8a5e-72ce7883e727' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: {Your API Key}' \
     -H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
     -d '{
       "title": "Sample document",
       "message": "Kindly review and sign this.",
       "roles": [
    {
      "roleIndex": 1,
      "signerName": "{Signer name}",
      "signerEmail": "{Signer Email address}",
      "privateMessage": "Please check and sign the document.",
      "signerType": "Signer",
      "signerRole": "Manager",
        "locale": "EN"
    }
  ],
  
  "roleRemovalIndices": [2]
 }'

            var apiClient = new ApiClient("https://api.boldsign.com", "{Your API Key}");

            var templateClient = new TemplateClient(apiClient);

            var signatureField = new FormField(
                id: "sign",
                isRequired: true,
                type: FieldType.Signature,
                pageNumber: 1,
                bounds: new Rectangle(x: 100, y: 100, width: 100, height: 50));

            var formFieldCollections = new List<FormField>
{
    signatureField
};

            var templateRole = new Roles(
                roleSignerIndex: 1,
                roleSignerName: "David",
                roleSignerEmailAddress: "david@cubeflakes.com",
                formFields: formFieldCollections,
                locale: Locales.EN);

            templateRole.DeliveryMode = DeliveryMode.Email;

          
            var roles = new List<Roles>
{
    templateRole,
};
            var roleRemovalIndices = new int[] { 2 };
           
            var sendForSignFromTemplate = new SendForSignFromTemplate
            {
                TemplateId = "4fe17627-xxxx-41ff-xxxx-0af80fd77740",
                Roles = roles,
                RoleRemovalIndices = roleRemovalIndices
            };

            
            var documentCreated = await templateClient.SendUsingTemplateAsync(sendForSignFromTemplate).ConfigureAwait(false);

import requests

url = 'https://api.boldsign.com/v1/template/send?templateId=cda4932f-xxxx-4502-8a5e-72ce7883e727'

headers = {
    'accept': 'application/json',
    'X-API-KEY': '{Your API Key}',
    'Content-Type': 'application/json;odata.metadata=minimal;odata.streaming=true'
}

data = {
    "title": "Sample document",
    "message": "Kindly review and sign this.",
    "roles": [
        {
            "roleIndex": 1,
            "signerName": "{Signer name}",
            "signerEmail": "{Signer Email address}",
            "privateMessage": "Please check and sign the document.",
            "signerType": "Signer",
            "signerRole": "Manager",
            "locale": "EN"
        }
    ],
    "roleRemovalIndices": [2]
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print("Request successful!")
    print(response.json())
else:
    print("Request failed with status code", response.status_code)
    print(response.text)

const axios = require('axios');

const url = 'https://api.boldsign.com/v1/template/send?templateId=cda4932f-xxxx-4502-8a5e-72ce7883e727';

const headers = {
  'accept': 'application/json',
  'X-API-KEY': '{Your API Key}',
  'Content-Type': 'application/json;odata.metadata=minimal;odata.streaming=true'
};

const data = {
  title: "Sample document",
  message: "Kindly review and sign this.",
  roles: [
    {
      roleIndex: 1,
      signerName: "{Signer name}",
      signerEmail: "{Signer Email address}",
      privateMessage: "Please check and sign the document.",
      signerType: "Signer",
      signerRole: "Manager",
      locale: "EN"
    }
  ],
  roleRemovalIndices: [2]
};

axios.post(url, data, { headers })
  .then(response => {
    console.log('Request successful!');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed with status code', error.response.status);
    console.error(error.response.data);
  });

In the provided code example, replace templateId with the ID of the existing template to be used for sending the document and roleRemovalIndices with the role index value of the role you want to remove. Upon executing the provided code, the document will be created with the role removed and signature request will only be sent to the remaining roles.