> 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/xml-payloads.md).

# XML payloads

This document explains how to build, escape, and validate XML payloads for DocStudio API requests.

{% hint style="info" %}
Some DocStudio API endpoints use XML payloads to describe templates, envelopes, documents, recipient roles, and field values.
{% endhint %}

### When XML payloads are used

DocStudio uses XML payloads when a request needs to describe a document or an envelope structure.\
XML is used because templates and envelopes can contain:

* documents
* fields
* roles
* field groups
* dynamic tables
* attachments
* workflow settings

Common API operations that can use XML payloads include:

{% columns %}
{% column %}

* creating a template
* creating and sending an envelope from a template
* filling fields in an existing envelope
* passing document field values
  {% endcolumn %}

{% column %}

* assigning recipient mailboxes to template roles
* referencing uploaded files in file fields
* working with dynamic tables and field groups
  {% endcolumn %}
  {% endcolumns %}

Not every API endpoint uses XML. Many endpoints use JSON, query parameters, path parameters, or file upload formats.

{% hint style="info" %}
Always check the API reference for the exact request format required by the endpoint.
{% endhint %}

### Send XML in the JSON data field

Use the readable XML form while preparing the payload. Send the same XML as a JSON string in the `data` field.

{% tabs %}
{% tab title="Readable XML" %}

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  <info>
    <subject>Envelope subject</subject>
    <message>Envelope message</message>
  </info>
</envelope>
```

{% endtab %}

{% tab title="JSON request body" %}

```json
{
  "data": "<envelope templateUuid=\"{templateUuid}\" templateVersion=\"{templateVersion}\"><info><subject>Envelope subject</subject><message>Envelope message</message></info></envelope>"
}
```

{% endtab %}
{% endtabs %}

### Main parts of an envelope XML payload

A basic envelope XML payload usually contains:

* envelope attributes
* envelope information
* workflow roles
* documents
* field values

**Example**:

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  <info>
    <subject>Envelope subject</subject>
    <message>Envelope message</message>
  </info>
  <flow>
    <roles>
      <role id="{roleId}" mailboxUuid="{mailboxUuid}"/>
    </roles>
  </flow>
  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Signing date">2026-07-15</field>
    </document>
  </documents>
</envelope>
```

#### Envelope attributes

The root envelope element connects the new envelope to a specific template and template version.

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

Use values from the template structure:

* `templateUuid` identifies the template.
* `templateVersion` identifies the exact template version.

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

#### Envelope information

The info block contains general envelope information, such as the subject and message.

```xml
<info>
  <subject>Envelope subject</subject>
  <message>Envelope message</message>
</info>
```

Use this block to define what recipients see when they receive or open the envelope. The exact available properties depend on the endpoint and envelope settings.

#### Workflow roles

The flow block assigns real recipient mailboxes to roles from the template.

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

The `id` value comes from the template role. The `mailboxUuid` value identifies the mailbox assigned to that role in the envelope.

{% hint style="info" %}
The role defines what the participant must do, and the mailbox UUID defines who receives or processes that role.

If the role ID is copied from the wrong template or the mailbox UUID does not belong to an accessible mailbox, the request can fail or the envelope can be sent to the wrong participant.
{% endhint %}

#### Documents

The documents block contains the documents included in the envelope and the field values that must be applied to those documents.

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

{% hint style="info" %}

* The `documentId` must match the document ID from the template structure.
* Field names must match the field names from that document.
  {% endhint %}

Use the exact field names from the template. A different XML field name may prevent the value from being applied or cause a validation error.

#### Field values

Field values are passed inside field elements.

```xml
<field name="Customer name">ACME Ltd</field>
```

{% hint style="info" %}
Different field types can require different value formats:

* Text fields use plain text
* Date fields use a supported date format
* File fields reference an uploaded attachment
  {% endhint %}

File field example:

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

Do not use a local file path or file name as the **attachment identifier**, the `attachmentUuid` value must come from a previous file upload response.

#### Dynamic tables and field groups

Dynamic tables and grouped fields use nested field group structures.

Use field groups when the template contains repeatable table rows or grouped field sets.

**Example**:

