> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/templates-and-reusable-ids.md).

# Templates and reusable IDs

This document explains how to find, reuse, and validate template and API identifiers in DocStudio integrations.

DocStudio API uses templates as the source for envelope structure. When you send an envelope from a template, the request must reuse identifiers from that template instead of creating new ones manually.

### How templates work in API flows

A template is a reusable document structure.\
It defines:

{% columns %}
{% column %}

* documents
* fields
* recipient roles
  {% endcolumn %}

{% column %}

* signature places
* workflow order
* other
  {% endcolumn %}
  {% endcolumns %}

When sending an envelope from a template, reuse the template workflow. Provide only data for this envelope: recipient mailboxes, field values, uploaded files, metadata, and other envelope data.

A typical template-based flow looks like this:

1. Choose or create a template.
2. Read the template structure.
3. Save the reusable identifiers from the template.
4. Find mailbox UUIDs for recipients.
5. Build the envelope XML with template identifiers.
6. Send the envelope.
7. Save the returned envelope UUID.

{% hint style="warning" %}
Use the template UUID, version, role IDs, document IDs, and field names from the same template version. Do not create or mix these values manually.
{% endhint %}

### Reusable identifiers

Reusable identifiers are values that connect API requests with existing DocStudio objects. They tell DocStudio which template, document, role, field, mailbox, attachment, or envelope the request uses.

Common reusable identifiers include:

{% columns %}
{% column %}

* template UUID
* template version
* role ID
* mailbox UUID
* document ID
* field name
* field group name
  {% endcolumn %}

{% column %}

* attachment UUID
* envelope UUID
* account UUID
* domain UUID
* dictionary UUID
* column UUID
  {% endcolumn %}
  {% endcolumns %}

Collect each identifier from its source:

{% columns %}
{% column %}
**Template**

* template UUID and version
* role IDs
* document IDs
* field and field group names
  {% endcolumn %}

{% column %}
**API responses**

* mailbox UUIDs from mailbox data
* attachment UUIDs from upload responses
* envelope UUIDs from send responses
  {% endcolumn %}
  {% endcolumns %}

{% hint style="info" %}
Use account, domain, dictionary, and column UUIDs only for their respective API flows.
{% endhint %}

### Template UUID and template version

The **template UUID** identifies the template, the **template version** identifies its exact structure version.

Use both values in the root envelope element.

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  ...
</envelope>
```

Get the template UUID and version from the template structure or response. Keep these values paired. After updating a template, use the current version.

{% hint style="warning" %}
Do not combine a template UUID with another template's version.

Do not use an old version when the envelope needs the current structure.
{% endhint %}

### Role ID

Roles are defined in the template flow. Each template role must have an `id`, `title`, and `type`. The optional `order` attribute controls the role position in the flow.

Valid template role:

```xml
<flow type="manual">
  <roles>
    <role id="customer" title="Customer" type="signer" order="1" />
  </roles>
</flow>
```

Supported `type` values are `sender`, `assignee`, `copy`, `signer`, and `approver`.

When you create or send an envelope, reuse the role `id` from the selected template version and assign a recipient mailbox. Do not recreate the template role or change its ID.

```xml
<flow>
  <roles>
    <role id="customer" mailboxUuid="{recipientMailboxUuid}" />
  </roles>
</flow>
```

The role ID connects the envelope participant to the role defined in the template. If the ID does not exist in the selected template version, DocStudio cannot assign the participant to the workflow.

{% hint style="warning" %}
DocStudio cannot assign the participant to the workflow if the role ID does not exist in the selected template version.
{% endhint %}

### Mailbox UUID

Mailbox UUIDs identify mailboxes that can send, receive, or process envelopes. Many API requests use a mailbox UUID as the sender context, recipient assignment, path parameter, or request header.

Use mailbox UUIDs when you need to:

* assign recipients to template roles
* search mailbox data
* check envelope status
* download envelope documents from a mailbox context
* perform actions from a specific mailbox

Example recipient assignment:

```xml
<role id="{roleId}" mailboxUuid="{recipientMailboxUuid}"/>
```

The token owner must have access to the mailbox used in the request. A valid token can still receive a 403 Forbidden error if the user or integration does not have access to the selected mailbox.

### Document ID

Documents are defined inside the template. Each document has an ID that must be reused when you send field values in an envelope request.

Example:

```xml
<documents>
  <document id="{documentId}">
    <field name="Customer name">ACME Ltd</field>
  </document>
