> 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/examples/send-envelope-with-prefilled-fields.md).

# Send Envelope with Prefilled Fields

This document explains how to send a template envelope with prefilled fields.

### Scenario

Send an envelope from a template and prefill several fields before recipients open it. Use this example when an external system already has business data, such as customer name, contract number, amount, start date, or selected payment method, and this data must be inserted into the envelope automatically.

The template must already contain the fields that you want to prefill. The API request does not create new fields or change field configuration; it only sends values for fields that already exist in the selected template version.

### Step 1 Prepare template values

| Method | Endpoint                |
| ------ | ----------------------- |
| `POST` | `/api/v1/envelope/send` |

Prepare all identifiers before building the request. Use values from the selected template version.

You need:

{% columns %}
{% column %}

* API token
* sender mailbox UUID
* template UUID
* template version UUID
* role IDs from the template flow
  {% endcolumn %}

{% column %}

* recipient mailbox UUIDs
* document IDs from the template
* exact field names from the selected document
* values that match field validation rules
  {% endcolumn %}
  {% endcolumns %}

#### Prefilled fields

<table><thead><tr><th width="164">Field name</th><th width="200">Example value</th><th>Value requirements</th></tr></thead><tbody><tr><td><code>customer_name</code></td><td><code>ACME Ltd</code></td><td>text value</td></tr><tr><td><code>contract_number</code></td><td><code>SA-2026-001</code></td><td>value defined by the template configuration</td></tr><tr><td><code>quantity</code></td><td><code>10</code></td><td>numeric value</td></tr><tr><td><code>total_amount</code></td><td><code>1250.50</code></td><td>numeric or currency value</td></tr><tr><td><code>start_date</code></td><td><code>2026-07-15T10:00:00Z</code></td><td>date or date-time format accepted by the field</td></tr><tr><td><code>payment_method</code></td><td><code>Bank transfer</code></td><td>value matching the configured option</td></tr></tbody></table>

### Step 2 Build envelope XML

Add field values inside the `documents` block. Each value must be placed inside a `field` element with the same `name` used in the template field configuration.

```xml
<envelope templateUuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5" templateVersion="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585">
  <info>
    <subject>Sales agreement for ACME Ltd</subject>
    <message>Please review and complete the agreement.</message>
  </info>
  <flow>
    <roles>
      <role id="23f20eec-adad-4325-b553-1bde4be29198" mailboxUuid="9baec31c-e940-4894-b6d1-52033e1af66e" />
      <role id="b811f2b6-1656-42aa-9420-a9b8addb0246" mailboxUuid="42c95245-30c1-46ef-bd5b-a9a111deec10" />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="customer_name">ACME Ltd</field>
      <field name="contract_number">SA-2026-001</field>
      <field name="quantity">10</field>
      <field name="total_amount">1250.50</field>
      <field name="start_date">2026-07-15T10:00:00Z</field>
      <field name="payment_method">Bank transfer</field>
    </document>
  </documents>
</envelope>
```

Use the document ID and field names from the selected template version. Place each value under the document where that field is configured.

### Step 3 Send the request

#### Headers

<table><thead><tr><th width="142">Header</th><th width="172">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>application/json</code></td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Sender mailbox UUID used as the mailbox context</td></tr></tbody></table>

#### Request body

Send the envelope XML as a string in the JSON `data` field. Escape XML quotes and line breaks so the value remains valid JSON.

```json
{
  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\"><info><subject>Sales agreement for ACME Ltd</subject><message>Please review and complete the agreement.</message></info><flow><roles><role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\"/><role id=\"b811f2b6-1656-42aa-9420-a9b8addb0246\" mailboxUuid=\"42c95245-30c1-46ef-bd5b-a9a111deec10\"/></roles></flow><documents><document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\"><field name=\"customer_name\">ACME Ltd</field><field name=\"contract_number\">SA-2026-001</field><field name=\"quantity\">10</field><field name=\"total_amount\">1250.50</field><field name=\"start_date\">2026-07-15T10:00:00Z</field><field name=\"payment_method\">Bank transfer</field></document></documents></envelope>"
}
```

<table><thead><tr><th width="99">Field</th><th width="80">Type</th><th width="123">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>UUID</td><td>No</td><td>Envelope UUID when the flow already has an identifier</td></tr><tr><td><code>data</code></td><td>string</td><td>Yes</td><td>Envelope XML string with prefilled field values</td></tr><tr><td><code>metadata</code></td><td>object</td><td>No</td><td>Custom key-value metadata added to the envelope</td></tr></tbody></table>

### Request example

```http
POST /api/v1/envelope/send
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {senderMailboxUuid}

{
  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\"><info><subject>Sales agreement for ACME Ltd</subject><message>Please review and complete the agreement.</message></info><flow><roles><role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\"/><role id=\"b811f2b6-1656-42aa-9420-a9b8addb0246\" mailboxUuid=\"42c95245-30c1-46ef-bd5b-a9a111deec10\"/></roles></flow><documents><document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\"><field name=\"customer_name\">ACME Ltd</field><field name=\"contract_number\">SA-2026-001</field><field name=\"quantity\">10</field><field name=\"total_amount\">1250.50</field><field name=\"start_date\">2026-07-15T10:00:00Z</field><field name=\"payment_method\">Bank transfer</field></document></documents></envelope>"
}
```

### Step 4 Save the envelope UUID

The endpoint returns `201 Created` with the created envelope UUID. Save this UUID for follow-up operations.

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

| Field  | Type | Description           |
| ------ | ---- | --------------------- |
| `uuid` | UUID | Created envelope UUID |

### Step 5 Continue processing

Use the returned UUID to check envelope status and download the envelope archive.

### Common mistakes

{% hint style="warning" %}
Use identifiers from the same template version. Set the sender mailbox in `Mailbox`, assign each template role to the correct recipient mailbox, and pass valid field values in the XML `data` string.
{% endhint %}