TL;DR: You can send several templates as one document for signature with a single call to the BoldSign mergeAndSend endpoint. Pass the template IDs, set each signer’s role, and we send one combined document. Our eSignature API page shows what else the API can do.
A law firm sends every new client the same three forms: a standard contract, a confidentiality agreement and an appendix of terms. Each form lives as its own template. Sent one by one, the client gets three emails and may miss one.
Merging the templates fixes that. The client gets one complete package and signs it in one sitting. This guide shows how to do it with the BoldSign API, with code samples in six languages.
What does merging templates mean?
Merging takes two or more saved templates and joins them into one document before sending. The signer sees one file with every page and field in order.
Think of it like stapling three printed forms together before you hand them over. Each form keeps its own fields, but the person signs the whole set at once.
How do you send a document using multiple templates via the API?
You call one endpoint, POST https://api.boldsign.com/v1/template/mergeAndSend, with a list of template IDs and the signer details. Our reference page on how to send a document using multiple templates lists every property.
Step 1: Get your template IDs
Each template you merge needs an ID. Create templates first if your account has none yet. You can build them in two ways:
- In the web app, by following our guide to create a template.
- In code, with the create template API.
- From an existing template list, by copying the ID of each template you want.
Step 2: Merge and send
Put your template IDs in templateIds. Then change signerEmail and signerName to the person who should sign.
Prefill fields as part of the same call when your templates already hold form fields. Our guide on how to send a document using multiple templates by filling existing form fields shows how.
How does roleIndex work when you merge templates?
The roleIndex gives each role its place in the sequence. It must rise by one each time (1, 2, 3) and stay between 1 and 50.
Numbering carries on across templates instead of starting again:
- Template 1 uses roles 1 and 2.
- Template 2 then starts at role 3 and uses 3 and 4.
- Template 3 then starts at role 5.
What happens to shared signers and fields?
We combine matching roles into one, so a signer gets one request. The rules come from our API reference:
- Without a signing order, roles with the same role, email and name become one role.
- With a signing order, the order must also match before roles combine.
- Fields with the same name and type, set for one signer, update together through
existingFormFields.
Send files with either fileUrls or files in one request. Our API does not accept both together.
What does the code look like?
These samples send two templates to one signer as a single document. Each call returns a documentId for the new document.
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": "david@cubeflakes.com",
"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 = "david@cubeflakes.com",
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="david@cubeflakes.com",
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('david@cubeflakes.com');
$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("david@cubeflakes.com");
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 = "david@cubeflakes.com";
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();
Can you merge templates without the API?
Yes. In the BoldSign web app, select two or more templates under Browse templates, then select Merge & Use.
You then edit the recipients, place any extra fields and select Send. Our help article on how to merge multiple templates and send them for signature walks through each screen. You can try it with a 30-day free trial.
Which BoldSign plan do you need for the merge and send API?
Every BoldSign plan includes sandbox API access for testing, so you can try mergeAndSend at no cost. Live API calls need the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly.
Extra envelopes on the Enterprise API plan cost $0.75 each. Prices are in USD, as of November 2026, and the pricing page lists every plan.
How do you start merging templates with the API?
The quickest test is two small templates and one signer in the sandbox. Here are three next steps.
- Create a free API sandbox account and send your first merged document.
- Request a demo to talk through your integration with our team.
- Open a support ticket when a merge request returns an error.
Frequently asked questions
Can I merge multiple templates into one document with an API?
Yes. The BoldSign mergeAndSend endpoint takes a list of template IDs and sends them to your signers as one document in a single request.
What does the mergeAndSend endpoint return?
A successful call returns a JavaScript Object Notation (JSON) object with one field, documentId. Store it so you can check the status or download the signed file later.
How does roleIndex work across merged templates?
Role numbers run in order across the whole set. The second template starts at 3 when the first one uses roles 1 and 2. Values go from 1 to 50.
Is there a limit on how many templates I can merge?
Our API reference lets you pass one or more template IDs and states no maximum. Role index values still cap the merged document at 50 roles.
What happens when two templates share the same signer?
We combine them into one role when the role, email and name match. With a signing order on, the order must match as well.
Can I prefill form fields when I merge templates?
Yes. Use the existingFormFields property with the template's position in the list. A field with the same name and type in two templates, set for one signer, updates in both.
Can I merge templates without writing code?
Yes. In the BoldSign web app, select two or more templates in Browse templates, then select Merge & Use. You then add recipients and send as usual.
Is a document sent from merged templates legally binding?
Yes, when it meets the same rules as any electronic signature, such as the signer agreeing to sign electronically. Merging templates does not change how the signature works. Check the rules for your document type and country.