> ## 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.

# Use a template

Creates a new envelope using a predefined template.

This endpoint allows you to generate an envelope by inheriting roles, fields, and documents from a template — eliminating the need to define recipients and layout manually.

Each role in the template must be matched with a corresponding recipient in the request, and the number of recipients must match the number of roles exactly. Fields assigned to each role will automatically carry over to the matched recipient.

Template documents are automatically used unless you explicitly replace them. When replacing a document, the new document must contain the **same number of pages** as the one it's replacing, and **page dimensions must be similar** to preserve field positioning.

You may also choose to create the envelope in a draft state for manual preparation via the Annature dashboard.

## Parameters

<ParamField path="id" required>
  The unique identifier of the template being used to create the envelope.
</ParamField>

<ParamField path="name" type="conditionally required">
  The name of the envelope, shown in the subject line of emails and in the Annature dashboard.

  Required only if the template does not define a default `envelope_name`.
</ParamField>

<ParamField path="message" type="optional">
  Custom message displayed in recipient emails and the Annature UI.

  If not provided, the template's `envelope_message` value will be used if available.
</ParamField>

<ParamField path="share" type="optional">
  Whether the envelope should be shared with the sender's group.

  Defaults to the template's `envelope_shared` setting if not explicitly provided.
</ParamField>

<ParamField path="draft" type="optional">
  Set to `true` to create the envelope as a draft.

  Drafts can be opened and edited in the Annature dashboard via:\
  `https://dashboard.annature.com.au/create-envelope?envelopeId={{envelope_id}}`
</ParamField>

<ParamField path="account_id" required>
  The unique identifier of the sender creating the envelope.
</ParamField>

<ParamField path="group_id" type="optional">
  Overrides the default group inheritance from the sender.

  If not supplied, the envelope inherits the sender’s group automatically.
</ParamField>

<ParamField path="documents" type="optional">
  A list of documents to replace those defined in the template.

  Each replacement must reference the `id` of the template document being replaced, and have the same number of pages with similar dimensions.

  <Expandable title="child arguments">
    <ResponseField name="replacing" required>
      The `id` of the template document being replaced.
    </ResponseField>

    <ResponseField name="id" type="optional">
      A user-defined identifier for the new document.
    </ResponseField>

    <ResponseField name="name" type="optional">
      Display name of the document.
    </ResponseField>

    <ResponseField name="base" required>
      Base64-encoded string of the PDF file.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="recipients" required>
  A list of recipients to be assigned to roles from the template.

  The number of recipients must match the number of template roles.

  <Expandable title="child arguments">
    <ResponseField name="role_id" required>
      The ID of the role the recipient is inheriting fields and settings from.
    </ResponseField>

    <ResponseField name="name" type="conditionally required">
      The recipient's name.

      Required only if the role does not define a default `recipient_name`.
    </ResponseField>

    <ResponseField name="email" type="conditionally required">
      The recipient's email address.

      Required only if the role does not define a default `recipient_email`.
    </ResponseField>

    <ResponseField name="mobile" type="optional">
      The recipient’s mobile number in E.164 format.
    </ResponseField>

    <ResponseField name="message" type="optional">
      A message specific to this recipient, overriding the envelope message.
    </ResponseField>

    <ResponseField name="password" type="optional">
      A code or passphrase the recipient must enter to access the envelope.
    </ResponseField>

    <ResponseField name="muted" type="optional">
      Whether Annature should suppress all emails to this recipient.
    </ResponseField>

    <ResponseField name="redirects" type="optional">
      Destination URLs to redirect the recipient after specific actions.

      <Expandable title="child arguments">
        <ResponseField name="session_completed" type="optional">
          Redirect URL after the recipient completes the envelope.
        </ResponseField>

        <ResponseField name="session_declined" type="optional">
          Redirect URL after the recipient declines the envelope.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

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

  ```json Body theme={null}
  {
    "id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
    "name": "Non disclosure agreement",
    "message": "Lorem ipsum dolor sit amet.",
    "shared": false,
    "draft": false,
    "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
    "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
    "documents": [{
      "replacing": "fcad499b03c6fc222bc66208317a18c9",
      "id": "0a0cd6ec2daae5e1750dabc87953f933",
      "name": "Non disclosure agreement.pdf",
      "base": "iVBORw0KGgoAAAANSUhE.."
    }],
    "recipients": [{
      "role_id": "fcad499b03c6fc222bc66208317a18c9",
      "name": "Ted Annature",
      "email": "ted@annature.com.au",
      "mobile": "+61422000000",
      "message": "Lorem ipsum dolor sit amet.",
      "password": "password1",
      "muted": false,
      "redirects": {
        "session_completed": "https://..",
        "session_declined": "https://.."
      }
    }]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "7e8f68e4c6df9395cd7ff48d69d7e2c1",
    "name": "Non disclosure agreement",
    "message": "Lorem ipsum dolor sit amet.",
    "status": "sent",
    "shared": false,
    "created": "2019-12-17T05:30:00Z",
    "sent": "2019-12-17T05:30:00Z",
    "voided": null,
    "declined": null,
    "completed": null,
    "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
    "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
    "recipients": [{
      "id": "255e591c2c9fe1bc99be1ec03075b402",
      "name": "Ted Annature",
      "email": "ted@annature.com.au",
      "mobile": "+61422000000",
      "type": "signer",
      "status": "sent",
      "message": "Lorem ipsum dolor sit amet.",
      "password": false,
      "muted": false,
      "order": 1,
      "declined_reason": null,
      "created": "2019-12-17T05:30:00Z",
      "sent": "2019-12-17T05:30:00Z",
      "declined": null,
      "completed": null,
      "redirects": {
        "session_completed": "https://..",
        "session_declined": "https://.."
      }
    }]
  }
  ```
</ResponseExample>