Templates and versions
The text people sign, and why it is never changed under them.
A template has a code (rental-agreement) and
numbered versions. A version is a draft until it is published,
and a published version is frozen: the database refuses to change or delete it,
because somebody may have signed it. Changing the words means a new version.
Each document records the exact version it was made from, and the certificate
says which, so "what did they sign?" always has one answer.
The lifecycle
| Step | Call | What happens |
|---|---|---|
| Create | POST /v1/templates | Version 1, as a draft, with its text, placeholders, consent wording and questions. |
| Change the draft | PATCH /v1/templates/{id} | name, body, body_format, variables, fields (the whole list). Only while it is a draft. |
| Publish | POST /v1/templates/{id}/publish | New documents from this code use this version, and its text is frozen. Refused, by name, for a placeholder the template does not declare. |
| Revise | POST /v1/templates/{id}/revise | A new draft, one version higher, copied from the newest with whatever you change. Publish it to put it into use. |
| Throw a draft away | DELETE /v1/templates/{id} | Only a draft nothing was made from. The only version of a code going frees the code. |
| Read one | GET /v1/templates/{id} | The version whole, with versions: every version of its code, newest first. |
| List | GET /v1/templates?code= | Every version of every template, or one code's; no text. |
// A new clause for next season, without touching what people signed this one.
const current = await signsealer.template(templateId);
const next = await signsealer.reviseTemplate(current.template_id, {
body: current.body + "\n\nHelmets are required on every trail.",
});
await signsealer.publishTemplate(next.template_id);Revise only from the newest version. Revising an older one would quietly
throw away every change made since, so it answers 409 conflict,
and the hint names the newest version's id. A draft is not revised; it is
changed with PATCH.
What happens to what was already sent
- Documents already sent keep their version. The text is stored on the document when it is prepared, and a new version changes nothing about a document on its way to a signer.
- New documents use the newest published version. A draft is never sent.
- A tablet that ran the form with no network names the version it showed (
expected_template_version) when it catches up. If a newer one was published meanwhile, the start answers409 template_changedand nothing is sealed against words the person did not read.
Settings that outlive a version
Some settings belong to the code, not one version, and carry over to every
version after: PATCH /v1/templates/{id}/settings with any of
| Setting | Means |
|---|---|
| valid_months | How long a signature stays good, in months; null for as long as the document is kept. GET /v1/standing answers against it. |
| remind_days | Days before the end each signer is emailed a link to sign again. Needs valid_months. |
| resign | true: everybody who signed an older version must sign the newest published one; their standing reads resign. false lifts it. |
| one_time | Made to send once rather than reused. |
| show_address | The business's address printed under it. |
A template that is a PDF
Uploading the file is a dashboard step, because every page needs a picture a signer can read and drawing them needs a browser (Signing a PDF). Everything on this page works on it afterwards, except changing its text: a PDF's text is the file. Revise it to rename it or change its questions; to change what it says, start a new template from the new file.
Ready to build? An API key takes a minute in the portal, and the free plan covers the first 25 agreements a month.
Get an API key