Skip to main content
A package template captures everything that defines a package - its documents, stakeholders, actors, placed elements, and settings - and stores it under a reusable code. Once you have a template, you can create a new package from it by passing a single TemplateCode, instead of sending the documents, fields, and process again on every call. Templates are worth setting up when you send the same kind of package repeatedly: a standard NDA, an employment contract, an onboarding pack. If the documents and field layout are stable and only the signer changes from one send to the next, a template removes almost all of the per-call construction work and keeps every package consistent.

​
Prerequisites

  • A valid access token or Basic Auth credentials - see Platform Access
  • Your tenant’s base URL set as BASE_URL
  • A package you have already built and want to reuse (for creating a template), or an existing TemplateCode (for creating packages from one)
All examples use Bearer authentication. Replace the token and variable values with your own.

​
Create a template from a package

Build a package the way you normally would - add its documents, stakeholders, actors, and fields - but leave it in Draft status. Then save it as a template with POST /packages/{packageId}/template. The only field in the body is TemplateName, which must be unique within the package’s document group.
The response returns the template’s code. Save it - this is what you pass when creating packages from the template.
The source package must be in Draft status. Saving a package that has already been activated as a template returns 409 Conflict. Build and configure the package, then save it as a template before you activate any signing flow.
Everything that defines the package is stored in the template, so you can generate templates on the fly as part of an automated flow - for example, build a canonical package once during setup and save it as a template your integration reuses from then on.

​
List available templates

Retrieve the templates available in your tenant, with their codes, using GET /templates:
Each item gives you the template Name and the TemplateCode you pass when creating a package:
The endpoint accepts optional query parameters to page and filter the list: pageNumber and pageSize for pagination, documentGroupCode to return only templates in a given document group, sort (asc or desc), and createdAfter / createdBefore to filter by creation date.

​
Create a package from a template

To create a package from a template, call POST /packages with a TemplateCode. The package is pre-populated with everything defined in the template.
When you create a package from a template, the parameters behave as follows: In other words, Initiator is the only thing you must supply beyond the TemplateCode. You can override Name, ExternalReference, and ProofCorrelationId, but everything else - documents, stakeholders, fields, callbacks, theme, and other package settings - comes from the template and cannot be overridden in this call. The response is the created package, in the same shape as Get package. As with any package, you can continue to add or change information with additional API calls after it is created.

​
Templates and super calls

A template cannot be combined with a super call.
The super call inlines documents, stakeholders, actors, and elements directly in the POST /packages body; creating from a template instead inherits all of that from the TemplateCode. Pass one or the other, not both. See Instant package for the super-call approach.

​
Placing template fields by marker

If the template defines unplaced elements that are matched to documents by text markers, the SingleMarkerMatchPerElement parameter controls how those element definitions are consumed as documents are confirmed:
  • false (the default, or null): an element definition can be matched by markers in multiple documents, and cleanup of any remaining unplaced elements is deferred.
  • true: each element definition can be matched by only one marker during document confirmation, and the definition is removed once it has been placed.
On package submit, the remaining UnplacedElements will be disregarded and removed. For more on markers and the other ways to position fields, see Field positioning.

​
When to use a template

Templates pay off when the structure of a package is stable and repeated:
  • Recurring documents - the same contract, form, or agreement sent many times.
  • Stable field layouts - signing fields, checkboxes, and text fields always in the same place.
  • Consistency - every package built the same way, with the same settings, reducing the chance of a per-call mistake.
If each package is one-off, or the documents and field positions change every time, building the package directly - step by step in Send a document for signing, or all at once with an Instant package - is simpler than maintaining a template.

​
Next steps