How to Safely Edit eSignature API Templates in Production

TL;DR: Editing a template doesn't retroactively change documents already sent from it, so a signer stuck with the old wording isn't a bug. The real risks are structural: nested edits to roles or form fields replace the entire list rather than patching it, and role index changes downstream of a removed or reordered role can silently point to the wrong role.

Knowing which of your changes are safe partial updates and which require the full structure prevents most template-editing incidents.

You add a mandatory field to a template, confident it’ll show up everywhere the template is used. A signer who received their document an hour earlier reports the old version, without the field. Nothing is broken. The document they got was already a separate copy by the time you made the edit.

That one is intuitive once you know it. The harder failures happen inside the template itself. Removing a role, or forgetting to include an existing field when you edit another one, can quietly change or delete parts of a template you never touched.

Templates in eSignature APIs work like reusable configuration, not like a single document you keep revising in place. That’s useful, but it means an edit can ripple in ways a simple find-and-replace never would, especially once roles and field IDs are involved.

Here’s what actually happens in BoldSign’s templates specifically, and the pattern that avoids all three.

Key takeaways

• Editing a template only changes future documents sent from it; anything already sent for signature keeps the version it was sent with.
• Nested parts of a template, like a role’s list of form fields, are replaced wholesale on edit, not patched, so leaving out an existing field’s ID can delete it.
• Roles are tracked by a numeric index as well as by name. BoldSign automatically renumbers remaining roles when one is excluded at send time; when you remove or reorder a role through a template edit, you supply each role’s index yourself, so it’s worth verifying afterward.
• Any code that hardcodes a role’s index or a field’s ID needs to be revisited after a template edit, not assumed to still be correct.
• Fetching a template’s current structure before editing it, then sending the full structure back, is the safest way to change a template without losing something else.

Editing a template doesn’t reach documents already sent

This isn’t a BoldSign quirk. Across eSignature platforms, once a document is sent for signature, its content is generally treated as fixed, specifically so the signed record can’t be quietly altered after the fact. Adobe Acrobat Sign, for example, only allows editing an in-flight document as an opt-in enterprise feature, disabled by default for everyone else. If something needs to change in a document that’s already out for signature, the usual fix is voiding it and sending a new one, not patching the original.

BoldSign follows the same pattern for templates specifically. Editing a template only changes what future documents sent from that template look like. A document already sent keeps the fields, wording, and roles it went out with, since template edits are scoped to the template itself, not to documents already in progress.

That boundary makes sense once you think about why it exists: if a template edit could retroactively rewrite a document a signer already has open, the signed result would no longer reliably reflect what was actually presented and agreed to. Voiding and resending stays the correct fix for a document that’s already out.

The practical implication: if a fix needs to reach documents already sent, editing the template isn’t the tool. You’d resend from the updated template, or revoke the specific document and send a corrected one, rather than trying to alter what’s already out.

A partial-looking edit can wholesale-replace a role’s fields

The Edit Template API exists so you can update an existing template’s roles, fields, or title directly, without deleting and rebuilding it from scratch. That convenience comes wrapped in two different update behaviors, and mixing them up is where most accidental damage happens.

Top-level properties like title, description, and document message support true partial updates: send only what you want to change, and everything else stays put.

Roles and the form fields inside a role don’t work that way. Updating a role’s form fields replaces that role’s entire field list, rather than adding to it. If your update request includes only the one new field you meant to add, every other field on that role disappears from the template.

The same applies one level up: updating the roles array replaces the whole list of roles, not just the one you’re touching. Leave an unrelated role out of the request, and it’s gone from the template, along with every field assigned to it.

A complete edit request looks like this. When updating a template, all roles and fields must be included explicitly, and for any existing form field, you must provide the same field ID specified in the template:

curl -X PUT "https://api.boldsign.com/v1/template/edit?templateId=Your_template_id" \ 
  -H "Content-Type: application/json" \ 
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{ 
    "enableSigningOrder": true, 
    "roles": [ 
      { 
        "name": "Manager", 
        "index": 1, 
        "defaultSignerName": "Alex", 
        "defaultSignerEmail": "[email protected]", 
        "signerOrder": 1, 
        "signerType": "Signer", 
        "formFields": [ 
          { 
            "id": "Signature1", 
            "fieldType": "Signature", 
            "isRequired": true, 
            "allowEditFormField": true, 
            "allowDeleteFormField": true, 
            "bounds": { 
              "x": 625, 
              "y": 293, 
              "width": 124, 
              "height": 32 
            }, 
            "pageNumber": 1 
          } 
        ] 
      } 
    ] 
  }'

Field IDs matter here because BoldSign expects existing field IDs to be preserved when you update form fields. If an edit drops a field’s ID, anything referencing that field by ID afterward won’t find it anymore.

Role index changes can break downstream references

Roles in a BoldSign template aren’t only identified by name. Each one also has a numeric index that reflects its position. That index is what several send-time operations actually use, including assigning signer details to a role and excluding a role you don’t need for a specific send.

BoldSign’s own documentation gives a concrete example for send-time role removal: a template with three roles at index 1, 2, and 3. Remove the role at index 2 using roleRemovalIndices, and the role that was at index 3 becomes index 2. The role that was third is now addressed as if it were second.

Any code that hardcoded “role index 3 is always the approver” can end up pointing at the wrong role instead, and the assignment or role-based logic built on that index behaves unexpectedly. For a contract that was supposed to route to a legal reviewer, that’s a mistake more likely to surface during an audit than during testing.

That renumbering is documented specifically for roles excluded at send time. Editing a template’s roles directly works differently: you supply the full role list yourself, with each role’s index set explicitly in the request.

When editing a template, update the full roles list carefully and verify the remaining role indices afterward before downstream code relies on them.

The safe pattern for editing a template without losing something else

BoldSign documents a straightforward pattern for any edit that touches roles or form fields: fetch the template’s current properties first, make your change in that structure, then send the whole thing back. That way you’re submitting a complete, accurate picture instead of guessing at what else needs to stay.

A short checklist for that pattern:

• Fetch the template’s current properties before editing any role or form field.
• Make your change inside that fetched structure, keeping every other role and field intact.
• Re-map field names where needed rather than pasting the properties response straight into the edit request, since the two don’t always match exactly.
• Include enableSigningOrder explicitly whenever the request includes roles, so signer sequencing isn’t left ambiguous.
• After the edit, re-check any code that hardcodes a role index or field ID against the new structure, not just whatever you changed on purpose.

Templates are reusable configuration, not permanent identifiers

None of this is about BoldSign being fragile. It’s what you’d expect from a system where roles and fields are addressed by ID and position so other API calls can reference them precisely. That same precision is what makes an incomplete edit dangerous instead of harmless.

If you’re building automation that edits templates regularly, BoldSign’s developer documentation covers the full request and response shape for roles and form fields. Create a free API sandbox to test an edit against a template before you run it against production.

FAQs