Template
Templates are created in the same way as regular documents, but instead of associating signature fields with people, we simply associate fields with roles. A role is simply a placeholder for a real person. For example, if we have a purchase order that will always be signed by two people, one from the company and one from the customer, we can create a template with two roles, Customer and Representative.
This section demonstrates how to create, list, and delete templates. Templates can be created programmatically or via the BoldSign web interface and then used in your application.
Asynchronous template processing
The process of template create is asynchronous. Although you will promptly receive the template ID upon initiation, the actual file may still be undergoing processing in the background. To determine whether the template has been successfully created, you must listen for the webhooks.
The system will trigger either a TemplateCreated or TemplateCreateFailed event, indicating the success or failure of the template create, respectively. In the event of failure, the system will send a TemplateCreateFailed event along with an accompanying error message. It is imperative to address and resolve this error to ensure the proper creating of the template in the next request.
Template not found
If you discover that a template is not present in your account even after receiving a templateId in the API response, it is directly tied to the asynchronous template processing, as explained in the preceding section. To ascertain whether the template has been successfully created, you should actively monitor the TemplateCreated and TemplateCreateFailed webhook events. These events will provide confirmation regarding the status of the template, indicating whether it has been successfully created or if an issue has occurred during the process.
Create template
post/v1/template/createWhen you need to send the same contracts out for signature to different groups of people repeatedly, you can use templates to save time. Once a template is created, sending contracts using that template takes less than a minute. Templates can be created for both self-signing and sending signature requests to other signers. This API supports both multipart/form-data and application/json content types.
Code snippet using multipart/form-data
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=@Bill-of-Sale.pdf;type=application/pdf' \
-F 'Title=title of the template' \
-F 'AllowMessageEditing=true' \
-F 'Description=testingDescription' \
-F 'DocumentTitle=title of the document' \
-F 'AllowNewFiles=true' \
-F 'AllowModifyFiles=true' \
-F 'Roles={
"name": "Hr",
"index": 1,
"defaultSignerName": "Alex Gayle",
"defaultSignerEmail": "alexgayle@cubeflakes.com",
"signerOrder": 1,
"signerType": "Signer",
"formFields": [
{
"id": "sign_id",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 50,
"y": 100,
"width": 100,
"height": 60
},
"isRequired": true,
"backgroundHexColor": "string"
}
]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "API-KEY");
var templateClient = new TemplateClient(apiClient);
var documentFilePath = new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = @"D:\Bill-of-Sale.pdf",
};
var filesToUpload = new List<IDocumentFile>
{
documentFilePath,
};
var signatureField = new FormField(
id: "sign_id",
backgroundHexColor: "string",
type: FieldType.Signature,
pageNumber: 1,
bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30));
var formFieldsCollections = new List<FormField>
{
signatureField,
};
var templateRole = new TemplateRole(
roleIndex: 1,
name: "Hr",
defaultSignerName: "Alex Gayle",
defaultSignerEmail: "alexgayle@cubeflakes.com",
signerOrder: 1,
signerType: SignerType.Signer,
formFields: formFieldsCollections,
locale: Locales.EN);
var roles = new List<TemplateRole>
{
templateRole,
};
var templateRequest = new CreateTemplateRequest()
{
Title = "title of the template",
DocumentMessage = "document message for signers",
Files = filesToUpload,
Description = "testingDescription",
DocumentTitle = "title of the document",
AllowNewFiles = true,
AllowModifyFiles = true,
Roles = roles
};
var templateCreated = templateClient.CreateTemplate(templateRequest);
import requests
import json
url = "https://api.boldsign.com/v1/template/create"
payload = {
"BrandId": "",
"EnableReassign": "true",
"AllowNewRoles": "true",
"EnablePrintAndSign": "false",
"DocumentMessage": "document message for signers",
"EnableSigningOrder": "false",
"UseTextTags": "false",
"Title": "title of the template",
"AllowMessageEditing": "true",
"Description": "testingDescription",
"DocumentTitle": "title of the document",
"AllowNewFiles": True,
"AllowModifyFiles": True,
"Roles": json.dumps(
{
"name": "Hr",
"index": 1,
"defaultSignerName": "Alex Gayle",
"defaultSignerEmail": "alexgayle@boldsign.dev",
"signerOrder": 1,
"signerType": "Signer",
"locale": "EN",
"imposeAuthentication": "None",
"deliveryMode": "Email",
"formFields": [
{
"id": "sign_id",
"name": "sign",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {"x": 50, "y": 100, "width": 100, "height": 60},
"isRequired": True,
"backgroundHexColor": "string"
}
],
"allowRoleEdit": True,
"allowRoleDelete": True,
}
),
}
files = [
("Files", ("file", open("sample.docx", "rb"), "application/msword"))
]
headers = {
"accept": "application/json",
"X-API-KEY": "<<<API-KEY>>>",
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('BrandId', '');
form.append('EnableReassign', 'true');
form.append('AllowNewRoles', 'true');
form.append('EnablePrintAndSign', 'false');
form.append('DocumentMessage', 'document message for signers');
form.append('EnableSigningOrder', 'false');
form.append('UseTextTags', 'false');
form.append('AllowNewFiles', 'true');
form.append('AllowModifyFiles', 'true');
form.append('Files', fs.readFileSync('Bill-of-Sale.pdf;type=application/pdf'), 'Bill-of-Sale.pdf;type=application/pdf');
form.append('Title', 'title of the template');
form.append('AllowMessageEditing', 'true');
form.append('Description', 'testingDescription');
form.append('DocumentTitle', 'title of the document');
form.append('Roles', '{\n "name": "Hr",\n "index": 1,\n "defaultSignerName": "Alex Gayle",\n "defaultSignerEmail": "alexgayle@cubeflakes.com",\n "signerOrder": 1,\n "signerType": "Signer",\n "locale": "En",\n "deliveryMode": "Email",\n "imposeAuthentication": "None",\n "formFields": [\n {\n "id": "sign_id",\n "name": "sign",\n "fieldType": "Signature",\n "pageNumber": 1,\n "bounds": {\n "x": 50,\n "y": 100,\n "width": 100,\n "height": 60\n },\n "isRequired": true\n }\n ],\n "allowRoleEdit": true,\n "allowRoleDelete": true\n}');
const response = await axios.post(
' https://api.boldsign.com/v1/template/create',
form,
{
headers: {
...form.getHeaders(),
'accept': 'application/json',
'X-API-KEY': '<API-KEY>',
'Content-Type': 'multipart/form-data'
}
}
);
Code snippet using application/json
curl -X POST \
'https://api.boldsign.com/v1/template/create' \
-H 'accept: application/json' \
-H 'X-API-KEY: {your API key}' \
-H 'Content-Type: application/json' \
-d '{
"DocumentMessage": "document message for signers",
"Files": [
"data:application/pdf;base64,JVBERi0xLjcKJcfs..."
],
"Title": "title of the template",
"AllowMessageEditing": true,
"Description": "testingDescription",
"DocumentTitle": "title of the document",
"Roles": [
{
"name": "Hr",
"index": 1,
"defaultSignerName": "Alex Gayle",
"defaultSignerEmail": "alexgayle@cubeflakes.com",
"signerOrder": 1,
"signerType": "Signer",
"formFields": [
{
"id": "sign_id",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 50,
"y": 100,
"width": 100,
"height": 60
},
"isRequired": true,
"backgroundHexColor": "string"
}
]
}
]
}'
import requests
import json
url = "https://api.boldsign.com/v1/template/create"
payload = {
"BrandId": "",
"EnableReassign": True,
"AllowNewRoles": True,
"EnablePrintAndSign": False,
"DocumentMessage": "document message for signers",
"EnableSigningOrder": False,
"UseTextTags": False,
"Title": "title of the template",
"AllowMessageEditing": True,
"Description": "testingDescription",
"DocumentTitle": "title of the document",
"Files": [
"data:application/pdf;base64,JVBERi0xLjcKJcfs..."
],
"Roles": [
{
"name": "Hr",
"index": 1,
"defaultSignerName": "Alex Gayle",
"defaultSignerEmail": "alexgayle@boldsign.dev",
"signerOrder": 1,
"signerType": "Signer",
"locale": "EN",
"imposeAuthentication": "None",
"deliveryMode": "Email",
"formFields": [
{
"id": "sign_id",
"name": "sign",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {"x": 50, "y": 100, "width": 100, "height": 60},
"isRequired": True,
"backgroundHexColor": "string"
}
],
"allowRoleEdit": True,
"allowRoleDelete": True,
}
]
}
headers = {
"Content-Type": "application/json",
"accept": "application/json",
"X-API-KEY": "<<<API-KEY>>>", # Replace <<<API-KEY>>> with your actual API key
}
# Convert payload to JSON string
payload_json = json.dumps(payload)
# Send POST request
response = requests.post(url, headers=headers, data=payload_json)
# Print response
print(response.text)
const axios = require('axios');
const fs = require('fs');
const payload = {
BrandId: '',
EnableReassign: true,
AllowNewRoles: true,
EnablePrintAndSign: false,
DocumentMessage: 'document message for signers',
EnableSigningOrder: false,
UseTextTags: false,
Files: [
'data:application/pdf;base64,JVBERi0xLjcKJcfs...'
],
Title: 'title of the template',
AllowMessageEditing: true,
Description: 'testingDescription',
DocumentTitle: 'title of the document',
Roles: [
{
name: 'Hr',
index: 1,
defaultSignerName: 'Alex Gayle',
defaultSignerEmail: 'alexgayle@cubeflakes.com',
signerOrder: 1,
signerType: 'Signer',
locale: 'EN',
imposeAuthentication: 'None',
deliveryMode: 'Email',
formFields: [
{
id: 'sign_id',
name: 'sign',
fieldType: 'Signature',
pageNumber: 1,
bounds: { x: 50, y: 100, width: 100, height: 60 },
isRequired: true,
backgroundHexColor: 'string'
}
],
allowRoleEdit: true,
allowRoleDelete: true
}
]
};
const response = await axios.post(
'https://api.boldsign.com/v1/template/create',
payload,
{
headers: {
'accept': 'application/json',
'X-API-KEY': '<API-KEY>', // Replace <API-KEY> with your actual API key
'Content-Type': 'application/json'
}
}
);
console.log(response.data);
<?php
require_once "vendor/autoload.php";
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
$client = new Client();
$payload = [
"BrandId" => "",
"EnableReassign" => true,
"AllowNewRoles" => true,
"EnablePrintAndSign" => false,
"DocumentMessage" => "document message for signers",
"EnableSigningOrder" => false,
"UseTextTags" => false,
"Title" => "title of the template",
"AllowMessageEditing" => true,
"Description" => "testingDescription",
"DocumentTitle" => "title of the document",
"Files" => [
"data:application/pdf;base64,JVBERi0xLjcKJcfs..."
],
"Roles" => [
[
"name" => "Hr",
"index" => 1,
"defaultSignerName" => "Alex Gayle",
"defaultSignerEmail" => "alexgayle@cubeflakes.com",
"signerOrder" => 1,
"signerType" => "Signer",
"locale" => "EN",
"imposeAuthentication" => "None",
"deliveryMode" => "Email",
"formFields" => [
[
"id" => "sign_id",
"name" => "sign",
"fieldType" => "Signature",
"pageNumber" => 1,
"bounds" => ["x" => 50, "y" => 100, "width" => 100, "height" => 60],
"isRequired" => true,
"backgroundHexColor"=> "string"
]
],
"allowRoleEdit" => true,
"allowRoleDelete" => true
]
]
];
$headers = [
'accept' => 'application/json',
'X-API-KEY' => '{your API key}', // Replace with your actual API key
'Content-Type' => 'application/json'
];
$request = new Request('POST', 'https://api.boldsign.com/v1/template/create', $headers, json_encode($payload));
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
Request body
| TitlestringRequired | The title of the template. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Descriptionstring | The description of the template. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DocumentTitlestring | This is the name of the document that will be displayed in the BoldSign user interface as well as in the signature request email. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DocumentMessagestring | The message that will be seen by all recipients. You can include any instructions related to this document that the signer should be aware of before signing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Filesarray | The files to be uploaded for the template. .pdf, .png, .jpg, and .docx are supported file formats. You may upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25MB in size. The base64 format is data:application/{{fileType}};base64,{{content}} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| FileUrlsarray | The URL of the file to be uploaded that is publicly accessible. .pdf, .png, .jpg, and .docx are supported file formats. You may upload up to 25 files. Each document may have a maximum of 1000 pages and must be no larger than 25MB in size. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Rolesarray | A role is simply a placeholder for a real person. For example, if we have a purchase order that will always be signed by two people, one from the company and one from the customer, we can create a template with two roles,
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AllowNewFilesboolean | When set to true, the sender can add new files while using this template to send signature requests. If set to false, the sender will not be able to add new files. Defaults to true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AllowModifyFilesboolean | When set to true, the sender can replace or delete existing files while using this template to send signature requests. If set to false, the sender will not have the ability to replace or delete files. Defaults to true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| CCarray | You can add anyone who needs to receive a copy of the signed document by adding their email address. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| BrandIdstring | You can customize the branding of signature request emails and document signing pages with your own colors, logos, and other elements. The brand id can be obtained from both the branding API and the web app branding page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| AllowMessageEditingboolean | When disabled, you cannot change the message while creating a document with this template. The default value is true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| AllowNewRolesboolean | When disabled, you cannot add additional signers to the document. The default value is true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| EnableReassignboolean | When disabled, the reassign option is not available after sending the document out for signature. The default value is true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| EnablePrintAndSignboolean | When enabled, the document can be printed and signed offline. The default value is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| EnableSigningOrderboolean | When enabled, signers can only sign the document in the order specified. Furthermore, the next signer will be notified when the previous signer has signed the document. The default value is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
DocumentInfoarray | This is used to specify the title and description of the document in the various supported languages.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| UseTextTagsboolean | When enabled, it will convert all the tags defined in the document to BoldSign form fields. The default value is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TextTagDefinitionsarray | This can be used for long text tag handling.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| autoDetectFieldsboolean | When enabled, it will convert all the fillable form fields in the document to BoldSign form fields. BoldSign supports Textbox, Checkbox, Radio button, and Signature form fields. Other fields will not be detected as of now. The default value is false. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| labelsstring[] | The labels (Tags) that will be assigned to the document when a document is created using this template which can be used to categorize and filter the documents. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| templateLabelsstring[] | The template labels (Tags) are added to the template to categorize and filter the documents. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| onBehalfOfstring | The email address of the user to create the template on their behalf. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recipientNotificationSettingsobject | Control email notifications to recipients or CC collectively by configuring properties within
|
Example response
201 Created
{
"templateId": "4e2375dd-xxxx-xxxx-xxxx-870952cee6f8"
}