Send Envelope

This document contains details for the /api/v1/envelope/send endpoint, including headers, request parameters, response fields, and status codes.

Endpoint

Method	Endpoint
POST	/api/v1/envelope/send

Headers

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	application/json
Mailbox	Yes	UUID of the sender mailbox

Use a token with access to the sender mailbox.

Request

Field	Type	Required	Description
uuid	UUID	No	Predefined envelope UUID
data	string	Yes	Envelope XML serialized as a JSON string
metadata	object	No	Custom envelope metadata

Envelope XML

Use identifiers from the same template version.

Envelope value	Source
envelope/@templateUuid	Template UUID
envelope/@templateVersion	Template version UUID
role/@id	Role ID from the template flow
role/@mailboxUuid	Recipient mailbox UUID
document/@id	Document ID from the selected template version
field/@name	Exact field name from the selected template version

Example envelope XML:

<envelope
  templateUuid="{templateUuid}"
  templateVersion="{templateVersion}"
>
  <info>
    <subject>Sales agreement</subject>
    <message>Please review and complete the agreement.</message>
  </info>

  <flow>
    <roles>
      <role
        id="{roleId}"
        mailboxUuid="{recipientMailboxUuid}"
      />
    </roles>
  </flow>

  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Contract amount">1250.50</field>
    </document>
  </documents>
</envelope>

Request example

POST /api/v1/envelope/send
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {senderMailboxUuid}

{
  "data": "{envelopeXml}"
}

Optional request fields

uuid

Set uuid when the integration assigns the envelope UUID.

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

metadata

Set metadata to store custom envelope data.

{
  "data": "{envelopeXml}",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "priority": true
  }
}

Response

The endpoint returns 201 Created with the created envelope UUID.

{
  "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a"
}

Field	Type	Description
uuid	UUID	UUID of the created envelope

Status codes

Code	Description
201	Envelope created and sent successfully
400	Invalid request headers, JSON body, envelope XML, or reusable identifiers
401	Missing, invalid, or expired authorization token
403	No permission to send envelopes from the specified mailbox

Related topics

• Send your first envelope

• XML payloads

• Templates and reusable IDs

• Envelope fields

• Envelope metadata

• Upload Attachments

• Fill Envelope

• Check Envelope Status

• Error handling and API error codes