Draft Envelopes

This document contains endpoints for creating, updating, and deleting draft envelopes, including headers, request bodies, responses, and practical examples.

Drafts allow an integration to prepare envelope XML, assign recipients, store metadata, and save the result before starting the document workflow.

The endpoints on this page create, update, and delete draft envelopes. To create and send an envelope immediately, use Send Envelope instead.

Business goals

Draft Envelope endpoints support integrations that need to prepare an envelope over multiple operations instead of sending it immediately. They support the following business goals:

• Prepare envelopes before sending. Create an envelope and save it while its documents, recipients, fields, or metadata are still being prepared.

• Update business data. Replace the envelope XML or metadata when information changes before the envelope is sent.

• Separate preparation from delivery. Let one process create or update the envelope while another process validates and sends it.

• Remove unused drafts. Delete one or multiple draft envelopes that should no longer be completed or sent.

• Preserve a stable identifier. Save the returned envelope UUID and use it in subsequent update, delete, and send operations.

Endpoint summary

Method	Endpoint	Purpose	Successful response
POST	/api/v1/envelope	Create a draft envelope without sending it	201 Created
PUT	/api/v1/envelope	Update an existing draft envelope without sending it	200 OK
DELETE	/api/v1/envelope	Delete one or multiple draft envelopes	200 OK

Draft envelope structure and headers

All three endpoints require an API token and the current mailbox UUID. The Mailbox header identifies the mailbox in which the draft is created, updated, or deleted.

Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {mailboxUuid}

The create and update endpoints use JSON request bodies containing envelope XML and optional metadata. The update request also supports previously saved document signature data.

Field	Type	Create	Update	Description
uuid	UUID	Optional	Required	UUID assigned to or identifying the draft envelope
data	string	Required	Required	Envelope XML serialized as a JSON string
metadata	object	Optional	Optional	Custom string key-value pairs stored with the envelope
savedDocSignatures	array	Not used	Optional	Previously saved document signature data included in the update

When uuid is omitted from the create request, DocStudio generates an envelope UUID and returns it in the response. When the integration assigns the UUID itself, include it in the create request and continue using the same value in later operations.

The data field must contain valid envelope XML referencing an existing template and template version. Serialize the XML as a JSON string and escape it when required. Role IDs, recipient mailbox UUIDs, document IDs, and field names must correspond to the selected template version. See XML payloads for encoding guidance.

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

The metadata object stores business identifiers and other custom values separately from the envelope XML. Metadata can later be used to connect the envelope with records in a CRM, ERP, or another external system.

{
  "contractId": "CONTRACT-1042",
  "customerId": "CUSTOMER-77551",
  "source": "CRM"
}

Practical example: Create, update, and delete a draft envelope

A CRM integration prepares a sales agreement but must wait for final customer information before sending it. The integration creates a draft, saves its UUID, updates the draft when the missing information becomes available, and deletes it if the agreement is cancelled.

Create the draft envelope

Create the draft with its initial envelope XML and metadata. The request saves the envelope in the mailbox specified by the Mailbox header without sending notifications or starting the recipient workflow.

Node.js

const payload = {
  data: "{envelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM"
  }
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

console.log(body);

PHP

<?php

$payload = [
    "data" => "{envelopeXml}",
    "metadata" => [
        "contractId" => "CONTRACT-1042",
        "customerId" => "CUSTOMER-77551",
        "source" => "CRM"
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

echo $body;

Python

import requests

payload = {
    "data": "{envelopeXml}",
    "metadata": {
        "contractId": "CONTRACT-1042",
        "customerId": "CUSTOMER-77551",
        "source": "CRM",
    },
}

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
    },
    json=payload,
    timeout=30,
)

response.raise_for_status()
print(response.json())

Ruby

require "json"
require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/envelope"
)

