Fill Envelope

This document explains how to fill an existing envelope via the API, including recipient role rules, the request body format, and an example payload.

Method

Method	PUT
URL	/api/v1/envelope/mailbox/{uuid}/{action}
Authorization	Bearer {token}
Content-Type	application/json
Body	{"data":"string"}

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.

<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.

Wait until the role becomes active in the envelope flow. If another mailbox or role sends the request, the API rejects it.

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.

<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

• Send Envelope

• Create Template

• Check Envelope Status