</documents>
```

The document ID tells DocStudio which document contains the field. If the request uses the wrong document ID, field values may not be applied or the request may fail validation.

Use document IDs from the same template version that you reference in the envelope request.

### Field names

Field names identify fields inside template documents. When you send field values, use the exact field names from the template structure.

Example:

```xml
<field name="Customer name">ACME Ltd</field>
<field name="Signing date">2026-07-15</field>
```

Field names are case-sensitive and must match the template field names. Do not rename fields in the API request, even if the new name looks clearer.

Incorrect field names are one of the most common reasons why envelope data is not applied correctly.

### Field group names

Field group names are used when the template contains grouped fields or dynamic tables. The request must use the same field group names that exist in the template structure.

Example:

```xml
<fieldgroup name="Products">
  <fieldset index="0">
    <field name="Product name">Service plan</field>
    <field name="Quantity">1</field>
  </fieldset>
</fieldgroup>
```

Use field groups when the template expects repeated or grouped data. Do not invent new group names in the envelope request.

### Attachment UUIDs

Attachment UUIDs are returned after a file is uploaded to DocStudio. Use attachment UUIDs when a field or document must reference an uploaded file.

Example file field:

```xml
<field name="Attachment" attachmentUuid="{attachmentUuid}">agreement.pdf</field>
```

The attachment UUID must come from the file upload response. Do not use a local file path, file name, or external file URL instead of the attachment UUID.

### Envelope UUID

The envelope UUID identifies the envelope after it is created or sent.

Response example:

```json
{
  "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a"
}
```

Save the envelope UUID. You need it to check envelope status, download documents, get audit trail data, or perform follow-up actions.

The envelope UUID is not available before the envelope is created. It is returned by the send or create operation.

### Additional account and dictionary identifiers

#### Account and domain UUIDs

Account and domain UUIDs are used in account administration flows, such as managing corporate users and account domains.

For example, account domain endpoints can use an account UUID to identify the account and a domain UUID to identify a specific domain.

Use these identifiers only in account-level API flows. They are not the same as mailbox UUIDs, template UUIDs, or envelope UUIDs.

#### Dictionary and column UUIDs

Dictionaries and dictionary columns have their own UUIDs. These identifiers are used when templates contain dictionary or lookup fields.

Use dictionary UUIDs and column UUIDs when the API request needs to reference a specific dictionary or dictionary column. Do not replace them with dictionary names unless the endpoint explicitly supports that.

### Combine identifiers in an envelope request

A send envelope request combines identifiers from different sources.

Use [Working with XML payloads](/guides/xml-payloads.md) for the complete XML structure and escaping rules.

Example:

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  <flow>
    <roles>
      <role id="{roleId}" mailboxUuid="{recipientMailboxUuid}"/>
    </roles>
  </flow>
  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Attachment" attachmentUuid="{attachmentUuid}">agreement.pdf</field>
    </document>
  </documents>
</envelope>
```

In this example:

{% columns %}
{% column %}

* `templateUuid` comes from the template
* `templateVersion` comes from the template
* `roleId` comes from the template flow
* `recipientMailboxUuid` comes from mailbox data
  {% endcolumn %}

{% column %}

* `documentId` comes from the template document
* `Customer name` comes from the template field name
* `Attachment` comes from the template file field name
* `attachmentUuid` comes from the file upload response
  {% endcolumn %}
  {% endcolumns %}

Each value has a different source. Mixing values from different templates, versions, accounts, or mailboxes can cause validation errors or access errors.

### Get reusable identifiers

Use the template structure to get:

{% columns %}
{% column %}