payload = {
  data: "{envelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM"
  }
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]any{
		"data": "{envelopeXml}",
		"metadata": map[string]string{
			"contractId": "CONTRACT-1042",
			"customerId": "CUSTOMER-77551",
			"source":     "CRM",
		},
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Mailbox",
		"{mailboxUuid}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	fmt.Println(string(body))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "data": "{envelopeXml}",
          "metadata": {
            "contractId": "CONTRACT-1042",
            "customerId": "CUSTOMER-77551",
            "source": "CRM"
          }
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .POST(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " +
          response.statusCode() +
          "\n" +
          response.body()
      );
    }

    System.out.println(response.body());
  }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();

var payload = new
{
    data = "{envelopeXml}",
    metadata = new
    {
        contractId = "CONTRACT-1042",
        customerId = "CUSTOMER-77551",
        source = "CRM"
    }
};

using var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://api.docstudio.com/api/v1/envelope"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

request.Headers.Add(
    "Mailbox",
    "{mailboxUuid}"
);

request.Content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

using var response =
    await client.SendAsync(request);

var body =
    await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: " +
        $"{(int)response.StatusCode}\n{body}"
    );
}

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": "{envelopeXml}",
    "metadata": {
      "contractId": "CONTRACT-1042",
      "customerId": "CUSTOMER-77551",
      "source": "CRM"
    }
  }'

A successful request returns 201 Created and the draft envelope UUID. Save this value because it identifies the draft in all subsequent operations.

{
  "uuid": "{envelopeUuid}"
}

If the integration needs to assign the UUID before creating the draft, include it in the request. DocStudio then uses the supplied value instead of generating a new one.

{
  "uuid": "{envelopeUuid}",
  "data": "{envelopeXml}",
  "metadata": {
    "contractId": "CONTRACT-1042",
    "source": "CRM"
  }
}

Update the draft envelope

Use PUT /api/v1/envelope after changing recipients, field values, the subject, the message, or other information stored in the envelope XML. Include the UUID returned by the create request and send the complete updated XML.

Node.js

const payload = {
  uuid: "{envelopeUuid}",
  data: "{updatedEnvelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM",
    draftState: "READY"
  }
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$payload = [
    "uuid" => "{envelopeUuid}",
    "data" => "{updatedEnvelopeXml}",
    "metadata" => [
        "contractId" => "CONTRACT-1042",
        "customerId" => "CUSTOMER-77551",
        "source" => "CRM",
        "draftState" => "READY"
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope"
);

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

payload = {
    "uuid": "{envelopeUuid}",
    "data": "{updatedEnvelopeXml}",
    "metadata": {
        "contractId": "CONTRACT-1042",
        "customerId": "CUSTOMER-77551",
        "source": "CRM",
        "draftState": "READY",
    },
}

response = requests.put(
    "https://api.docstudio.com/api/v1/envelope",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
    },
    json=payload,
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "json"
require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/envelope"
)

payload = {
  uuid: "{envelopeUuid}",
  data: "{updatedEnvelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM",
    draftState: "READY"
  }
}

