When dealing with complex agreements or contracts, it’s often necessary to combine multiple templates into a single document before sending it out for signatures.
Consider a legal firm that needs to send out a comprehensive agreement package to a client. The package might include a standard contract, a confidentiality agreement, and an appendix with specific terms. Typically, each of these forms exists as a separate template. Instead of sending these documents individually, they can use an API to merge the templates into a single, cohesive document. This ensures that the client receives a well-organized, complete agreement in one go.
In this blog, we’ll take a detailed look at how to implement this process using the BoldSign API, along with code examples to guide you through each step. For comprehensive guidance on sending documents with multiple templates, refer to the official BoldSign Send Document Using Multiple Templates documentation.
Please note that the following conditions are not supported when merging templates:
- Templates with different signer types: If one template has a role as a signer and the other template has the same role as a reviewer or in-person signer, the merge request will fail. The roles must be of the same signer type.
- Templates with different signer authentication modes: If one template has a role that requires SMS OTP for authentication and the other template with the same role require it to use an access code for authentication, the merge request will fail. Both templates must have the same signer authentication mode.
- Templates with different signer languages: If one template has a role set to use a specific signer language, such as English, and the other template with the same uses a different signer language, such as French, the merge request will fail. Both templates must be set to the same signer language.
- Templates must be active and accessible: If any template ID is invalid, deleted, or unavailable in your account, the merge request will fail.
Step-by-Step Guide
Let’s see how to send a document containing multiple templates for signature via the API.
Step 1: Create templates in BoldSign
To perform merge and send, you need to retrieve the template IDs of the templates you are going to use. If you don’t have templates in your account, you can create them using either the API or web app:
Step 2: Merge and send
Once you have your template IDs, provide them to templateIds. Modify the signerEmail and signerName properties to match the email address and name of the signer to whom you intend to send the document. If your templates already contain form fields and you want to prefill those values while merging, refer to the official BoldSign documentation: Send document using multiple templates by filling existing form fields
Note on role index: The roleIndex represents the position of a role in a sequence and must increase linearly 1, 2, 3, and so on. When multiple templates are merged, the numbering continues from the next available value across templates (for example, if Template 1 uses 1 and 2, Template 2 begins at 3, and if Template 2 uses 3 and 4, Template 3 begins at 5). Valid roleIndex values range from 1 to 50.
Example Code for Sending a Document Using Multiple Templates
The following code snippets demonstrate how to send documents for signature using multiple templates via the API.
curl -X 'POST' \
'https://api.boldsign.com/v1/template/mergeAndSend' \
-H 'accept: application/json' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json;odata.metadata=minimal;odata.streaming=true' \
-d '{
"templateIds": ["TEMPLATE_ID_1", "TEMPLATE_ID_2"],
"title": "DOCUMENT_TITLE",
"message": "Kindly review and sign this.",
"roles": [
{
"roleIndex": 1,
"signerName": "david",
"signerOrder": 1,
"signerEmail": "[email protected]",
"privateMessage": "Please check and sign the document.",
"signerType": "Signer",
"signerRole": "Manager",
"locale": "EN"
}
]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var templateClient = new TemplateClient(apiClient);
var role = new Roles
{
RoleIndex = 1,
SignerName = "david",
SignerOrder = 1,
SignerEmail = "[email protected]",
PrivateMessage = "Please check and sign the document.",
SignerType = SignerType.Signer,
SignerRole = "Manager",
Locale = Locales.EN
};
var mergeAndSendForSign = new MergeAndSendForSign
{
TemplateIds = new[] { "TEMPLATE_ID_1", "TEMPLATE_ID_2" },
Title = "DOCUMENT_TITLE",
Message = "Kindly review and sign this.",
Roles = new List<Roles> { role }
};
var documentCreated = templateClient.MergeAndSend(mergeAndSendForSign);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
template_api = boldsign.TemplateApi(api_client)
role = boldsign.Role(
roleIndex=1,
signerName="david",
signerOrder=1,
signerEmail="[email protected]",
privateMessage="Please check and sign the document.",
signerType="Signer",
signerRole="Manager",
locale="EN"
)
form = boldsign.MergeAndSendForSignForm(
templateIds=["TEMPLATE_ID_1", "TEMPLATE_ID_2"],
title="DOCUMENT_TITLE",
message="Kindly review and sign this.",
roles=[role]
)
document_created = template_api.merge_and_send(form)
<?php
require_once "vendor/autoload.php";
use BoldSign\Configuration;
use BoldSign\Api\TemplateApi;
use BoldSign\Model\{Role,MergeAndSendForSignForm};
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$templateApi = new TemplateApi($config);
$role = new Role();
$role->setRoleIndex(1);
$role->setSignerName('david');
$role->setSignerOrder(1);
$role->setSignerEmail('[email protected]');
$role->setPrivateMessage('Please check and sign the document.');
$role->setSignerType('Signer');
$role->setSignerRole('Manager');
$role->setLocale('EN');
$form = new MergeAndSendForSignForm();
$form->setTemplateIds(['TEMPLATE_ID_1', 'TEMPLATE_ID_2']);
$form->setTitle('DOCUMENT_TITLE');
$form->setMessage('Kindly review and sign this.');
$form->setRoles([$role]);
$documentCreated = $templateApi->mergeAndSend($form);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");
TemplateApi templateApi = new TemplateApi(client);
Role role = new Role();
role.setRoleIndex(1);
role.setSignerName("david");
role.setSignerOrder(1);
role.setSignerEmail("[email protected]");
role.setPrivateMessage("Please check and sign the document.");
role.setSignerType(Role.SignerTypeEnum.SIGNER);
role.setSignerRole("Manager");
role.setLocale(Role.LocaleEnum.EN);
MergeAndSendForSignForm form = new MergeAndSendForSignForm();
form.setTemplateIds(Arrays.asList("TEMPLATE_ID_1", "TEMPLATE_ID_2"));
form.setTitle("DOCUMENT_TITLE");
form.setMessage("Kindly review and sign this.");
form.setRoles(Arrays.asList(role));
var documentCreated = templateApi.mergeAndSend(form);
import { TemplateApi, MergeAndSendForSignForm, Role } from "boldsign";
async function main() {
const templateApi = new TemplateApi();
templateApi.setApiKey("YOUR_API_KEY");
const role = new Role();
role.roleIndex = 1;
role.signerName = "david";
role.signerOrder = 1;
role.signerEmail = "[email protected]";
role.privateMessage = "Please check and sign the document.";
role.signerType = "Signer";
role.signerRole = "Manager";
role.locale = "EN";
const form = new MergeAndSendForSignForm();
form.templateIds = ["TEMPLATE_ID_1", "TEMPLATE_ID_2"];
form.title = "DOCUMENT_TITLE";
form.message = "Kindly review and sign this.";
form.roles = [role];
const documentCreated = await templateApi.mergeAndSend(form);
}
main();
Conclusion
Combining multiple templates into a single document before sending it for signature is convenient. It eases both the sending and signing processes, preventing documents from getting overlooked or forgotten. BoldSign lets senders use this feature to improve everyone’s signing experience. Prefer the BoldSign web app? You can merge templates directly in the BoldSign web app using the Merge & Use option. Follow the step-by-step instructions in the official guide How to merge multiple templates and send out for signature?
Start your 30-day free BoldSign trial today and try merging and sending multiple templates as one document. We value your feedback, so please share your thoughts below. If you have any questions or need more information about our services, don’t hesitate to schedule a demo or reach out to our support team through our support portal.
