Send Envelope with Metadata

This document explains how to store and use envelope metadata through the API.

Scenario

Send an envelope from a template and attach metadata for an external process.

Step 1 Prepare template and metadata values

Method	Endpoint
POST	/api/v1/envelope/send

Prepare the template values and metadata before building the request.

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

• metadata keys and values

Metadata rules

Rule	Value
Key length	1–32 characters
Value length	0–128 characters
Supported value types	string, boolean, null

{
  "customerId": "C-1024",
  "crmRecordId": "CRM-77551",
  "source": "crm",
  "priority": true,
  "externalReference": null
}

Step 2 Build envelope XML

Build the envelope XML with template, role, document, and field values.

<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"
      />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="customer_name">ACME Ltd</field>
      <field name="contract_amount">1250.50</field>
    </document>
  </documents>
</envelope>

Pass metadata in the metadata JSON object. Do not add it to the XML.

Step 3 Send the request

Use these headers:

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

Send the envelope XML in data and metadata in metadata.

{
  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\">\n  <info>\n    <subject>Sales agreement for ACME Ltd</subject>\n    <message>Please review and complete the agreement.</message>\n  </info>\n  <flow>\n    <roles>\n      <role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\" />\n    </roles>\n  </flow>\n  <documents>\n    <document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\">\n      <field name=\"customer_name\">ACME Ltd</field>\n      <field name=\"contract_amount\">1250.50</field>\n    </document>\n  </documents>\n</envelope>",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "source": "crm",
    "priority": true
  }
}

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

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\">\n  <info>\n    <subject>Sales agreement for ACME Ltd</subject>\n    <message>Please review and complete the agreement.</message>\n  </info>\n  <flow>\n    <roles>\n      <role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\" />\n    </roles>\n  </flow>\n  <documents>\n    <document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\">\n      <field name=\"customer_name\">ACME Ltd</field>\n      <field name=\"contract_amount\">1250.50</field>\n    </document>\n  </documents>\n</envelope>",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "source": "crm",
    "priority": true
  }
}

Step 4 Save the envelope UUID

The endpoint returns 201 Created. Save the envelope UUID.

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

Field	Type	Description
uuid	UUID	Created envelope UUID

Step 5 Manage metadata

Update metadata

Use this endpoint to add or change metadata.

Method	Endpoint
PUT	/api/v1/envelope/{id}/metadata

Use these headers:

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	Use application/json
Mailbox	Yes	Current mailbox UUID

Path parameters:

Parameter	Type	Required	Description
id	UUID	Yes	Envelope ID

{
  "crmRecordId": "CRM-77551",
  "processingStatus": "synced",
  "priority": true
}

The request adds new keys and overwrites existing values. The endpoint returns 200 OK.

Read metadata

Read envelope.metadata.

{
  "envelope": {
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "WAITING",
    "metadata": {
      "customerId": "C-1024",
      "crmRecordId": "CRM-77551",
      "source": "crm",
      "priority": true
    }
  }
}

Display metadata

Add this element to the template info section:

<metadata show="true" />

Display metadata only when the template includes this element and metadata has a value.

Continue processing

Use the envelope UUID to check the envelope status, process callbacks, or download the completed archive.

Keep document values in fields and external references in metadata.

• Include the Authorization header

• Use the sender mailbox UUID in Mailbox

• Confirm token access to the sender mailbox

• Send valid envelope XML in data

• Send a valid JSON object in metadata

• Use keys that are 1–32 characters long

• Use values that are 0–128 characters long

• Use supported metadata value types

• Do not include secrets or large data blocks

• Add <metadata show="true" /> to display metadata