request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]any{
		"uuid": "{envelopeUuid}",
		"data": "{updatedEnvelopeXml}",
		"metadata": map[string]string{
			"contractId":  "CONTRACT-1042",
			"customerId":  "CUSTOMER-77551",
			"source":      "CRM",
			"draftState":  "READY",
		},
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPut,
		"https://api.docstudio.com/api/v1/envelope",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Mailbox",
		"{mailboxUuid}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "uuid": "{envelopeUuid}",
          "data": "{updatedEnvelopeXml}",
          "metadata": {
            "contractId": "CONTRACT-1042",
            "customerId": "CUSTOMER-77551",
            "source": "CRM",
            "draftState": "READY"
          }
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .PUT(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " +
          response.statusCode() +
          "\n" +
          response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();

var payload = new
{
    uuid = "{envelopeUuid}",
    data = "{updatedEnvelopeXml}",
    metadata = new
    {
        contractId = "CONTRACT-1042",
        customerId = "CUSTOMER-77551",
        source = "CRM",
        draftState = "READY"
    }
};

using var request = new HttpRequestMessage(
    HttpMethod.Put,
    "https://api.docstudio.com/api/v1/envelope"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

request.Headers.Add(
    "Mailbox",
    "{mailboxUuid}"
);

request.Content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

using var response =
    await client.SendAsync(request);

var body =
    await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: " +
        $"{(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request PUT \
  --url 'https://api.docstudio.com/api/v1/envelope' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --data '{
    "uuid": "{envelopeUuid}",
    "data": "{updatedEnvelopeXml}",
    "metadata": {
      "contractId": "CONTRACT-1042",
      "customerId": "CUSTOMER-77551",
      "source": "CRM",
      "draftState": "READY"
    }
  }'

A successful update returns 200 OK. The operation saves the new draft state but does not send the envelope or notify its recipients.

Use the same Mailbox header that provides access to the draft. Include the draft UUID and the updated envelope data in the request. The request must contain the complete envelope state that needs to remain after the update.

Include saved document signatures

The update request can include savedDocSignatures when saved signature data must be retained with the draft. Use it when updating an envelope that already contains signatures saved before it is sent. Each entry identifies the document, signature field, signature source, encoded signature data, and optional certificate data.

{
  "uuid": "{envelopeUuid}",
  "data": "{updatedEnvelopeXml}",
  "metadata": {
    "contractId": "CONTRACT-1042"
  },
  "savedDocSignatures": [
    {
      "documentId": "{documentId}",
      "signatureName": "{signatureName}",
      "signatures": [
        {
          "source": "binary",
          "data": "{base64SignatureData}",
          "certificate": "{base64CertificateData}"
        }
      ]
    }
  ]
}

The signatures array must contain at least one signature entry. Omit savedDocSignatures when the draft does not contain saved document signatures.

Delete draft envelopes

Delete drafts that should no longer be completed or sent. The request accepts an array, so the integration can delete one or multiple drafts in the same operation.

Node.js

const payload = {
  uuids: [
    "{envelopeUuid}"
  ]
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$payload = [
    "uuids" => [
        "{envelopeUuid}"
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope"
);

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

response = requests.delete(
    "https://api.docstudio.com/api/v1/envelope",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
    },
    json={
        "uuids": [
            "{envelopeUuid}",
        ],
    },
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "json"
require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/envelope"
)

payload = {
  uuids: [
    "{envelopeUuid}"
  ]
}

request = Net::HTTP::Delete.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string][]string{
		"uuids": {
			"{envelopeUuid}",
		},
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodDelete,
		"https://api.docstudio.com/api/v1/envelope",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Mailbox",
		"{mailboxUuid}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "uuids": [
            "{envelopeUuid}"
          ]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .method(
            "DELETE",
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " +
          response.statusCode() +
          "\n" +
          response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();

var payload = new
{
    uuids = new[]
    {
        "{envelopeUuid}"
    }
};

using var request = new HttpRequestMessage(
    HttpMethod.Delete,
    "https://api.docstudio.com/api/v1/envelope"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

request.Headers.Add(
    "Mailbox",
    "{mailboxUuid}"
);

request.Content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

using var response =
    await client.SendAsync(request);

var body =
    await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: " +
        $"{(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request DELETE \
  --url 'https://api.docstudio.com/api/v1/envelope' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --data '{
    "uuids": [
      "{envelopeUuid}"
    ]
  }'

Review every UUID before sending a delete request. The operation can delete multiple drafts in one request.

To delete multiple drafts, include each envelope UUID in the same array. All specified envelopes must be accessible through the mailbox context used in the request.

{
  "uuids": [
    "{firstEnvelopeUuid}",
    "{secondEnvelopeUuid}",
    "{thirdEnvelopeUuid}"
  ]
}

A successful request returns 200 OK. This endpoint is intended for draft envelopes that have not entered the recipient workflow.

Send the completed draft

When the draft is ready, send it through POST /api/v1/envelope/send. Include the saved envelope UUID and the final envelope XML so DocStudio can start the configured workflow.

Node.js

const payload = {
  uuid: "{envelopeUuid}",
  data: "{finalEnvelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM"
  }
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/send",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const body = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed: ${response.status}\n${body}`
  );
}

if (body) {
  console.log(body);
}

PHP

<?php

$payload = [
    "uuid" => "{envelopeUuid}",
    "data" => "{finalEnvelopeXml}",
    "metadata" => [
        "contractId" => "CONTRACT-1042",
        "customerId" => "CUSTOMER-77551",
        "source" => "CRM"
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/send"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException(
        "Request failed: {$status}\n{$body}"
    );
}

if ($body !== "") {
    echo $body;
}

Python

import requests

payload = {
    "uuid": "{envelopeUuid}",
    "data": "{finalEnvelopeXml}",
    "metadata": {
        "contractId": "CONTRACT-1042",
        "customerId": "CUSTOMER-77551",
        "source": "CRM",
    },
}

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/send",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
    },
    json=payload,
    timeout=30,
)

