> 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/introduction/core-concepts.md).

# Core concepts

This document contains the main DocStudio API concepts and their relationships.

{% hint style="info" %}
This page explains the main DocStudio API concepts before working with endpoints and examples. DocStudio API is built around document workflows.
{% endhint %}

### How the main concepts work together

A typical DocStudio API workflow starts with a template. The template defines the reusable document structure, fields, recipient roles, signature places, and workflow order. Follow this workflow:

1. Choose or create a [template](/guides/templates-and-reusable-ids.md).
2. Read the template UUID, version, role IDs, document IDs, and field names.
3. Create an envelope from the template.
4. Assign recipient mailboxes to template roles.
5. [Send the envelope](/api-reference/send-envelope.md) and save its UUID.
6. Track its status, fill active fields, and download completed documents.

An envelope is the document workflow sent to recipients. Use its UUID to track status, download files, and get audit trail data.

### Key identifiers

Save these values when building an envelope request:

* template UUID
* template version
* role ID
* document ID
* field name
* mailbox UUID
* envelope UUID

### Account

An account is the main workspace where users, mailboxes, templates, domains, and document workflows are managed.

Corporate account integrations can also use API endpoints to manage account domains and create corporate users in bulk. For example, an integration can download an XLSX example file, fill it with user data, roles, permissions, and mailbox assignments, and upload it to create users in bulk.

### Mailbox

A mailbox is the API context for document actions. Use the sender mailbox to send an envelope. Use recipient mailboxes to assign participants to roles.

Some requests require a mailbox UUID in the header or path. Use it to find recipients, search envelopes, and check status. The mailbox context defines the available access.

Use [Search Mailboxes and Contacts](/api-reference/search-mailboxes-and-contacts.md) to find mailbox UUIDs. Use [Check Envelope Status](/api-reference/check-envelope-status.md) to track envelopes.

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

In this example, `roleId` comes from the template flow. The `mailboxUuid` identifies the mailbox assigned to that role.

### Template

A template is a reusable document structure. It defines document content, fields, roles, signatures, and workflow order. Reuse its data when creating or sending an envelope.

Reference the template with `templateUuid` and `templateVersion` in envelope requests.

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

These values connect the envelope to the exact template version. A wrong template version may cause request rejection or field validation errors.

Use [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md) to work with template structures and fields.

### Envelope

An envelope is a document workflow created from a template. It contains the documents, field values, recipients, workflow data, metadata, and status information needed to process the document.

Many envelope endpoints use XML inside the JSON `data` field. The XML describes the envelope structure, recipients, documents, and field values.

```json
{
  "data": "<envelope templateUuid=\"{templateUuid}\" templateVersion=\"{templateVersion}\">...</envelope>"
}
```

Use [Send Envelope](/api-reference/send-envelope.md) to create and send envelopes. Use [Fill Envelope](/api-reference/fill-envelope.md) to fill active fields. Follow [Send your first envelope](/introduction/send-your-first-envelope.md) to download completed documents.

### Recipient role

A recipient role defines who participates in the envelope workflow and what that participant must do. Roles are defined in the template flow. Each role has an ID, type, title, and order.

Role order controls when the recipient becomes active. A role may fill or sign fields after the previous role completes its step. A template role becomes an envelope participant after the request assigns its mailbox.

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

Assign real mailboxes to template roles when sending an envelope. This connects the template role to the recipient mailbox.

### Document

A document is part of a template or envelope. It can be a structured DocStudio document or an uploaded external file. Each document has a document ID.

Use the correct document ID when sending field values. This identifies the document that contains those fields. Send field values inside that document.

```xml
<documents>
  <document id="{documentId}">
    <field name="Customer name">ACME Ltd</field>
    <field name="Signing date">2026-07-15</field>
  </document>
</documents>
```

Match `documentId` and field names with the template structure. DocStudio validates field values against template field settings.

### Field

A field defines data that users can enter, select, upload, calculate, copy, or sign. DocStudio supports these field types:

{% columns %}
{% column %}

* text
* number
* currency
* number to text
* date
* dropdown
  {% endcolumn %}

{% column %}

* choice
* checkbox
* file
* dictionary
* lookup
  {% endcolumn %}

{% column %}

* dynamic table
* duplicate
* formula
* autonumber
* signature
  {% endcolumn %}
  {% endcolumns %}

Different field types can require different value formats. For example, a text field can use a simple value, a file field must reference an uploaded attachment, and a dynamic table uses field groups and fieldsets.

```xml
<field name="Text field">Text value</field>

<field name="File field" attachmentUuid="{attachmentUuid}">agreement.pdf</field>

<fieldgroup name="Table">
  <fieldset index="0">
    <field name="Row value">First row</field>
  </fieldset>
</fieldgroup>
```

Field configuration belongs to the template. Send or fill field values later in envelope requests. Use exact field names from the template structure.

### Metadata

Metadata is extra envelope data outside document content. It can store external IDs, flags, references, and other business-specific values for later processing.

```json
{
  "customerId": "C-1024",
  "approved": true,
  "externalReference": null
}
```

Use metadata to connect external records with DocStudio envelopes. It can store a customer ID, order ID, CRM record ID, department, campaign, or internal process reference.

Store metadata as key-value pairs. Add it to envelopes and envelope forms. Envelopes created from a form can inherit the same values.

### Envelope form link

An envelope form link lets users create envelopes from a shared link. The form uses a template with predefined fields and roles. After users submit required fields, DocStudio creates a new envelope.

Envelope form links can use metadata and callbacks. This supports public or semi-public intake flows.

### Audit trail

Audit trail data records envelope history and participant actions. It can be used to inspect what happened during envelope processing, track completion details, or store document workflow history in an external system.

### Dictionary

A dictionary is a predefined dataset for dictionary and lookup fields in templates. Use dictionaries for controlled values, such as customers, products, departments, regions, or other business-specific lists.

Import dictionary data from CSV files through [Dictionaries](/api-reference/dictionaries.md).

### Widget

A widget is an embeddable DocStudio flow for an external web page. The [Simple File Send Widget](/guides/simple-file-send-widget.md) lets users send files for signing without signing in to DocStudio.

Use widgets to expose a limited DocStudio workflow outside the main platform interface.

### Status

Envelope status shows the envelope's place in the workflow. Status values help integrations decide what to do next. Common envelope statuses include:

* DRAFT
* WAITING
* COMPLETED
* EXPIRED
* CANCELLED

Use mailbox and envelope status endpoints to search, filter, and track envelopes.

### Before you send an envelope

Confirm the template, mailbox, role, document, and field used by your request. Most envelope requests depend on template identifiers and mailbox context.

Choose a template first. Read its identifiers. Assign the correct mailbox UUIDs to roles. Then send or fill the envelope using the same template structure.