* template UUID
* template version
* role IDs
* document IDs
  {% endcolumn %}

{% column %}

* field names
* field group names
* field types
* field validation settings
  {% endcolumn %}
  {% endcolumns %}

Use mailbox endpoints or account data to get:

* sender mailbox UUID
* recipient mailbox UUIDs
* mailbox names and aliases

Use file upload endpoints to get:

* attachment UUID
* uploaded file name
* uploaded file size

Use the send envelope response to get:

* envelope UUID

Use account endpoints to get:

* account UUID
* domain UUID
* corporate user-related identifiers

Use dictionary endpoints or dictionary configuration to get:

* dictionary UUID
* dictionary column UUID

### Recommended workflow

Before building a request, collect all required identifiers and check that they belong to the same flow.

Recommended preparation checklist:

1. Select the template.
2. Read the current template version.
3. Copy role IDs from the selected template version.
4. Copy document IDs from the selected template version.
5. Copy field names from the selected documents.
6. Find recipient mailbox UUIDs.
7. Upload files if the envelope needs file fields.
8. Save attachment UUIDs from upload responses.
9. Build the envelope XML.
10. Send the request.
11. Save the returned envelope UUID.

This preparation reduces validation errors and makes the integration easier to debug.

### Store identifiers safely

Avoid hardcoding template versions, role IDs, document IDs, field names, or mailbox UUIDs directly in source code if these values can change.

For stable production integrations, it can be acceptable to store known identifiers in secure configuration. However, the integration should still be reviewed when the template changes.

If a template is updated, check whether the reusable identifiers used by the integration are still valid.

### Handle template changes

When a template changes, the template version can also change. If your integration sends envelopes from that template, make sure the request uses the correct template version and structure.

After a template update, check:

{% columns %}
{% column %}

* whether the template version changed
* whether role IDs are still the same
* whether document IDs are still the same
* whether required fields were added or removed
  {% endcolumn %}

{% column %}

* whether field names changed
* whether field validation rules changed
* whether dynamic tables or field groups changed
  {% endcolumn %}
  {% endcolumns %}

If the integration still uses old identifiers, the send request can fail or apply data incorrectly.

### Common mistakes

Common reusable identifier mistakes include:

{% columns %}
{% column %}

* using a template UUID from one template and a template version from another template
* using role IDs copied from an old template version
* assigning a mailbox UUID to the wrong role
* using a mailbox UUID that the token owner cannot access
* sending field values to the wrong document ID
* using field names that do not exist in the selected template
  {% endcolumn %}

{% column %}

* changing field names manually in the API request
* using a file name instead of an attachment UUID
* using an envelope UUID where the endpoint expects a mailbox UUID
* using a mailbox UUID where the endpoint expects an account UUID
* reusing identifiers from a test environment in production
* reusing production identifiers in a staging or local test environment
  {% endcolumn %}
  {% endcolumns %}

### Troubleshooting checklist

If a request fails or does not apply data correctly, check the identifiers first.

{% columns %}
{% column %}

* the template UUID and template version are correct
* the role IDs and document IDs belong to the selected template version
* each role has the correct mailbox UUID
* the token owner can access the selected mailbox
* field names and field group names match the template exactly
  {% endcolumn %}

{% column %}

* attachment UUIDs come from successful upload responses
* the envelope UUID was copied from the send response
* account UUIDs are used only for account-level endpoints
* dictionary UUIDs and column UUIDs match the selected dictionary configuration
* the integration is not mixing identifiers from different environments
  {% endcolumn %}
  {% endcolumns %}

### Related topics

{% columns %}
{% column width="33.33333333333333%" %}

* [Working with XML payloads](/guides/xml-payloads.md)
* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Send Envelope](/api-reference/send-envelope.md)
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* [Search Mailboxes and Contacts](/api-reference/search-mailboxes-and-contacts.md)
* [Upload Attachments](/api-reference/upload-attachments.md)
  {% endcolumn %}

{% column %}

* [Create Template](/api-reference/create-template.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)
  {% endcolumn %}
  {% endcolumns %}