```xml
<fieldgroup name="Products">
  <fieldset index="0">
    <field name="Product name">Service plan</field>
    <field name="Quantity">1</field>
    <field name="Price">100</field>
  </fieldset>
  <fieldset index="1">
    <field name="Product name">Support package</field>
    <field name="Quantity">2</field>
    <field name="Price">50</field>
  </fieldset>
</fieldgroup>
```

Each `fieldset` is one repeated row. Its `index` sets the row position.

Use field group and field names exactly as they appear in the template. Do not add names to the envelope request.

### Escape XML and JSON values

If a field value contains reserved characters, they must be escaped so the XML remains valid.

Use these XML escapes:

* `&amp;` for `&`
* `&lt;` for `<`
* `&gt;` for `>`
* `&quot;` for `"`
* `&apos;` for `'`

**Example**:

```xml
<field name="Company">ACME &amp; Partners</field>
```

If reserved characters are not escaped, the API may reject the request because the XML is not valid.

#### Escape JSON values

When XML is sent **inside** a JSON string, JSON escaping rules also apply. This means quotation marks inside XML attributes must be escaped.

**Readable XML**:

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

**XML inside JSON**:

```json
{
  "data": "<role id=\"{roleId}\" mailboxUuid=\"{mailboxUuid}\"/>"
}
```

If you build requests in code, use a reliable XML builder and JSON serializer when possible. Avoid manually concatenating large XML strings if the integration can generate XML and serialize JSON safely.

### Do not send system-generated values

Some values are generated by DocStudio and should not be sent manually in XML payloads.

For example, DocStudio generates the following values:

* envelope status
* creation date
* completion data
* active role state
* other system-managed values

The platform controls these values.

Send only the values that the endpoint expects and that your integration needs to provide. Do not copy system-generated values from an existing envelope and try to reuse them in a new request.

### Get required values

Before building an envelope XML payload, collect the reusable identifiers from the correct sources.

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
* validation settings
  {% endcolumn %}
  {% endcolumns %}

Use **mailbox endpoints** or **existing account data** to get:

* sender mailbox UUID
* recipient mailbox UUIDs
* mailbox context required by the endpoint

Use **file upload endpoints** to get:

* attachment UUIDs
* uploaded file metadata

Use the **send envelope response** to get:

* envelope UUID

{% hint style="info" %}
The envelope UUID is returned after the envelope is created or sent.

**Save it** because you will need it to check status, download documents, or get audit trail data.
{% endhint %}

### Common mistakes

Most XML payload issues happen when the request contains incorrect identifiers, invalid XML, or values that do not match the template configuration.

Common mistakes include:

{% columns %}
{% column %}

* using a template UUID from one template and role IDs from another template
* using an outdated template version
* creating role IDs, document IDs, or field names manually
* using a mailbox UUID that the token owner cannot access
* sending field values for fields that do not exist in the selected document
* using the wrong field value format
  {% endcolumn %}

{% column %}

* forgetting to escape XML reserved characters
* forgetting to escape quotation marks when XML is placed inside JSON
* sending XML that is not wrapped in the JSON data field
* using a file name instead of an attachment UUID for file fields
* copying system-generated envelope values into a new request
  {% endcolumn %}
  {% endcolumns %}

### Troubleshooting checklist

If an XML payload fails validation, check these points first:

{% columns %}
{% column %}

* The XML is valid and well-formed.
* The XML is passed as a string inside the JSON data field.
* Quotation marks are escaped correctly in the JSON string.
* Reserved XML characters are escaped in field values.
* The template UUID and template version are correct.
* Role IDs and document IDs match the selected template version.
* Mailbox UUIDs are correct and accessible.
  {% endcolumn %}

{% column %}

* Field names match the template exactly.
* Field values match the expected field types and validation rules.
* File fields use valid attachment UUIDs.
* Dynamic table and field group names match the template.
* The request does not include values that DocStudio generates automatically.
  {% endcolumn %}
  {% endcolumns %}

### Related topics

{% columns %}
{% column %}

* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Send Envelope](/api-reference/send-envelope.md)
* [Create Template](/api-reference/create-template.md)
  {% endcolumn %}

{% column %}

* [Fill Envelope](/api-reference/fill-envelope.md)
* [Upload Attachments](/api-reference/upload-attachments.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)
  {% endcolumn %}
  {% endcolumns %}