Send Envelope from Template

This document explains how to create, send, track, and download an envelope from a DocStudio template.

Scenario

Send a sales agreement from a saved DocStudio template. The template already contains the document structure, recipient roles, and fields, so the API request only needs to reference the selected template version, assign real recipient mailboxes to template roles, and pass field values.

Use this example when the envelope structure is already prepared in DocStudio and the external system only starts the workflow. For example, a CRM can create an envelope from a contract template, assign the customer and manager mailboxes, prefill agreement data, and save the returned envelope UUID for tracking.

Step 1 Prepare template values

Method	Endpoint
POST	/api/v1/envelope/send

Prepare all identifiers before building the request. Do not create template UUIDs, template versions, role IDs, document IDs, or field names manually; these values must come 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

• field names from the template

Template value	Used in envelope XML
template/@uuid	envelope/@templateUuid
template/@version	envelope/@templateVersion
role/@id	flow > roles > role/@id
recipient mailbox UUID	flow > roles > role/@mailboxUuid
document/@id	documents > document/@id
field/@name	documents > document > field/@name

Template fragment

This simplified template fragment shows the values that must be reused in the send request. The example has two roles and one document field; the envelope XML must use the same template UUID, template version, role IDs, document ID, and field name.

<template uuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5" version="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585">
  <flow>
    <roles>
      <role id="23f20eec-adad-4325-b553-1bde4be29198" />
      <role id="b811f2b6-1656-42aa-9420-a9b8addb0246" />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="date field" type="date" />
    </document>
  </documents>
</template>

Step 2 Build envelope XML

Build the envelope XML by referencing the template and assigning recipient mailboxes to the template roles. Field values must be placed under the correct document ID and field name from the same template version.

<envelope templateUuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5" templateVersion="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585">
  <info>
    <subject>Sales agreement</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="date field">2026-07-21</field>
    </document>
  </documents>
</envelope>

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 envelope XML as a string in data. Add metadata when the envelope needs external identifiers or other integration references.

{  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\"><info><subject>Sales agreement</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=\"date field\">2026-07-21</field></document></documents></envelope>"}

Field	Type	Required	Description
uuid	UUID	No	Envelope UUID, when the flow already has an envelope identifier.
data	string	Yes	Envelope XML string.
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": "{envelopeXml}"
}

Step 4 Save the envelope UUID

The endpoint returns 201 Created with the created envelope UUID. Save this UUID in the external system, because it is required for follow-up operations such as retrieving the envelope, checking its status, downloading documents, or matching callback events.

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

Field	Type	Description
uuid	UUID	Created envelope UUID.

Step 5 Continue processing

After the request is processed, DocStudio creates the envelope from the selected template and sends it according to the template flow. The recipient mailboxes assigned in the XML become participants in the envelope, and the provided field values are saved to the matching fields.

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 XML as a JSON string in data.