Programmatic Template Editing Using the BoldSign Edit Template API

 

Templates often serve as living configuration in production eSignature workflows. As businesses scale, these templates change frequently, such as adding new approval steps, updated policies, branding refreshes, or additional required fields. When such updates are handled manually through dashboards, templates can drift across environments and introduce inconsistencies that break automated processes.

The BoldSign Edit Template API solves this by allowing developers to update existing or draft templates programmatically. You can modify metadata, signer roles, and form fields directly from your backend or CI/CD pipelines, keeping templates synchronized with application logic while reducing operational overhead and human error.

Why edit templates programmatically

Templates often act as “living configuration” in production workflows. Over time, teams update templates due to:

• New approval steps (HR, finance)
• Policy changes (legal, compliance)
• Branding refreshes (marketing)
• New mandatory fields (operations)

If these updates happen manually in the dashboard, templates can drift across environments (sandbox vs production) and become inconsistent. With the Edit Template API, you can apply controlled updates from your backend or CI/CD pipelines, keeping templates synchronized with your application logic while reducing operational overhead and human error.

What can you update using the Edit Template API

You can update common template configuration elements, including:

• Template title: Rename the template to reflect its updated purpose.
• Template description: Add or revise the summary of what the template is for.
• Document title: Change the title that signers see on the document.
• Document message: Update the message that accompanies the request to sign.
• Signer roles: Add, remove, reorder, or rename roles (e.g., “Manager”, “Client”).
• Form fields: Edit or add input elements (signature, text, date, checkbox) bound to pages and roles.
• Signing order settings: Toggle and adjust signer order behavior when relevant.

What can’t you change using the Edit Template API

The following changes are not supported:

• The document file itself (PDF or DOCX): If the underlying document needs to change, you must create a new template.
• Template ID
• Sent documents: Edits only apply to templates, not documents already sent for signing.

Partial updates vs nested updates

1) Top-level fields support partial updates 

For simple changes like title, description, documentTitle, documentMessage, or enableSigningOrder, you can send only the fields you want to change.

Result: Unspecified top-level fields remain unchanged.

2) Nested objects must be complete (roles and form fields)

When you update nested objects (like roles or a role’s formFields), you should assume you are replacing the existing array.

• Updating roles replaces the entire roles list
  Include every role you want to keep, not only the one you changed.
• Updating formFields for a role replaces that role’s field list
  Include the full set you want to keep, preserving field IDs when updating existing fields.

Safe pattern

1. Fetch Template Properties
2. Edit the JSON in memory
3. PUT the updated structure back

Field naming note: 
Template Properties responses may not match the exact request field names used by Edit Template in every SDK/version. Don’t copy/paste the Template Properties JSON directly into the Edit Template payload, map fields as needed (especially for form fields).

What you’ll need before calling the Edit Template API

Make sure you have the following in place:

• A BoldSign account (sandbox or production).
• An API key (or OAuth2 access token) to call BoldSign APIs over HTTPS.
• A REST client such as cURL, Postman, or your preferred HTTP library.
• The TemplateId of the template you want to update.

Authentication headers

Use one of the following:

• API Key: X-API-KEY: <your key>
• OAuth2: Authorization: Bearer <access_token>

How do you safely edit a template step by step

1. Retrieve Template Properties
   Get the full structure of the template, especially important before nested edits. You can refer to the following link to access the template properties : Get Template Properties
2. Plan minimal changes
   Decide whether a top-level partial update is enough (e.g., title only) or whether you must update roles/fields.
3. Prepare the payload 
   For nested edits, start from fetched JSON, modify only what’s needed, and keep unchanged roles/fields intact. 
4. Send the update
   PUT /v1/template/edit?templateId=<TEMPLATE_ID> with your chosen auth header.
5. Verify
   Fetch Template Properties again or run a sandbox send to confirm behavior.

How do you update only the template title (top-level partial update)

When you only need to change the template title, send just the title field. Everything else remains unchanged.

Below is an example code snippet

cURL

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" 
}'     

C#

        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); 

Python

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)     

PHP

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);      

Java

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);     

Node js

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 (nested update pattern)

Key rule: Include enableSigningOrder whenever roles are present.
When your request includes roles, always include enableSigningOrder explicitly (true or false). This ensures signer sequencing is unambiguous.

Recommended approach 

1. Fetch Template Properties
2. Modify roles/fields in memory (keep unchanged roles/fields)
3. Send the updated roles along with enableSigningOrder

Below is an example code snippet 

cURL

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  
        } 
      ] 
    } 
  ] 
}'     

C#

        var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY"); 
        var templateClient = new TemplateClient(apiClient); 
        var formFields = new List 
        { 
            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 
        { 
            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); 

Python

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) 

PHP

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);      

Java

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);     

Node js

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);     

Real-world use cases of the Edit Template API

1) HR offer letters

Scenario: A candidate’s role changes from “Developer” to “Engineer” right before sending the offer.
Solution: Update the template roles/messages instantly without recreating or editing in the dashboard.

2) Sales contracts

Scenario: High-value deals require an additional “Legal Reviewer” role.
Solution: Add/reorder roles and enforce signing order programmatically for compliance.

3) Operations & compliance

Scenario: A new checkbox/date field becomes mandatory across agreements.
Solution: Update form fields programmatically across templates to align with policy.

4) Marketing agreements

Scenario: Campaign names or project titles change frequently.
Solution: Update template metadata dynamically so documents remain current and professional.

Summary: Managing templates with BoldSign APIs

Templates are foundational when your eSignature workflows must evolve with business needs. With the Edit Template API, you can:

• Update titles, descriptions, and messages via partial updates
• Adjust signer roles and form fields via complete nested updates
• Reduce drift caused by manual edits
• Keep templates consistent across environments and teams

Conclusion

Editing templates programmatically is a smart way to keep eSignature workflows flexible and stable at scale. Use partial updates for top-level changes and the fetch–modify–update pattern for roles and fields to prevent accidental overwrites. With a few API calls, your team can keep templates current, reduce operational burden, and maintain consistency across environments.

If you’d like to learn more about BoldSign, leave a comment, book a demo, or connect with our support team through the support portal.

Related blogs

• BoldSign Collaborative Fields for Accurate Multi‑Signer API Workflows
• What Are the Common Challenges When Using Signature APIs in Software Development
• Select Visual Studio Enterprise Subscribers: Get 12 Months of BoldSign Growth Plan + 50 API Credits

Note: This blog was originally published at boldsign.com