response.raise_for_status()

if response.text:
    print(response.text)

Ruby

require "json"
require "net/http"
require "uri"

uri = URI(
  "https://api.docstudio.com/api/v1/envelope/send"
)

payload = {
  uuid: "{envelopeUuid}",
  data: "{finalEnvelopeXml}",
  metadata: {
    contractId: "CONTRACT-1042",
    customerId: "CUSTOMER-77551",
    source: "CRM"
  }
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request.body = JSON.generate(payload)

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true
) do |http|
  http.request(request)
end

unless response.is_a?(Net::HTTPSuccess)
  raise "Request failed: #{response.code}\n#{response.body}"
end

puts response.body unless response.body.empty?

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]any{
		"uuid": "{envelopeUuid}",
		"data": "{finalEnvelopeXml}",
		"metadata": map[string]string{
			"contractId": "CONTRACT-1042",
			"customerId": "CUSTOMER-77551",
			"source":     "CRM",
		},
	}

	requestBody, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/send",
		bytes.NewReader(requestBody),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Mailbox",
		"{mailboxUuid}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)

	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	body, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"Request failed: %s\n%s",
			response.Status,
			body,
		))
	}

	if len(body) > 0 {
		fmt.Println(string(body))
	}
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "uuid": "{envelopeUuid}",
          "data": "{finalEnvelopeXml}",
          "metadata": {
            "contractId": "CONTRACT-1042",
            "customerId": "CUSTOMER-77551",
            "source": "CRM"
          }
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/send"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .POST(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

    HttpResponse<String> response =
        HttpClient.newHttpClient().send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

    if (response.statusCode() < 200 ||
        response.statusCode() >= 300) {
      throw new RuntimeException(
          "Request failed: " +
          response.statusCode() +
          "\n" +
          response.body()
      );
    }

    if (!response.body().isEmpty()) {
      System.out.println(response.body());
    }
  }
}

.NET

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();

var payload = new
{
    uuid = "{envelopeUuid}",
    data = "{finalEnvelopeXml}",
    metadata = new
    {
        contractId = "CONTRACT-1042",
        customerId = "CUSTOMER-77551",
        source = "CRM"
    }
};

using var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://api.docstudio.com/api/v1/envelope/send"
);

request.Headers.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

request.Headers.Add(
    "Mailbox",
    "{mailboxUuid}"
);

request.Content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

using var response =
    await client.SendAsync(request);

var body =
    await response.Content.ReadAsStringAsync();

if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Request failed: " +
        $"{(int)response.StatusCode}\n{body}"
    );
}

if (!string.IsNullOrEmpty(body))
{
    Console.WriteLine(body);
}

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope/send' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --data '{
    "uuid": "{envelopeUuid}",
    "data": "{finalEnvelopeXml}",
    "metadata": {
      "contractId": "CONTRACT-1042",
      "customerId": "CUSTOMER-77551",
      "source": "CRM"
    }
  }'

A successful request returns 201 Created. The envelope is no longer only a draft because DocStudio starts the recipient workflow defined by its template and envelope XML.

Troubleshooting

Problem	What to check
The request XML is rejected	Verify that the XML references the selected template version and contains valid roles, recipients, documents, and fields
The draft is unavailable	Confirm that the Mailbox header grants access to the envelope UUID
An update lost expected values	Retrieve the current draft before using PUT, then submit the complete envelope state

Related topics

• Send Envelope

• Envelope Structure

• Templates and reusable IDs

• Envelope metadata

• Upload Attachments

• Check Envelope Status

• Error handling and API error codes