TL;DR: Send a
POSTrequest to/v1/template/createwith a title, a file and at least one role to create an eSignature template via API. The call returns a template ID at once, and a webhook tells you when the template is ready. Our eSignature API page shows what else you can build.
Your app sends the same offer letter or service contract to new people every week. Each request uploads the file again and places every signature field from scratch. That code is slow to write and easy to get wrong.
A template moves that setup into one call you make once. After that, every send only names the signers.
What is a document template in an API?
A document template is a saved file with its signer roles and form fields already in place. You create it once and reuse it for each new signer.
A rubber stamp works the same way. You carve the design once, then press it on every page without drawing it again.
In the BoldSign API, each field belongs to a role instead of a person. A role is a placeholder, such as HR or Employee, that you fill with a real name and email address when you send.
What do you need before you create a template via API?
You need an API key and a file to turn into a template. Our free sandbox gives you both a key and a place to test.
- An API key, which you generate in your sandbox account.
- A PDF or other supported file, up to 25 files per template.
- One role for each signer, with the fields that role fills in.
The request body uses multipart/form-data when you upload files from disk. Use the FileUrls parameter instead when the file sits at a public web address.
How do you create a template via API?
Send a POST request to https://api.boldsign.com/v1/template/create with your API key in the X-API-KEY header. Our developer guide to creating templates via API lists every parameter.
- Set the required
Title, plus an optionalDocumentTitleandDocumentMessage. - Attach your file with
Files, or link to it withFileUrls. - Add a role in
Roleswith itsindex,nameandsignerType. - Place each field in the role’s
formFields, with a page number and position. - Send the request and save the
templateIdin the response.
The samples below create a template with one HR role and one signature field. Our help article on how to create templates walks through the same request.
curl -X 'POST' \
'https://api.boldsign.com/v1/template/create' \
-H 'accept: application/json' \
-H 'X-API-KEY: {YOUR_API_KEY}' \
-H 'Content-Type: multipart/form-data' \
-F 'DocumentMessage=Document message for signers' \
-F 'Files=@{YOUR_FILE_PATH};type=application/pdf' \
-F 'Title=Title of the template' \
-F 'DocumentTitle=Title of the document' \
-F 'Roles={
"name": "Hr",
"index": 1,
"defaultSignerName": "Alex",
"defaultSignerEmail": "alex@example.com",
"signerOrder": 1,
"signerType": "Signer",
"formFields": [
{
"id": "sign_id",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 50,
"y": 100,
"width": 100,
"height": 60
}
}
]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{YOUR_API_KEY}");
var templateClient = new TemplateClient(apiClient);
var documentFilePath = new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = "{YOUR_FILE_PATH}",
};
var filesToUpload = new List<IDocumentFile>
{
documentFilePath,
};
var signatureField = new FormField(
id: "sign_id",
type: FieldType.Signature,
pageNumber: 1,
bounds: new Rectangle(x: 50, y: 100, width: 100, height: 60));
var formFieldsCollections = new List<FormField>
{
signatureField,
};
var templateRole = new TemplateRole(
roleIndex: 1,
name: "Hr",
defaultSignerName: "Alex",
defaultSignerEmail: "alex@example.com",
signerOrder: 1,
signerType: SignerType.Signer,
formFields: formFieldsCollections);
var roles = new List<TemplateRole>
{
templateRole,
};
var templateRequest = new CreateTemplateRequest()
{
Title = "Title of the template",
DocumentMessage = "Document message for signers",
Files = filesToUpload,
DocumentTitle = "Title of the document",
Roles = roles
};
var templateCreated = templateClient.CreateTemplate(templateRequest);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
template_api = boldsign.TemplateApi(api_client)
form_field = boldsign.FormField(
fieldType="Signature",
page_number=1,
bounds=boldsign.Rectangle(x=50, y=100, width=100, height=60),
)
role = boldsign.TemplateRole(
index=1,
name="Hr",
defaultSignerName="Alex",
defaultSignerEmail="alex@example.com",
signerType="Signer",
signerOrder=1,
formFields=[form_field],
)
create_template_request = boldsign.CreateTemplateRequest(
title="Title of the template",
documentTitle="Title of the document",
documentMessage="Document message for signers",
roles=[role],
files=["YOUR_FILE_PATH"],
)
template_created = template_api.create_template(create_template_request=create_template_request)
<?php require_once "vendor/autoload.php";
use BoldSign\Configuration;
use BoldSign\Api\TemplateApi;
use BoldSign\Model\{FormField, Rectangle, TemplateRole, CreateTemplateRequest};
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$template_api = new TemplateApi($config);
$form_field = new FormField();
$form_field->setFieldType('Signature');
$form_field->setPageNumber(1);
$bounds = new Rectangle([50, 100, 100, 60]);
$form_field->setBounds($bounds);
$role = new TemplateRole();
$role->setIndex(1);
$role->setName('Hr');
$role->setDefaultSignerName('Alex');
$role->setDefaultSignerEmail('alex@example.com');
$role->setSignerType('Signer');
$role->setSignerOrder(1);
$role->setFormFields([$form_field]);
$create_template = new CreateTemplateRequest();
$create_template->setTitle('Title of the template');
$create_template->setDocumentTitle('Title of the document');
$create_template->setDocumentMessage('Document message for signers');
$create_template->setRoles([$role]);
$create_template->setFiles(['YOUR_FILE_PATH']);
$template_created = $template_api->createTemplate([$create_template]);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");
TemplateApi templateApi = new TemplateApi(client);
FormField signatureField = new FormField();
signatureField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
signatureField.setPageNumber(1);
Rectangle bounds = new Rectangle().x(50f).y(100f).width(100f).height(60f);
signatureField.setBounds(bounds);
TemplateRole templateRole = new TemplateRole();
templateRole.setIndex(1);
templateRole.setName("Hr");
templateRole.setDefaultSignerName("Alex");
templateRole.setDefaultSignerEmail("alex@example.com");
templateRole.setSignerType(TemplateRole.SignerTypeEnum.SIGNER);
templateRole.setSignerOrder(1);
templateRole.setFormFields(Arrays.asList(signatureField));
CreateTemplateRequest createTemplate = new CreateTemplateRequest();
createTemplate.setTitle("Title of the template");
createTemplate.setDocumentTitle("Title of the document");
createTemplate.setDocumentMessage("Document message for signers");
createTemplate.setRoles(Arrays.asList(templateRole));
File file = new File("YOUR_FILE_PATH");
createTemplate.setFiles(Arrays.asList(file));
TemplateCreated templateCreated = templateApi.createTemplate(createTemplate);
import { TemplateApi, CreateTemplateRequest, TemplateRole, Rectangle, FormField } from "boldsign";
import * as fs from "fs";
async function main() {
const templateApi = new TemplateApi();
templateApi.setApiKey("YOUR_API_KEY");
const bounds = new Rectangle();
bounds.x = 50;
bounds.y = 100;
bounds.width = 100;
bounds.height = 60;
const formField = new FormField();
formField.fieldType = FormField.FieldTypeEnum.Signature;
formField.pageNumber = 1;
formField.bounds = bounds;
const role = new TemplateRole();
role.index = 1;
role.name = "Hr";
role.defaultSignerEmail = "alex@example.com";
role.defaultSignerName = "Alex";
role.signerType = TemplateRole.SignerTypeEnum.Signer;
role.signerOrder = 1;
role.formFields = [formField];
const file = fs.createReadStream("YOUR_FILE_PATH");
const createTemplateRequest = new CreateTemplateRequest();
createTemplateRequest.title = "Title of the template";
createTemplateRequest.documentTitle = "Title of the document";
createTemplateRequest.documentMessage = "Document message for signers";
createTemplateRequest.roles = [role];
createTemplateRequest.files = [file];
const templateCreated = templateApi.createTemplate(createTemplateRequest);
}
main();
Use either the fileUrls or the files parameter in one request. The API rejects a request that holds both.
Why does template creation take a moment to finish?
Template creation is asynchronous. You get a template ID at once, but the files may still be processing in the background.
Listen for webhooks to know when the template is ready. A TemplateCreated event means it worked, and a TemplateCreateFailed event carries an error message you can act on.
Our available webhook events page lists both events. Check each request’s signature with the steps in verify webhook events. The Template not found guide covers the error you see when you send too early.
How do you send a document from your new template?
Call POST /v1/template/send with the templateId and a real signer for each role. The roles, files and fields stay exactly as you saved them.
Each role in the request names its roleIndex, signerName and signerEmail. Our guide to sending a document from a template shows the full request. You can also edit a template via API later, and each change applies to the next send.
Which BoldSign plan do you need for the API, and what does it cost?
Live API access comes with the Enterprise API plan, which starts at $30 a month with 40 envelopes. Extra envelopes cost $0.75 each, and the plan includes webhooks.
You can build and test first in our free sandbox, with no credit card. Sandbox documents carry a test watermark and are deleted after 14 days. Prices are in USD, as listed on the BoldSign pricing page in November 2026.
Where do you go next with templates via API?
Create one template in the sandbox and send it to yourself. Then add the roles and fields your workflow needs.
- Create a free API sandbox account and run the client URL (cURL) sample.
- Book a demo to walk through your template workflow with our team.
- Open a ticket in our support portal with a question about your request.
Frequently asked questions
What is a template in the BoldSign API?
A template is a saved document with its roles and form fields already set. You create it once and send it again with new signers each time.
Which endpoint creates a template?
Send a create (POST) request to https://api.boldsign.com/v1/template/create. Title is required, and the response returns a templateId.
Why does my new template ID not work right away?
Template creation runs in the background, so the files may still be processing. Wait for the TemplateCreated webhook event before you send from the template.
How many files can one template hold?
You can upload up to 25 files. Each document can have up to 1,000 pages and must be 25 megabytes or smaller.
Can I use files and fileUrls in the same request?
No. Each request takes either uploaded files or public file links, so pick the one that matches where your file is stored.
Is a document sent from an API template legally binding?
Yes, when the signers agree to sign electronically and the signed record is kept. Every document gets an audit trail. Check the rules for your document type and country.
Can I try the e signature API free before I pay?
Yes. Our free sandbox gives you full API access with no credit card. Sandbox documents carry a test watermark and are deleted after 14 days.
Is there a digital signature API free plan for live documents?
No, live documents need the Enterprise API plan, which starts at $30 a month with 40 envelopes. The free sandbox is for building and testing.