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:

• API token

• sender mailbox UUID

• template UUID

• template version UUID

• role IDs from the template flow

• recipient mailbox UUIDs

• document IDs from the template

• exact field names from the selected document

• values that match field validation rules

Prefilled fields

Field name	Example value	Value requirements
customer_name	ACME Ltd	text value
contract_number	SA-2026-001	value defined by the template configuration
quantity	10	numeric value
total_amount	1250.50	numeric or currency value
start_date	2026-07-15T10:00:00Z	date or date-time format accepted by the field
payment_method	Bank transfer	value matching the configured option

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.

<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

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	Use application/json
Mailbox	Yes	Sender mailbox UUID used as the mailbox context

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.

{
  "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>"
}

Field	Type	Required	Description
uuid	UUID	No	Envelope UUID when the flow already has an identifier
data	string	Yes	Envelope XML string with prefilled field values
metadata	object	No	Custom key-value metadata added to the envelope

Request example

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.

{
  "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

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.