> ## Documentation Index
> Fetch the complete documentation index at: https://docs.annature.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# The Template object

A template is a reusable resource in Annature that allows you to generate [envelopes](/api-reference/envelopes/create-envelope) without redefining [documents](/api-reference/documents/document-object), [recipients](/api-reference/recipients/recipient-object), and [fields](/api-reference/fields/field-object) each time.

Templates streamline envelope creation for common workflows — such as NDAs, onboarding documents, or client agreements — by allowing you to predefine structure, roles, and field placement once, then reuse those settings as needed.

Like envelopes, templates must include at least one document and one role. Roles act as placeholder recipients and are resolved at the time the template is used.

## Template documents

Each template contains one or more base documents. When creating an envelope from a template, you can choose to:

* Use the template’s original documents exactly as they are; or
* Replace one or more documents with updated versions — such as prefilled contracts or customised forms.

Replacement documents must meet two criteria:

1. **They must have the same number of pages** as the originals. This ensures that all fields can be correctly reapplied to the new document structure.
2. **Their dimensions must be nearly identical** to the original pages. This is required to maintain accurate field positioning — especially for coordinate-placed or anchored fields.

If these requirements are not met, field transfer will be incomplete or fail silently. For example, fields assigned to page 6 of the original document cannot be carried over if the replacement document only has 5 pages.

This workflow is designed for use cases where the layout stays the same, but content is prefilled externally — such as merging client data into a standard contract before sending.

There is no restriction on adding new documents beyond those defined in the template.

## Template roles

Roles define placeholder recipients for the template. Each role specifies a set of [fields](/api-reference/fields/field-object) and default recipient properties (such as signing order or message content).

When using the template, you’ll provide recipient details (name, email, etc.) and map them to the appropriate role by referencing the role’s `id`. This allows Annature to copy the role’s properties and apply its fields to the matching recipient.

## Attributes

<ParamField path="id" type="string">
  The unique identifier for the template.
</ParamField>

<ParamField path="name" type="string(250)">
  The name of the template as shown in the Annature dashboard.
</ParamField>

<ParamField path="shared" type="boolean">
  Indicates whether the template is shared with other accounts in the same group as the creator.
</ParamField>

<ParamField path="envelope_name" type="string(250)">
  Default name applied to envelopes created from this template.
</ParamField>

<ParamField path="envelope_message" type="string(5000)">
  Default message body applied to envelopes created from this template.
</ParamField>

<ParamField path="envelope_shared" type="boolean">
  Default value for the `shared` property when an envelope is created from this template.
</ParamField>

<ParamField path="created" type="string">
  The ISO 8601 timestamp indicating when the template was created.
</ParamField>

<ParamField path="account_id" type="string">
  The unique identifier of the account that created the template.
</ParamField>

<ParamField path="group_id" type="string">
  The unique identifier of the [group]() the template is assigned to.

  If `shared` is `true`, other accounts in this group will have access to use the template.
</ParamField>

<ParamField path="documents" type="array, document object">
  An array of document objects defined within the template.
</ParamField>

<ParamField path="roles" type="array">
  An array of role objects representing placeholder recipients and their associated fields.
</ParamField>

<RequestExample>
  ```bash Endpoints theme={null}
  GET /v1/templates
  GET /v1/templates/:id
  POST /v1/templates/:id/use
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
    "name": "Non disclosure agreement template",
    "shared": false,
    "envelope_name": "Non disclosure agreement",
    "envelope_message": "Lorem ipsum dolor sit amet.",
    "envelope_shared": false,
    "created": "2019-12-17T05:30:00Z",
    "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
    "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
    "documents": [],
    "roles": []
  }
  ```
</ResponseExample>