Template Versions

DocSpring supports template versioning to help you manage changes to your templates safely. Every template has a draft version for making changes, and you can publish these changes as numbered versions (e.g., 1.2.3) that won’t affect your existing API integrations.

How Versioning Works

Draft vs Published Versions

• Draft Version: Every template starts with a draft version that you can freely edit
• Published Versions: When ready, publish your draft as a numbered version (e.g., 1.2.3)
  • Published versions are read-only and cannot be modified
  • Changes to your draft’s PDF, fields and the other things a version keeps don’t affect published versions. The template’s other settings apply to every version as soon as you change them on the draft
  • API calls default to using the latest published version

What a Version Keeps

A published version keeps everything that decides what its PDFs and forms contain:

• The template’s PDF, or for an HTML template its HTML, SCSS, header, footer and page settings
• The fields, with their order, conditions, formulas and default values, and the template’s Field defaults
• The template’s name and description
• Allow Additional Properties, Merge Audit Trail With Signature Request PDFs, Add Submission ID Footers to Signature Requests and Parse Dates Using the Template’s Date Format, and whether its PDFs are editable

The other settings belong to the template, not to one version. When you change one on the draft, every version uses the new value straight away: Locked, Online Form, Online Form Privacy, Show Continue Once Required Fields Are Filled In, Redirect URL, Expire Submissions, Submission Privacy, Encrypt PDFs with a Password, a Word template’s Each Submission Makes (Word documents, OpenDocument files or PDFs), Webhook URL, Slack Webhook URL and Embed Domains.

Signature Requests Sent From the Draft

A signature request sent from the draft keeps the template as it was when you sent it, so you can keep editing the draft while the request waits for its signers. The signers see that template, and their signed PDF is made from it. The submission still has the template’s ID and is listed with its submissions, and its page opens the template as sent, read-only. Like a published version, it takes the template’s other settings from the draft.

If the draft’s PDF is still processing, or AI field setup is still adding its fields, when you send the request, the request keeps the template as it is when that finishes. If it hasn’t finished after 20 minutes, or the signers finish first, the signed PDF is made from the draft as it is then.

Version Numbers

DocSpring uses semantic versioning (major.minor.patch). When an API endpoint supports a template version parameter, you can pass the following values:

• Full version: 1.2.3
• Partial version: 1.2 (uses the latest 1.2.x version)
• Major version only: 1 (uses the latest 1.x.x version)
• latest: Uses the latest published version
• draft: Uses the draft version

Managing Versions

Publishing a Version

1. Make your changes in the draft version
2. Click the Versions button in the template editor header to open the Versions modal
3. Click “Publish Version” and choose which number to increment:
   • Major (1.0.0): For breaking changes
   • Minor (0.1.0): For new features
   • Patch (0.0.1): For bug fixes
4. Add an optional description to track what changed

Working with Versions

• View Version History: Open the Versions modal to see all published versions
• Show Version: Open a published version in the template editor (read-only)
• Show Changes: Compare a version with the previous version, or compare your draft with the latest published version
• Restore Previous Version: Click “Restore to Draft” to roll back to an older version
• Restore to Copy: Create a new template from any published version (not available in the embedded template editor)
• Delete Version: Permanently delete a published version
• Track Version in Template: Add the @@version field to show “draft” or the current version string
• View Version in Submissions: The exact template version is stored with each submission

Using Versions in Your Integration

Generate PDF API

When generating PDFs, use the version query parameter to specify which template version to use:

POST /api/v2/templates/<TEMPLATE_ID>/submissions?version=1.2.3
{
  "data": { ... }
}

Version parameter options:

• Omit parameter: Uses latest published version (or draft if none published)
• version=1.2.3: Uses a specific version
• version=1.2: Uses the latest 1.2.x version
• version=1: Uses the latest 1.x.x version
• version=latest: Uses latest published version (or draft, if no versions have been published)
• version=draft: Uses the draft version

In a batch, the same values go in template_version, for the whole batch or for each submission.

Web Forms

When viewing a template’s web form:

• If you’re signed in and own the template:

  • The draft version is shown by default
  • Add ?version=latest to view the latest published version
  • Add ?version=1.2.3 to view a specific version

• If you’re not signed in or don’t own the template:

  • The latest published version is shown by default
  • Falls back to draft if no published versions exist
  • Add ?version=1.2.3 to view a specific version

The “Form” and “Visual” buttons in the template editor will include the version that you are currently viewing (?version=draft by default.) Make sure to check the version parameter before you share the form URL.