> 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/api-documentation/envelope/envelope-structure.md).

# Envelope Structure

{% hint style="info" %}
**Looking for user documentation?**

If you want to learn how to use DocStudio in the interface, open the user documentation. It explains how to sign in, create and send envelopes, work with templates, sign documents, manage mailboxes, and configure account settings.

[Open DocStudio Knowledge Base](https://support.docstudio.com/)
{% endhint %}

Use this XML inside the `data` field of envelope API requests. Send only the fields your request needs.

{% hint style="info" %}
The platform generates some envelope properties automatically.
{% endhint %}

### Example

```xml
<envelope templateUuid="1997a1b4-88e3-4f58-88ca-fcd2c6fb5869" templateVersion="4a303734-a118-44a2-aedf-67df61612628">
    <info>
        <subject>Sales agreement</subject>
        <message>Please review the attached data.</message>
        <forwarding delegation="true" sharing="true"/>
    </info>
    <flow>
        <roles>
            <role id="74266bb8-91ad-4e35-9d98-5862fc59cf3e" mailboxUuid="8dcde243-a918-444a-ac7d-44ac88554769"/>
            <role id="a09d90c7-46c1-4f59-8d76-e7975dd8fab6" mailboxUuid="8dcde243-a918-444a-ac7d-44ac88554769"/>
        </roles>
    </flow>
    <documents>
        <document id="16c545db-1002-4efb-a4de-b46bc5ed4885">
            <field name="Text">text</field>
            <field name="Number">10</field>
            <field name="Currency">10.20</field>
            <field name="Date">2024-01-11</field>
            <field name="Dictionary" recordUuid="76d0b4a4-114f-45a6-9039-d654c90a2df2">Record name</field>
            <field name="Signature">data:image/png;base64,iVBORw...K5CYII=</field>
            <field name="File" attachmentUuid="dc317260-adf3-4231-8eaa-588759d7b6f7">agreement.pdf</field>
            <field name="Checkbox">1</field>
            <field name="Dropdown">2</field>
            <field name="Dropdown 2">
                <value>1</value>
                <value>2</value>
            </field>
            <field name="1234">Choice</field>
            <fieldgroup name="Table">
                <fieldset index="0">
                    <field name="Text 2">1</field>
                </fieldset>
                <fieldset index="1">
                    <field name="Text 2">2</field>
                </fieldset>
            </fieldgroup>
        </document>
    </documents>
</envelope>
```

### Envelope root

<table><thead><tr><th width="158">Attribute</th><th width="85">Type</th><th width="107">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>templateUuid</code></td><td>UUID</td><td>yes</td><td>Template ID used to create the envelope</td></tr><tr><td><code>templateVersion</code></td><td>UUID</td><td>yes</td><td>Template version ID used for validation</td></tr></tbody></table>

### Info block

Use `<info>` to define envelope-level communication settings, including the subject, message, expiration, and forwarding options.

<table><thead><tr><th width="214">Element or attribute</th><th width="90">Type</th><th width="108">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>subject</code></td><td>string</td><td>depends</td><td>Envelope subject</td></tr><tr><td><code>message</code></td><td>string</td><td>no</td><td>Short message for recipients</td></tr><tr><td><code>expire</code></td><td>integer</td><td>no</td><td>Number of days before the envelope expires</td></tr><tr><td><code>forwarding/@delegation</code></td><td>boolean</td><td>no</td><td>Allow delegation</td></tr><tr><td><code>forwarding/@sharing</code></td><td>boolean</td><td>no</td><td>Allow sharing</td></tr></tbody></table>

### Flow block

Use `<flow>` to define recipients and map template roles to mailbox IDs.

<table><thead><tr><th width="174">Element or attribute</th><th width="82">Type</th><th width="107">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>role/@id</code></td><td>UUID</td><td>yes</td><td>Role ID from the template</td></tr><tr><td><code>role/@mailboxUuid</code></td><td>UUID</td><td>yes</td><td>Mailbox ID assigned to that role</td></tr></tbody></table>

### Documents block

Use `<documents>` to send field values for each template document, including standard fields, dictionary references, file attachments, and table rows.

<table><thead><tr><th width="206">Element or attribute</th><th width="81">Type</th><th width="106">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>document/@id</code></td><td>UUID</td><td>yes</td><td>Document ID from the template</td></tr><tr><td><code>field/@name</code></td><td>string</td><td>yes</td><td>Template field name</td></tr><tr><td><code>field</code> value</td><td>string</td><td>depends</td><td>Field value, validated by the template</td></tr><tr><td><code>field/@recordUuid</code></td><td>UUID</td><td>depends</td><td>Dictionary record ID</td></tr><tr><td><code>field/@attachmentUuid</code></td><td>UUID</td><td>depends</td><td>Uploaded attachment ID</td></tr><tr><td><code>fieldgroup/@name</code></td><td>string</td><td>yes</td><td>Dynamic table name</td></tr><tr><td><code>fieldset/@index</code></td><td>integer</td><td>yes</td><td>Zero-based row index</td></tr></tbody></table>

### Dynamic field formats

#### Text, Number, Currency, Date, and single-select Dropdown

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

* `name` — field name from the template
* value — field value

The platform validates the value against the template rules.

#### Multi-select Dropdown

```xml
<field name="string">
    <value>1</value>
    <value>2</value>
</field>
```

Use one `<value>` element for each selected option.

#### Dictionary

```xml
<field name="string" recordUuid="UUID">value</field>
```

* `name` — dictionary field name
* `recordUuid` — dictionary record ID
* value — record label, if needed

If you send both `recordUuid` and text, they must match.

#### Signature

```xml
<field name="string">data:image/png;base64,...</field>
```

Send the signature as a Base64 data URL.

#### File

```xml
<field name="string" attachmentUuid="UUID">filename.ext</field>
```

Upload the file first, then send the returned attachment ID. Use [Upload Attachment/External Documents Method](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/api-methods/upload-attachment-external-documents-method) to get `attachmentUuid`.

#### Checkbox

```xml
<field name="string">1</field>
```

Send `1` to mark the checkbox as selected. Skip the field when it is optional and unchecked.

#### Choice

```xml
<field name="group-name">option-name</field>
```

* `name` — radio group name
* value — selected option name inside that group

#### Duplicate, Lookup, and Autonumber

Do not send these fields manually. The platform fills them automatically.

#### Dynamic table

```xml
<fieldgroup name="string">
    <fieldset index="0">
        <field name="Text 2">1</field>
    </fieldset>
    <fieldset index="1">
        <field name="Text 2">2</field>
    </fieldset>
</fieldgroup>
```

Add one `<fieldset>` for each row you need. Use a zero-based `index` for each row.

### Platform-generated fields

You may also encounter envelope properties generated by the platform.

* `created`
* `status`
* `date`
* `roleId`
* `active`
* `completed`

Treat these fields as system data unless an endpoint requires them.

### Related topics

* [Envelope Forms](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/envelope-forms)
* [Fill Envelope](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/fill-envelope)
* [Dictionary Field API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/template-api/template-dynamic-fields-api/dictionary-field-api)
* [File Field API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/template-api/template-dynamic-fields-api/file-field-api)
* [Signature Field API](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/template-api/template-dynamic-fields-api/signature-field-api)