> 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/fill-envelope.md).

# Fill Envelope

### Method

<table><thead><tr><th width="321">Method</th><th>PUT</th></tr></thead><tbody><tr><td>URL</td><td><code>/api/v1/envelope/mailbox/{uuid}/{action}</code></td></tr><tr><td>Authorization</td><td>Bearer {token}</td></tr><tr><td>Content-Type</td><td>application/json</td></tr><tr><td>Body</td><td><code>{"data":"string"}</code></td></tr></tbody></table>

Use this endpoint to fill fields assigned to the current recipient in an existing envelope. Send only the fields owned by the active role.

### How it works

Create and send the envelope first. Then call this endpoint from the mailbox of the recipient who is currently active in the envelope flow.

Reuse the same template objects that exist in the template definition, including the template UUID, template version, document IDs, field names, and field owner role.

#### Template example

This simplified template example shows how the field owner is defined.

```xml
<template uuid="500afafd-711e-471a-a18f-24a89cd4ede3" version="143a2a4b-325e-4c05-a4c1-52f44e21b745">
    <documents>
        <document id="ef247568-559a-4ec1-9ecc-6b44c9fb8215">
            <field type="text" name="TEST template 2" roleId="b811f2b6-1656-42aa-9420-a9b8addb0246"/>
        </document>
    </documents>
    <flow>
        <roles>
            <role id="23f20eec-adad-4325-b553-1bde4be29198" title="Sender" type="sender" order="0"/>
            <role id="b811f2b6-1656-42aa-9420-a9b8addb0246" title="Assignee" type="assignee" order="1"/>
        </roles>
    </flow>
</template>
```

In this example, only the **Assignee** role can fill the `TEST template 2` field, because the field uses `roleId="b811f2b6-1656-42aa-9420-a9b8addb0246"`. The **Assignee** can fill it only after the **Sender** completes the previous step, because the **Sender** has order `0` and the **Assignee** has order `1`.

{% hint style="info" %}
Wait until the role becomes active in the envelope flow. If another mailbox or role sends the request, the API rejects it.
{% endhint %}

### Path parameters

* `uuid` — mailbox UUID of the current recipient
* `action` — action required for the current processing step

### Request body

Send the envelope XML as a string inside the `data` field. Reuse the same `templateUuid`, `templateVersion`, `document/@id`, and `field/@name` values from the template, then send only the field values that the active role must fill.

### Request example

This example shows the XML payload that you pass inside the `data` field. It fills the field owned by the **Assignee** role from the template shown above.

```xml
<envelope templateUuid="500afafd-711e-471a-a18f-24a89cd4ede3" templateVersion="143a2a4b-325e-4c05-a4c1-52f44e21b745">
    <documents>
        <document id="ef247568-559a-4ec1-9ecc-6b44c9fb8215">
            <field name="TEST template 2">12312</field>
        </document>
    </documents>
</envelope>
```

### What happens next

Apply the provided values to the matching template fields. If the current step is complete, move the envelope to the next role in the flow. Show the saved data to the next recipient when they open the envelope.

### Related topics

* [Envelope Structure](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/envelope-structure)
* [Send Envelope](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/envelope/send-envelope)
* [Create Template](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/api-methods/create-template)
* [Check Envelope Status](https://support.docstudio.com/docstudio-docs/docstudio-for-developers/api-documentation/api-methods/check-envelope-status)