Send your first envelope

This document explains how to send, track, and download your first envelope with DocStudio API.

Use the envelope UUID to retrieve the envelope, check its status, and download completed documents. For full contracts, response schemas, and status codes, use the linked API reference pages.

Before you start

Prepare the identifiers used by the template and envelope flow. Do not create role IDs, document IDs, or field names manually. Reuse values from the template structure.

You need:

• API token

• sender and recipient mailbox UUIDs

• existing template with its UUID and version

• role IDs, document IDs, and field names from the template

Read:

• Authentication and application tokens to get a token.

• Working with templates and reusable IDs to find template identifiers.

A basic envelope sending flow usually looks like this:

1. Get or create an API token.

2. Choose the template that will be used to create the envelope.

3. Read reusable identifiers from the template structure.

4. Find or prepare mailbox UUIDs for recipients.

5. Build the envelope XML.

6. Send the envelope.

7. Save the returned envelope UUID.

8. Retrieve the envelope and check its status.

9. Download the completed envelope archive if needed.

Step 1 Authenticate the request

DocStudio API requests require a token in the Authorization header. Use an application token for long-running integrations and a temporary authorization token only for testing or short-lived user sessions.

Authorization: Bearer {token}

Use the same token format in the send request and in follow-up requests, such as retrieving the envelope by UUID.

Step 2 Build the envelope XML

The envelope is sent as XML inside the JSON data field. The XML must reference the template UUID and template version, assign mailbox UUIDs to template roles, and send field values under the correct document IDs and field names.

<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  <flow>
    <roles>
      <role id="{roleId}" mailboxUuid="{recipientMailboxUuid}" />
    </roles>
  </flow>
  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Contract amount">1000</field>
    </document>
  </documents>
</envelope>

Escape reserved XML characters before putting the XML into the JSON request body. The data value must be a string, so line breaks and quotes must be valid for JSON.

Step 3 Send the envelope

Use this endpoint to create and send the envelope.

Method	Endpoint
POST	/api/v1/envelope/send

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:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": "<envelope templateUuid=\"{templateUuid}\" templateVersion=\"{templateVersion}\">...</envelope>"
}

Request body fields

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

Add metadata only when the envelope requires custom key-value data.

Response 201 Created:

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

Save the returned uuid. This is the envelope UUID used for follow-up requests, including retrieving the envelope, checking status, downloading documents, and reading audit trail data.

Step 4 Retrieve the envelope

Use the returned envelope UUID to retrieve the envelope and check its current status. Send the request in the context of the mailbox that was used to send the envelope.

Method	Endpoint
GET	/api/v1/mailbox/{mailboxUuid}?UUID={envelopeUuid}

Headers

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	Use application/json
mailboxUuid	Yes	UUID of the current mailbox

Path parameters

Parameter	Type	Required	Description
mailboxUuid	UUID	Yes	UUID of the mailbox used to access the envelope

Query parameters

Parameter	Type	Required	Description
UUID	UUID	Yes	UUID of the envelope returned by the send request

Request example

GET /api/v1/mailbox/{senderMailboxUuid}?UUID={envelopeUuid}
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {senderMailboxUuid}

The endpoint returns 200 OK with the matching envelope data. Check the status field before attempting to download the completed envelope documents.

Step 5 Download the completed archive

After the envelope is complete, download the archive if you need the final documents. Use the envelope UUID with the download endpoint.

Do not download the archive before the document files are ready. If the file is not ready yet, wait and retry according to the endpoint response and retry guidance.

Troubleshoot the first send request

If validation fails, check the template and mailbox first, then:

• Confirm the token can access the sender mailbox.

• Confirm that template UUID, version, role IDs, document IDs, and field names match.

• Confirm that XML is valid and field values follow template rules.

Related topics

• Authentication and application tokens

• Core concepts

• Working with templates and reusable IDs

• Send Envelope

• Check Envelope Status

• Error handling and API error codes