4.8-star rating on g2.com
PDF Updated? You Don't have to Rebuild Your Template.
If you've ever managed signing templates in production, you've hit this problem. A lawyer updates a clause. Legal sends a revised PDF. Your 14-field NDA template now needs to be rebuilt from scratch: re-upload the document, replace every field, reassign every signer.
For one template that's an hour of work. For ten templates across fifty customer workspaces, it becomes an actual problem.
Template Document Replacement solves it. Swap the underlying PDF on any template and every field, signer assignment, and setting stays exactly where it was.
The Problem It Solves
Templates are where the real work lives
They often find API access makes sense because they're already paying for the platform. Adding developer access to an existing Enterprise agreement is typically negotiable, and the legal/procurement work is already done.
Same Structure. Same Fields. No Way to Keep Them… Until Now.
The triggers are common: a typo fix, a clause revision, a rebranded header, a legal team update, a regulatory change. The document structure stays the same, the pages stay the same, the fields should stay the same. Previously there was no way to preserve that work. Now there is.
How It Works
Swap the PDF. Keep Everything Else.
Upload a new PDF. Firma.dev validates that the page count matches the original and that page dimensions are within 1pt tolerance. If both checks pass, the document is swapped instantly. Every field position, every signer assignment, every template setting remains untouched.
Why the Validation Rules Exist
The validation rules aren't arbitrary constraints, they're safeguards. If the page count changes or dimensions shift significantly, field positions would drift off-page or land in the wrong location. The 1pt tolerance covers minor rendering differences between PDF exports from the same source file, while blocking replacements that would misalign your fields.
Three surfaces support document replacement
Main template editor
A Replace Document button in the template header. Upload directly from the UI.
Embedded editor
Server-side validation via the edge function with JWT authentication. Works in any embedded integration.
REST API
POST /templates/{id}/replace-document
with a base64-encoded PDF.
Using the API
The endpoint is straightforward. Encode your replacement PDF as base64 and POST it to the template (API reference: https://docs.firma.dev/api-reference/v01.09.00/templates/replace-template-document)
The response is the updated template object. If validation fails, you get a 400 with a clear error indicating whether the issue is page count mismatch, dimension mismatch, or an invalid PDF.
Validation Rules
DOC and DOCX uploads via the UI are automatically converted to PDF before validation. The API accepts PDF directly.
Check
Requirement
Page count
Must match the original exactly
Page dimensions
Must match within 1pt tolerance per page
File format
Base64-encoded PDF via API; PDF, DOC, or DOCX (up to 60MB) via UI
Who This Is For
Legal and compliance teams iterating on contract language
When your standard agreements get updated, one API call now replaces the document across any template without disrupting the field configuration.
SaaS platforms managing templates across customer workspaces
Rebranding or updating a document that's deployed across dozens of workspaces no longer means manual rebuilds in each one. Update the source template and you're done.
Compliance-driven document updates
Regulated industries sometimes require document updates on a schedule. Replacing the PDF without losing field placements means the update can be automated, tested, and deployed without human rework.
Template Document Replacement is available in API v1.9.0 with no breaking changes from v1.8.0.
