---
title: "Edit Template API: Programmatic Template Updates Made Simple"
description: "Learn how to edit templates programmatically using the Edit Template API. Update titles, roles, and form fields safely with partial and nested updates."
url: "https://boldsign.com/blogs/edit-template-api/"
---

1. [Blog](https://boldsign.com/blogs.md)
2. [API](https://boldsign.com/category/api.md)

# Programmatic Template Editing Using the BoldSign Edit Template API

[Ranjitha Vazhivittan](https://boldsign.com/author/ranjitha-vazhivittan/) March 24, 2026 Updated March 27, 2026 8 min read

> **TL;DR:** BoldSign Edit Template API allows you to update existing templates including titles, messages, roles, and form fields, directly from code without recreating them. Use partial updates for top-level changes, and fetch Template Properties before editing nested objects to prevent accidental overwrites and template drift in automated workflows.

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](https://account.boldsign.com/signup?planId=1076\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign) (sandbox or production).
- An [API key](https://developers.boldsign.com/authentication/api-key) (or [OAuth2 access token](https://developers.boldsign.com/authentication/oauth-2-0)) 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](https://developers.boldsign.com/template/template-details)
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](https://account.boldsign.com/signup?planId=1076) 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 -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
    )
```

```
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 (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 -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
{
    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);
```

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

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

## 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](https://developers.boldsign.com/how-to-guides/edit-a-template-using-API) 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](https://account.boldsign.com/signup?planId=1076\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign), leave a comment, book a [demo](https://boldsign.com/request-demo.md), or connect with our support team through the [support portal](https://support.boldsign.com/support/tickets/create).

Topics [API integration](https://boldsign.com/blogs/tag/api-integration.md)[Templates](https://boldsign.com/blogs/tag/templates.md)[Form fields](https://boldsign.com/blogs/tag/form-fields.md)

## Sign documents 3x faster

Send, sign and manage documents securely and efficiently.

[Try it today](https://account.boldsign.com/signup?planId=1018\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign)

## Frequently asked questions

### Does the Edit Template API support partial updates?

Yes, send only the fields you want to update and BoldSign updates only those fields.

### Can I partially update roles or form fields?

Not safely. Partial updates are limited to top-level properties; nested objects require the complete object to be sent.

### Can I change the template’s PDF/DOCX using this API?

No. The API does not permit altering the files linked to the template.

### Why should I call Template Properties before editing nested objects?

Because nested updates require complete objects; Template Properties gives you the full structure so you can edit safely.

### What are the key fields I can update via Edit Template API?

Title, Description, `DocumentTitle`, `DocumentMessage`, Roles, and `FormFields`.

## Ranjitha Vazhivittan

Ranjitha is a skilled software developer with 3 years of experience at BoldSign. Alongside her technical expertise, she has a passion for writing and enjoys sharing thoughtful insights on technology and development. Beyond work, she stays curious by exploring emerging tools and trends, constantly seeking opportunities to learn and grow.

[More posts by Ranjitha Vazhivittan](https://boldsign.com/author/ranjitha-vazhivittan/)

## Related posts

- [API](https://boldsign.com/category/api.md) September 29, 2026 10 min read

  ## [How to Migrate from Docusign Without Losing Templates or Workflow Continuity](https://boldsign.com/blogs/migrate-from-docusign.md)

  Learn how to migrate from Docusign while protecting templates, signed records, and active workflows. Explore key risks, a practical checklist, and next steps.

- [API](https://boldsign.com/category/api.md) September 22, 2026 9 min read

  ## [What Are the Common Challenges When Using Signature APIs in Software Development](https://boldsign.com/blogs/common-signature-api-challenges.md)

  Explore the common challenges developers face with a Signature API, from authentication issues to PDF rendering, webhooks, templates, and rate limits.

- [API](https://boldsign.com/category/api.md) September 18, 2026 6 min read

  ## [How to Safely Edit eSignature API Templates in Production](https://boldsign.com/blogs/edit-esignature-api-template.md)

  Learn what can break when you edit an eSignature API template, including roles, fields, and indexes, and how to update templates safely in production today.

Get started

## Sign up for your free trial today!

[Start free trial](https://account.boldsign.com/signup?planId=1018)

- 30-day free trial
- No credit card required

*Picture: A completed employment contract: signed by John Doe on 11/03/2026, all parties have signed*
