TL;DR: The BoldSign Edit Template API updates an existing template from code, including its title, message, signer roles and form fields. Send only the top-level fields you want to change, and send complete roles when you change nested data. Our eSignature API page covers the rest of the platform.
Your app sends the same offer letter template every day. Then HR adds an approval step, and someone has to fix the template by hand in every account.
Manual edits like this drift apart between sandbox and production. The Edit Template API lets your code make the change instead, so every copy stays the same.
What is the BoldSign Edit Template API?
The Edit Template API is one PUT request that changes a saved template. You pass the template ID and the fields you want to update.
A recipe card works in a similar way. You can cross out “1 cup of sugar” and write “half a cup” without rewriting the whole card. The template keeps its document, and only the settings you send change.
Why edit templates programmatically?
Templates act like living settings for your signing workflow. They change as your business changes.
- HR adds a new approval step.
- Legal updates a policy clause or a required notice.
- Operations makes a new field mandatory.
Manual dashboard edits make templates drift between sandbox and production. API edits run from your backend or your deployment pipeline, so templates stay in step with your code.
What can you update with the Edit Template API?
You can update both the template’s text and the people and fields inside it. The Edit Template reference lists every property.
Template details
- Title: rename the template to match its purpose.
- Description: explain what the template is for.
- Document title: change the title that signers see.
- Document message: update the message sent with the signing request.
Signers and fields
- Signer roles: add, remove, reorder or rename roles such as Manager or Client.
- Form fields: add or change signature, text, date and checkbox fields on each page.
- Signing order: turn the order on or off with
enableSigningOrder.
What can’t you change with the Edit Template API?
The document file and anything already sent stay as they are. Plan around these three limits.
- The document file: to change the PDF or Word file, create a new template.
- The template ID: it stays the same for the life of the template.
- Sent documents: edits apply to later sends, not to documents already out for signature.
How do partial updates and nested updates differ?
Top-level fields accept partial updates, while roles and form fields need the complete object. Mixing these up is the most common way to lose data in an edit.
Top-level fields: send only what changes
The title, description, documentTitle, documentMessage and enableSigningOrder are top-level fields. Send only the ones you want to change, and the API leaves every other field as it is.
Roles and form fields: send the whole object
Treat the roles you send as the full list. Include every role you want to keep, not only the one you changed.
The same goes for a role’s formFields. Send the full set of fields for that role, and keep the field IDs of fields you are updating.
A safe pattern for nested edits
- Get the template properties.
- Change the roles or fields in memory.
- Send the updated structure back with a
PUTrequest.
Field names in the template properties response may differ from the names that Edit Template expects. Map each field rather than pasting the response straight into your request, especially for form fields.
What do you need before you call the Edit Template API?
You need an account, a way to sign in to the API and the ID of the template you want to change.
- A free API sandbox account or a live account.
- An API key or an OAuth 2.0 access token.
- A tool for sending web requests, such as client URL (cURL), Postman or a BoldSign software development kit (SDK).
- The
templateIdof the template you want to update.
Send your API key in the X-API-KEY header. With OAuth, send Authorization: Bearer <access_token> instead.
How do you edit a template safely, step by step?
Fetch the template, decide how much to change, then send the update and check it. These five steps keep accidental overwrites out of your templates.
- Get the template properties. Call Get Template Properties to see the full structure before a nested edit.
- Plan the smallest change. Decide whether a top-level update is enough, or whether roles and fields must change.
- Build the request body. For nested edits, start from the fetched data and keep the roles and fields you are not changing.
- Send the update. Call
PUT /v1/template/edit?templateId=<TEMPLATE_ID>with your sign-in header. - Check the result. A success returns 204 No Content, so fetch the template properties again or send a test document.
How do you update only the template title?
Send just the title field in the request body. Every other field in the template stays unchanged.
The examples below show the same request in cURL and in each BoldSign SDK.
curl -X 'PUT' \
'https://api.boldsign.com/v1/template/edit?templateId={YOUR_TEMPLATE_ID}' \
-H 'accept: */*' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Title of the template"
}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var templateClient = new TemplateClient(apiClient);
var editTemplateRequest = new EditTemplateRequest("YOUR_TEMPLATE_ID")
{
Title = "A new title for template"
};
await templateClient.EditTemplateAsync(editTemplateRequest);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
template_api = boldsign.TemplateApi(api_client)
edit_template_request = boldsign.EditTemplateRequest(title="A new title for template")
template_api.edit_template(
template_id="YOUR_TEMPLATE_ID", edit_template_request=edit_template_request
)
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$apiInstance = new TemplateApi($config);
$template_id = 'YOUR_TEMPLATE_ID';
$edit_template_request = new EditTemplateRequest();
$edit_template_request->setTitle('Updated Template Title');
$apiInstance->editTemplate($template_id, $edit_template_request);
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
TemplateApi templateApi = new TemplateApi(apiClient);
EditTemplateRequest editTemplateRequest = new EditTemplateRequest();
editTemplateRequest.setTitle("A new title for template");
String templateId = "YOUR_TEMPLATE_ID";
templateApi.editTemplate(templateId, editTemplateRequest);
import { TemplateApi } from "boldsign";
import { EditTemplateRequest } from "boldsign";
const templateApi = new TemplateApi();
templateApi.setApiKey("YOUR_API_KEY");
var editTemplateRequest = new EditTemplateRequest();
editTemplateRequest.title = "Updated Template Title";
var templateId = "YOUR_TEMPLATE_ID";
await templateApi.editTemplate(templateId, editTemplateRequest);
How do you update roles and form fields with the API?
Send the complete roles list, with each role’s form fields, and set enableSigningOrder in the same request. The flag defaults to false, so stating it every time keeps the signing order clear.
- Get the template properties.
- Change the roles or fields in memory, keeping everything you are not changing.
- Send the updated roles together with
enableSigningOrder.
The examples below replace the roles with one signer and one signature field.
curl -X 'PUT' \
'https://api.boldsign.com/v1/template/edit?templateId={YOUR_TEMPLATE_ID}' \
-H 'accept: */*' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"enableSigningOrder": true,
"roles": [
{
"name": "Customer",
"index": 1,
"signerOrder": 1,
"defaultSignerName": "Alex",
"defaultSignerEmail": "alexgayle@boldsign.dev",
"signerType": "Signer",
"locale": "EN",
"formFields": [
{
"id": "Signature1",
"fieldType": "Signature",
"pageNumber": 1,
"bounds": {
"x": 100,
"y": 100,
"width": 200,
"height": 20
},
"isRequired": true
}
]
}
]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var templateClient = new TemplateClient(apiClient);
var formFields = new List<FormField>
{
new FormField(
id: "Signature1",
type: FieldType.Signature,
pageNumber: 1,
isRequired: true,
bounds: new Rectangle(x: 150, y: 150, width: 200, height: 30)),
};
var templateRoles = new List<TemplateRole>
{
new TemplateRole()
{
Name = "Manager",
Index = 1,
DefaultSignerName = " Alex",
DefaultSignerEmail = "alexgayle@boldsign.dev",
SignerType = SignerType.Signer,
FormFields = formFields,
SignerOrder = 1,
AllowRoleEdit = true,
AllowRoleDelete = true,
},
};
var editTemplateRequest = new EditTemplateRequest("YOUR_TEMPLATE_ID")
{
EnableSigningOrder = true,
Roles = templateRoles,
};
await templateClient.EditTemplateAsync(editTemplateRequest);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
template_api = boldsign.TemplateApi(api_client)
form_fields = [
boldsign.FormField(
id="Signature1",
name="sign",
fieldType="Signature",
pageNumber=1,
font="Helvetica",
bounds=boldsign.Rectangle(x=50, y=100, width=100, height=60),
isRequired=True,
)
]
role = boldsign.TemplateRole(
index=1,
name="Manager",
defaultSignerName="Alex Gayle",
defaultSignerEmail="alexgayle@boldsign.dev",
signerType="Signer",
formFields=form_fields,
)
edit_template_request = boldsign.EditTemplateRequest(enableSigningOrder=False, roles=[role])
template_api.edit_template(
template_id="YOUR_TEMPLATE_ID", edit_template_request=edit_template_request
)
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$apiInstance = new TemplateApi($config);
$template_id = 'YOUR_TEMPLATE_ID';
// Create form field
$signatureField = new FormField();
$signatureField->setFieldType('Signature');
$signatureField->setPageNumber(1);
$bounds = new Rectangle([100, 100, 100, 50]);
$signatureField->setBounds($bounds);
// Create role and assign form field
$role = new TemplateRole();
$role->setName('Signer');
$role->setDefaultSignerEmail('alexgayle@boldsign.dev');
$role->setDefaultSignerName('Alex Gayle');
$role->setSignerOrder(1);
$role->setIndex(1);
$role->setFormFields([$signatureField]);
// Create edit template request
$edit_template_request = new EditTemplateRequest();
$edit_template_request->setEnableSigningOrder(true);
$edit_template_request->setRoles([$role]);
$apiInstance->editTemplate($template_id, $edit_template_request);
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
TemplateApi templateApi = new TemplateApi(apiClient);
Rectangle bounds = new Rectangle();
bounds.setX(50f);
bounds.setY(100f);
bounds.setWidth(100f);
bounds.setHeight(60f);
FormField formField = new FormField();
formField.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
formField.setPageNumber(1);
formField.setBounds(bounds);
TemplateRole role = new TemplateRole();
role.setIndex(1);
role.setName("Manager");
role.setDefaultSignerName("Alex");
role.setDefaultSignerEmail("alexgayle@boldsign.dev");
role.setSignerOrder(1);
role.setSignerType(TemplateRole.SignerTypeEnum.SIGNER);
role.setFormFields(Arrays.asList(formField));
EditTemplateRequest editTemplateRequest = new EditTemplateRequest();
editTemplateRequest.setEnableSigningOrder(false);
editTemplateRequest.setRoles(Arrays.asList(role));
String templateId = "YOUR_TEMPLATE_ID";
templateApi.editTemplate(templateId, editTemplateRequest);
import { TemplateApi, EditTemplateRequest, TemplateRole, Rectangle, FormField } from "boldsign";
const templateApi = new TemplateApi();
templateApi.setApiKey("YOUR_API_KEY");
const bounds = new Rectangle();
bounds.x = 100;
bounds.y = 50;
bounds.width = 100;
bounds.height = 100;
var formField = new FormField();
formField.fieldType = FormField.FieldTypeEnum.TextBox;
formField.pageNumber = 1;
formField.bounds = bounds;
var editTemplateRequest = new EditTemplateRequest();
editTemplateRequest.enableSigningOrder = true;
var role = new TemplateRole();
role.index = 1;
role.defaultSignerEmail = "alexgayle@boldsign.dev";
role.defaultSignerName = "Alex";
role.name = "Signer";
role.signerOrder = 1;
role.formFields = [formField];
editTemplateRequest.roles = [role];
var templateId = "YOUR_TEMPLATE_ID";
await templateApi.editTemplate(templateId, editTemplateRequest);
Where is the Edit Template API useful?
Any team whose documents change often can keep its templates current from code. Here are four common cases.
HR offer letters
A job title changes from Developer to Engineer just before an offer goes out. Your app updates the role name and message without rebuilding the template.
Sales contracts
High-value deals need an extra Legal Reviewer role. Your code adds the role and turns on the signing order, so the reviewer signs at the right point.
Operations and policy fields
A new checkbox or date field becomes mandatory across agreements. One script adds it to every affected template.
Campaign agreements
Campaign names and project titles change often. Updating the template title and message keeps each document accurate.
Which BoldSign plan do you need for the Edit Template API?
Every BoldSign plan, including the free one, includes sandbox API access for testing. Live API calls need the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly.
The Enterprise API plan includes unlimited templates. Prices are in USD, as of November 2026, and the pricing page lists every plan.
How do you start editing templates with the BoldSign API?
Start in the sandbox, then follow our developer guide as you build. Here are three next steps.
- Create a free API sandbox account and get a sandbox API key.
- Follow the developer guide on editing templates programmatically.
- Request a demo, or ask our team a question through the support portal.
Frequently asked questions
Does the Edit Template API support partial updates?
Yes, for top-level fields. Send only the title, description or message you want to change, and every other top-level field stays as it is.
Can I partially update roles or form fields?
No. Roles and form fields are nested objects, so you send the complete object. Fetch the template first, change it in memory, then send the whole list back.
Can I replace the PDF in a template with the Edit Template API?
No. The endpoint changes template settings only, not the files linked to it. Create a new template when the document itself changes.
Why should I get template properties before an edit?
Template properties return the full role and field structure. Starting from that copy keeps the roles and fields you did not mean to change.
Which fields can I change with the Edit Template API?
You can change the title, description, document title and document message. You can also change signer roles, form fields and the signing order setting.
Does editing a template change documents already sent?
No. An edit applies to the template, so later sends use the new version. Documents already out for signature keep the version they were sent with.
What does the Edit Template API return when it succeeds?
It returns 204 No Content. The response has no body, so fetch the template properties again to confirm the change.
Can I test the Edit Template API for free?
Yes. A free API sandbox account lets you create templates and call the Edit Template API with a sandbox key before you go live.