Envelope Search

This document contains endpoints for searching envelopes and workflows, retrieving mailbox filters, creating reports, and configuring envelope list columns.

Envelope Search endpoints retrieve envelopes available in a specific mailbox and filter them by status, scope, template, dates, recipients, metadata, or searchable field values.

The controller also provides operations for editorial review and approval searches, report creation, template-role discovery, mailbox-folder retrieval, and envelope-list column configuration.

Business goals

Envelope Search endpoints support the following business goals:

• Find envelopes for operational processing

• Monitor received, sent, draft, shared, archived, deleted, expiring, or waiting envelopes

• Find envelopes associated with specific templates, senders, recipients, labels, forms, or metadata

• Search values stored in searchable envelope fields

• Retrieve envelopes involved in editorial review or approval workflows

• Generate reports for selected envelopes or filtered search results

• Retrieve folders available in a mailbox

• Configure additional columns displayed in envelope lists

Endpoint summary

Search, review, approval, and reporting

Method	Endpoint	Purpose
POST	/api/v1/envelope/search	Search envelopes available in the current mailbox
POST	/api/v1/envelope/search/roles	Retrieve template roles for envelope search
POST	/api/v1/envelope/search-reviews	Search envelopes associated with editorial reviews
POST	/api/v1/envelope/search-approvals	Search envelopes associated with approval workflows
POST	/api/v1/envelope/report	Request an envelope report
POST	/api/v1/envelope/mailbox-folders	Retrieve available mailbox folders
POST	/api/v1/envelope/fields	Retrieve searchable envelope fields

Displayed columns

Method	Endpoint	Purpose
POST	/api/v1/envelope/column	Add an envelope field as a displayed column
PUT	/api/v1/envelope/column/{id}	Update a displayed column
DELETE	/api/v1/envelope/column	Delete displayed columns
POST	/api/v1/envelope/column-reset	Reset envelope column settings

Request context

All operations require an API token and the current mailbox UUID. The Mailbox header determines which envelopes, workflows, search fields, folders, reports, and column settings are available to the request.

Header	Required	Description
Authorization	Yes	Bearer authorization token
Mailbox	Yes	Current mailbox UUID
Content-Type	Conditional	application/json for requests with a JSON body

POST /api/v1/envelope/column-reset does not have a request body, so its request does not require Content-Type. All other operations described on this page accept a JSON request body.

The mailbox UUID is represented as {mailboxUuid} in request examples. Envelope search responses use the property name mailboxUUID, while sender, initiator, and template-related response objects can use mailboxUuid; integrations must preserve the capitalization defined by each response schema.

Pagination

The following query parameters apply to POST /api/v1/envelope/search, POST /api/v1/envelope/search-reviews, and POST /api/v1/envelope/search-approvals. Use them to control which page is returned or request only envelope identifiers.

Parameter	Type	Required	Default	Description
offset	integer	No	0	Number of envelopes to skip
limit	integer	No	25	Maximum number of envelopes to return
uuidOnly	boolean	No	Not set	Retrieve only envelope UUIDs

Search envelopes

Use POST /api/v1/envelope/search to retrieve envelopes available in the current mailbox. Send an empty JSON object to search without body filters, or provide one or more properties to narrow the results.

Request filters

Property	Type	Description
label	array of strings	Envelope labels
scope	array of strings	Envelope locations
status	array of strings	Envelope statuses
subject	string	Envelope subject
createDateFrom	date-time	Earliest envelope creation date
createDateTo	date-time	Latest envelope creation date
receiveDateFrom	date-time	Earliest envelope receipt date
receiveDateTo	date-time	Latest envelope receipt date
expireDateFrom	date-time	Earliest envelope expiration date
expireDateTo	date-time	Latest envelope expiration date
sendDateFrom	date-time	Earliest envelope sending date
sendDateTo	date-time	Latest envelope sending date
archived	boolean	Archived or non-archived envelopes
deleted	boolean	Deleted or non-deleted envelopes
template	array of UUIDs	Template UUIDs
activeRole	array of strings	Active template roles
sender	array of strings	Envelope senders
recipient	array of strings	Envelope recipients
sortField	string	Field used for sorting, createdAt by default
sort	string	Sort order
searchFields	array of objects	Searchable envelope field values
form	array of UUIDs	Form UUIDs
metadata	object	Metadata key-value properties
templateVersion	array of UUIDs	Template version UUIDs

Supported scope values:

• inbox — received envelopes

• outbox — sent envelopes

• draft — draft envelopes

• shared — shared envelopes

Supported status values:

• DRAFT

• SENT

• WAITING

• COMPLETED

• CANCELLED

• EXPIRED

• ON_APPROVAL

Supported sort values:

• desc — descending

• asc — ascending

If sortField is omitted, the API uses createdAt. Use asc or desc in sort to control the order.

Retrieve envelopes without body filters

This request returns the first 25 envelopes available in the current mailbox. Change offset and limit to retrieve another page or modify its maximum size.

Node.js

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

const body = await response.text();

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

console.log(body);

PHP

<?php

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode(
        new stdClass()
    ),
    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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search",
    params={
        "offset": 0,
        "limit": 25,
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={},
    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/search"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

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

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"
	"fmt"
	"io"
	"net/http"
)

func main() {
	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25",
		bytes.NewBufferString("{}"),
	)
	if err != nil {
		panic(err)
	}

	request.Header.Set(
		"Authorization",
		"Bearer {token}",
	)
	request.Header.Set(
		"Mailbox",
		"{mailboxUuid}",
	)
	request.Header.Set(
		"Content-Type",
		"application/json",
	)
	request.Header.Set(
		"Accept",
		"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 {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search" +
            "?offset=0&limit=25"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "application/json"
        )
        .POST(
            HttpRequest.BodyPublishers.ofString("{}")
        )
        .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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search" +
    "?offset=0&limit=25",
    new { }
);

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/search?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{}'

Retrieve only envelope UUIDs

Set uuidOnly=true when the integration only needs identifiers for subsequent processing. The API retrieves only the UUID of each envelope matching the supplied filters.

Node.js

const payload = {
  scope: ["outbox"],
  status: ["COMPLETED"]
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=100&uuidOnly=true",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => ["outbox"],
    "status" => ["COMPLETED"]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=100&uuidOnly=true"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search",
    params={
        "offset": 0,
        "limit": 100,
        "uuidOnly": "true",
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": ["outbox"],
        "status": ["COMPLETED"],
    },
    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/search"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 100,
  uuidOnly: true
)

payload = {
  scope: ["outbox"],
  status: ["COMPLETED"]
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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][]string{
		"scope":  {"outbox"},
		"status": {"COMPLETED"},
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=100&uuidOnly=true",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": ["outbox"],
          "status": ["COMPLETED"]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search" +
            "?offset=0&limit=100&uuidOnly=true"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = new[] { "outbox" },
    status = new[] { "COMPLETED" }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search" +
    "?offset=0&limit=100&uuidOnly=true",
    payload
);

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/search?offset=0&limit=100&uuidOnly=true' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": ["outbox"],
    "status": ["COMPLETED"]
  }'

Practical example: Find completed envelopes for a customer

A CRM integration can find completed sales agreements created from a specific template for one customer. The request filters the mailbox outbox by status, template UUID, creation date, and the customer identifier stored in envelope metadata.

Node.js

const payload = {
  scope: ["outbox"],
  status: ["COMPLETED"],
  createDateFrom: "2026-09-01T00:00:00Z",
  createDateTo: "2026-09-30T23:59:59Z",
  template: ["{templateUuid}"],
  metadata: {
    customerId: "C-1024",
    documentType: "sales-agreement"
  },
  sortField: "createdAt",
  sort: "desc"
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => ["outbox"],
    "status" => ["COMPLETED"],
    "createDateFrom" => "2026-09-01T00:00:00Z",
    "createDateTo" => "2026-09-30T23:59:59Z",
    "template" => ["{templateUuid}"],
    "metadata" => [
        "customerId" => "C-1024",
        "documentType" => "sales-agreement"
    ],
    "sortField" => "createdAt",
    "sort" => "desc"
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search",
    params={
        "offset": 0,
        "limit": 25,
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": ["outbox"],
        "status": ["COMPLETED"],
        "createDateFrom": "2026-09-01T00:00:00Z",
        "createDateTo": "2026-09-30T23:59:59Z",
        "template": ["{templateUuid}"],
        "metadata": {
            "customerId": "C-1024",
            "documentType": "sales-agreement",
        },
        "sortField": "createdAt",
        "sort": "desc",
    },
    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/search"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

payload = {
  scope: ["outbox"],
  status: ["COMPLETED"],
  createDateFrom: "2026-09-01T00:00:00Z",
  createDateTo: "2026-09-30T23:59:59Z",
  template: ["{templateUuid}"],
  metadata: {
    customerId: "C-1024",
    documentType: "sales-agreement"
  },
  sortField: "createdAt",
  sort: "desc"
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"scope":          []string{"outbox"},
		"status":         []string{"COMPLETED"},
		"createDateFrom": "2026-09-01T00:00:00Z",
		"createDateTo":   "2026-09-30T23:59:59Z",
		"template":       []string{"{templateUuid}"},
		"metadata": map[string]string{
			"customerId":   "C-1024",
			"documentType": "sales-agreement",
		},
		"sortField": "createdAt",
		"sort":      "desc",
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": ["outbox"],
          "status": ["COMPLETED"],
          "createDateFrom": "2026-09-01T00:00:00Z",
          "createDateTo": "2026-09-30T23:59:59Z",
          "template": ["{templateUuid}"],
          "metadata": {
            "customerId": "C-1024",
            "documentType": "sales-agreement"
          },
          "sortField": "createdAt",
          "sort": "desc"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search" +
            "?offset=0&limit=25"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = new[] { "outbox" },
    status = new[] { "COMPLETED" },
    createDateFrom = "2026-09-01T00:00:00Z",
    createDateTo = "2026-09-30T23:59:59Z",
    template = new[] { "{templateUuid}" },
    metadata = new
    {
        customerId = "C-1024",
        documentType = "sales-agreement"
    },
    sortField = "createdAt",
    sort = "desc"
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search" +
    "?offset=0&limit=25",
    payload
);

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/search?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": ["outbox"],
    "status": ["COMPLETED"],
    "createDateFrom": "2026-09-01T00:00:00Z",
    "createDateTo": "2026-09-30T23:59:59Z",
    "template": ["{templateUuid}"],
    "metadata": {
      "customerId": "C-1024",
      "documentType": "sales-agreement"
    },
    "sortField": "createdAt",
    "sort": "desc"
  }'

The metadata object accepts one or more string key-value properties. Use metadata names and values stored in the target envelopes.

A successful request returns 200 OK with a paginated collection. Save the returned envelopeUuid values for status checks, downloads, reports, or other follow-up operations.

{
  "totalElements": 1,
  "sizeRequested": 25,
  "numberOfElements": 1,
  "data": [
    {
      "envelopeUuid": "{envelopeUuid}",
      "subject": "Sales agreement",
      "message": "Please review and sign",
      "archived": false,
      "deleted": false,
      "shared": false,
      "sentByMe": true,
      "createdAt": "2026-09-12T10:15:00Z",
      "receivedAt": "2026-09-12T10:16:00Z",
      "sentAt": "2026-09-12T10:17:00Z",
      "seenAt": "2026-09-12T10:20:00Z",
      "expiredAfter": "2026-10-12T10:17:00Z",
      "sharingForbidden": false,
      "status": "COMPLETED",
      "accountUUID": "{accountUuid}",
      "mailboxUUID": "{mailboxUuid}",
      "mailboxName": "Sales",
      "total": 2,
      "completed": 2,
      "labels": [
        "{labelUuid}"
      ],
      "templateUuid": "{templateUuid}",
      "templateVersion": "{templateVersionUuid}",
      "templateName": "Sales agreement",
      "invitationCode": "string",
      "chainUuid": "{chainUuid}",
      "chainedByMe": false,
      "extraFields": [],
      "formId": "{formUuid}"
    }
  ],
  "searchFields": [],
  "columns": [],
  "senders": [],
  "templates": [
    {
      "templateUuid": "{templateUuid}",
      "templateName": "Sales agreement"
    }
  ],
  "sendersInfo": "string",
  "templatesInfo": "string"
}

The response contains the envelope page together with values that can be used to build search and display controls. The following collections describe the returned envelopes, searchable fields, configured columns, senders, and templates.

Property	Description
data	Envelopes returned for the current page
searchFields	Searchable envelope fields available in the results
columns	Current envelope-list column configuration
senders	Senders represented in the results
templates	Templates represented in the results
sendersInfo	Additional sender information
templatesInfo	Additional template information

Search by envelope field value

The searchFields property searches values stored in template fields configured as searchable. First use POST /api/v1/envelope/fields to retrieve available field names and types, then use the returned values in POST /api/v1/envelope/search.

Each searchFields object supports the following properties:

Property	Type	Required	Description
name	string	Yes	Field name, minimum one character
value	string	No	String field value
number	number	No	Numeric field value
from	date-time	No	Beginning of a date-time range
to	date-time	No	End of a date-time range
checked	boolean	No	Checkbox value
type	string	No	Searchable field type

Use the value property corresponding to the field type. For example, use value for text fields, number for numeric fields, from and to for date ranges, and checked for checkbox fields.

Find searchable fields

The required name query parameter contains the field-name term. The request body uses the standard envelope filters to limit the envelopes from which searchable fields are retrieved.

Node.js

const payload = {
  scope: ["inbox"],
  status: ["COMPLETED"]
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/fields?name=customer",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => ["inbox"],
    "status" => ["COMPLETED"]
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/fields",
    params={
        "name": "customer",
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": ["inbox"],
        "status": ["COMPLETED"],
    },
    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/fields"
)

uri.query = URI.encode_www_form(
  name: "customer"
)

payload = {
  scope: ["inbox"],
  status: ["COMPLETED"]
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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][]string{
		"scope":  {"inbox"},
		"status": {"COMPLETED"},
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/fields?name=customer",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": ["inbox"],
          "status": ["COMPLETED"]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/fields" +
            "?name=customer"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = new[] { "inbox" },
    status = new[] { "COMPLETED" }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/fields" +
    "?name=customer",
    payload
);

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/fields?name=customer' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": ["inbox"],
    "status": ["COMPLETED"]
  }'

A successful request returns 200 OK with the matching field names and types. The response can contain multiple searchable fields.

[
  {
    "name": "customer_name",
    "type": "text"
  },
  {
    "name": "contract_value",
    "type": "number"
  },
  {
    "name": "contract_date",
    "type": "datetime"
  },
  {
    "name": "approved",
    "type": "checkbox"
  }
]

Search by the returned field

Use the exact returned field name and type in searchFields. Supply the search value through the property corresponding to that type.

Node.js

const payload = {
  scope: ["inbox"],
  status: ["COMPLETED"],
  searchFields: [
    {
      name: "customer_name",
      value: "Acme",
      type: "text"
    },
    {
      name: "contract_value",
      number: 25000,
      type: "number"
    },
    {
      name: "approved",
      checked: true,
      type: "checkbox"
    }
  ]
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => ["inbox"],
    "status" => ["COMPLETED"],
    "searchFields" => [
        [
            "name" => "customer_name",
            "value" => "Acme",
            "type" => "text"
        ],
        [
            "name" => "contract_value",
            "number" => 25000,
            "type" => "number"
        ],
        [
            "name" => "approved",
            "checked" => true,
            "type" => "checkbox"
        ]
    ]
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search",
    params={
        "offset": 0,
        "limit": 25,
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": ["inbox"],
        "status": ["COMPLETED"],
        "searchFields": [
            {
                "name": "customer_name",
                "value": "Acme",
                "type": "text",
            },
            {
                "name": "contract_value",
                "number": 25000,
                "type": "number",
            },
            {
                "name": "approved",
                "checked": True,
                "type": "checkbox",
            },
        ],
    },
    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/search"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

payload = {
  scope: ["inbox"],
  status: ["COMPLETED"],
  searchFields: [
    {
      name: "customer_name",
      value: "Acme",
      type: "text"
    },
    {
      name: "contract_value",
      number: 25000,
      type: "number"
    },
    {
      name: "approved",
      checked: true,
      type: "checkbox"
    }
  ]
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"scope":  []string{"inbox"},
		"status": []string{"COMPLETED"},
		"searchFields": []map[string]any{
			{
				"name":  "customer_name",
				"value": "Acme",
				"type":  "text",
			},
			{
				"name":   "contract_value",
				"number": 25000,
				"type":   "number",
			},
			{
				"name":    "approved",
				"checked": true,
				"type":    "checkbox",
			},
		},
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search?offset=0&limit=25",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": ["inbox"],
          "status": ["COMPLETED"],
          "searchFields": [
            {
              "name": "customer_name",
              "value": "Acme",
              "type": "text"
            },
            {
              "name": "contract_value",
              "number": 25000,
              "type": "number"
            },
            {
              "name": "approved",
              "checked": true,
              "type": "checkbox"
            }
          ]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search" +
            "?offset=0&limit=25"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = new[] { "inbox" },
    status = new[] { "COMPLETED" },
    searchFields = new object[]
    {
        new
        {
            name = "customer_name",
            value = "Acme",
            type = "text"
        },
        new
        {
            name = "contract_value",
            number = 25000,
            type = "number"
        },
        new
        {
            name = "approved",
            checked = true,
            type = "checkbox"
        }
    }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search" +
    "?offset=0&limit=25",
    payload
);

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/search?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": ["inbox"],
    "status": ["COMPLETED"],
    "searchFields": [
      {
        "name": "customer_name",
        "value": "Acme",
        "type": "text"
      },
      {
        "name": "contract_value",
        "number": 25000,
        "type": "number"
      },
      {
        "name": "approved",
        "checked": true,
        "type": "checkbox"
      }
    ]
  }'

Add from and to to search a date-time range:

{
  "searchFields": [
    {
      "name": "contract_date",
      "from": "2026-09-01T00:00:00Z",
      "to": "2026-09-30T23:59:59Z",
      "type": "datetime"
    }
  ]
}

Retrieve template roles for filtering

Use POST /api/v1/envelope/search/roles to retrieve role values from selected templates. The returned role values can then be used in the activeRole property of an envelope search request.

Node.js

const payload = [
  "{templateUuid}",
  "{anotherTemplateUuid}"
];

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search/roles",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "{templateUuid}",
    "{anotherTemplateUuid}"
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search/roles",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json=[
        "{templateUuid}",
        "{anotherTemplateUuid}",
    ],
    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/search/roles"
)

payload = [
  "{templateUuid}",
  "{anotherTemplateUuid}"
]

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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 := []string{
		"{templateUuid}",
		"{anotherTemplateUuid}",
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search/roles",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        [
          "{templateUuid}",
          "{anotherTemplateUuid}"
        ]
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search/roles"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new[]
{
    "{templateUuid}",
    "{anotherTemplateUuid}"
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search/roles",
    payload
);

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/search/roles' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    "{templateUuid}",
    "{anotherTemplateUuid}"
  ]'

A successful request returns 200 OK with the roles found in the selected templates. Use the returned role names without changing their capitalization.

The following filter finds envelopes in which Signer is currently active. It also limits the results to the template from which the role was retrieved.

Search envelopes for editorial review

Use POST /api/v1/envelope/search-reviews to retrieve envelopes associated with editorial review workflows. The request can filter reviews by scope, status, template, initiator, participant, receipt date, or subject.

Request filters

Property	Type	Description
scope	array of strings	Editorial review scopes
status	array of strings	Editorial review statuses
subject	string	Envelope subject
receiveDateFrom	date-time	Earliest envelope receipt date
receiveDateTo	date-time	Latest envelope receipt date
template	array of UUIDs	Template UUIDs
initiator	array of UUIDs	Review initiator mailbox UUIDs
participant	array of UUIDs	Editorial review participant UUIDs
sort	string	Sort order

Supported editorial review scopes:

• inbox

• outbox

Supported editorial review statuses:

• WAITING

• ON_APPROVAL

• COMPLETED

• CANCELLED

Practical example: Find reviews waiting for a participant

This request retrieves incoming editorial reviews that are waiting for a selected participant. The template filter limits the results to one document workflow.

Node.js

const payload = {
  scope: ["inbox"],
  status: ["WAITING"],
  template: ["{templateUuid}"],
  participant: ["{participantMailboxUuid}"],
  sort: "desc"
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search-reviews?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => ["inbox"],
    "status" => ["WAITING"],
    "template" => ["{templateUuid}"],
    "participant" => ["{participantMailboxUuid}"],
    "sort" => "desc"
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search-reviews?offset=0&limit=25"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search-reviews",
    params={
        "offset": 0,
        "limit": 25,
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": ["inbox"],
        "status": ["WAITING"],
        "template": ["{templateUuid}"],
        "participant": ["{participantMailboxUuid}"],
        "sort": "desc",
    },
    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/search-reviews"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

payload = {
  scope: ["inbox"],
  status: ["WAITING"],
  template: ["{templateUuid}"],
  participant: ["{participantMailboxUuid}"],
  sort: "desc"
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"scope":       []string{"inbox"},
		"status":      []string{"WAITING"},
		"template":    []string{"{templateUuid}"},
		"participant": []string{"{participantMailboxUuid}"},
		"sort":        "desc",
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search-reviews?offset=0&limit=25",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": ["inbox"],
          "status": ["WAITING"],
          "template": ["{templateUuid}"],
          "participant": ["{participantMailboxUuid}"],
          "sort": "desc"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search-reviews" +
            "?offset=0&limit=25"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = new[] { "inbox" },
    status = new[] { "WAITING" },
    template = new[] { "{templateUuid}" },
    participant = new[] { "{participantMailboxUuid}" },
    sort = "desc"
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search-reviews" +
    "?offset=0&limit=25",
    payload
);

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/search-reviews?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": ["inbox"],
    "status": ["WAITING"],
    "template": ["{templateUuid}"],
    "participant": ["{participantMailboxUuid}"],
    "sort": "desc"
  }'

A successful request returns 200 OK with a paginated collection. Each result includes the envelope UUID, review status, progress values, template information, approval flow UUID, urgent indicator, and last update time.

{
  "totalElements": 1,
  "sizeRequested": 25,
  "numberOfElements": 1,
  "data": [
    {
      "envelopeUuid": "{envelopeUuid}",
      "subject": "Contract editorial review",
      "message": "Review the contract before approval",
      "createdAt": "2026-09-12T10:15:00Z",
      "status": "WAITING",
      "mailboxUUID": "{mailboxUuid}",
      "accountUuid": "{accountUuid}",
      "mailboxName": "Legal",
      "total": 2,
      "completed": 1,
      "templateUuid": "{templateUuid}",
      "templateName": "Contract",
      "seenAt": "2026-09-12T10:20:00Z",
      "expiredAfter": "2026-09-19T10:15:00Z",
      "approvalFlowUuid": "{approvalFlowUuid}",
      "urgent": false,
      "lastUpdatedAt": "2026-09-12T11:30:00Z"
    }
  ],
  "initiators": [
    {
      "mailboxUuid": "{initiatorMailboxUuid}",
      "mailboxName": "Sales",
      "accountUuid": "{accountUuid}",
      "accountName": "Acme"
    }
  ],
  "templates": [
    {
      "templateUuid": "{templateUuid}",
      "templateName": "Contract"
    }
  ]
}

Search envelopes for approval

Use POST /api/v1/envelope/search-approvals to retrieve envelopes associated with approval workflows. The request can filter approvals by scope, status, template, initiator, urgency, receipt date, or subject.

Request filters

Property	Type	Description
scope	string	Approval search scope
status	array of strings	Approval statuses
subject	string	Envelope subject
receiveDateFrom	date-time	Earliest envelope receipt date
receiveDateTo	date-time	Latest envelope receipt date
template	array of UUIDs	Template UUIDs
initiator	array of UUIDs	Approval initiator mailbox UUIDs
sort	string	Sort order
urgent	boolean	Urgent approval indicator

Supported approval scopes:

• inbox

• outbox

Supported approval statuses:

• NOT_STARTED

• WAITING

• APPROVED

• REJECTED

• CANCELLED

Practical example: Find urgent approvals

This request retrieves urgent incoming approval workflows that have not started. The template filter limits the results to the selected business process.

Node.js

const payload = {
  scope: "inbox",
  status: ["NOT_STARTED"],
  template: ["{templateUuid}"],
  sort: "desc",
  urgent: true
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/search-approvals?offset=0&limit=25",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "scope" => "inbox",
    "status" => ["NOT_STARTED"],
    "template" => ["{templateUuid}"],
    "sort" => "desc",
    "urgent" => true
];

$curl = curl_init(
    "https://api.docstudio.com/api/v1/envelope/search-approvals?offset=0&limit=25"
);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/search-approvals",
    params={
        "offset": 0,
        "limit": 25,
    },
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "scope": "inbox",
        "status": ["NOT_STARTED"],
        "template": ["{templateUuid}"],
        "sort": "desc",
        "urgent": True,
    },
    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/search-approvals"
)

uri.query = URI.encode_www_form(
  offset: 0,
  limit: 25
)

payload = {
  scope: "inbox",
  status: ["NOT_STARTED"],
  template: ["{templateUuid}"],
  sort: "desc",
  urgent: true
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"scope":    "inbox",
		"status":   []string{"NOT_STARTED"},
		"template": []string{"{templateUuid}"},
		"sort":     "desc",
		"urgent":   true,
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/search-approvals?offset=0&limit=25",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "scope": "inbox",
          "status": ["NOT_STARTED"],
          "template": ["{templateUuid}"],
          "sort": "desc",
          "urgent": true
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/search-approvals" +
            "?offset=0&limit=25"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    scope = "inbox",
    status = new[] { "NOT_STARTED" },
    template = new[] { "{templateUuid}" },
    sort = "desc",
    urgent = true
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/search-approvals" +
    "?offset=0&limit=25",
    payload
);

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/search-approvals?offset=0&limit=25' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "scope": "inbox",
    "status": ["NOT_STARTED"],
    "template": ["{templateUuid}"],
    "sort": "desc",
    "urgent": true
  }'

A successful response contains the matching envelopes together with the initiators and templates represented in the results. Each result includes the envelope UUID, approval flow UUID, current status, progress values, and urgent indicator.

{
  "totalElements": 1,
  "sizeRequested": 25,
  "numberOfElements": 1,
  "data": [
    {
      "envelopeUuid": "{envelopeUuid}",
      "subject": "Purchase request",
      "message": "Approve the purchase request",
      "createdAt": "2026-09-12T10:15:00Z",
      "status": "NOT_STARTED",
      "mailboxUUID": "{mailboxUuid}",
      "accountUuid": "{accountUuid}",
      "mailboxName": "Procurement",
      "total": 2,
      "completed": 0,
      "templateUuid": "{templateUuid}",
      "templateName": "Purchase request",
      "seenAt": "2026-09-12T10:20:00Z",
      "expiredAfter": "2026-09-19T10:15:00Z",
      "approvalFlowUuid": "{approvalFlowUuid}",
      "urgent": true,
      "lastUpdatedAt": "2026-09-12T10:15:00Z"
    }
  ],
  "initiators": [
    {
      "mailboxUuid": "{initiatorMailboxUuid}",
      "mailboxName": "Procurement",
      "accountUuid": "{accountUuid}",
      "accountName": "Acme"
    }
  ],
  "templates": [
    {
      "templateUuid": "{templateUuid}",
      "templateName": "Purchase request"
    }
  ]
}

Retrieve mailbox folders

Use POST /api/v1/envelope/mailbox-folders to retrieve folder values available for the current mailbox. Send the folder values to check in a JSON array. The response returns the available values.

Supported folder values:

• INBOX

• OUTBOX

• DRAFT

• ARCHIVED

• DELETED

• SHARED

• EXPIRING

• WAITING

• EVERYTHING

Node.js

const payload = [
  "INBOX",
  "OUTBOX",
  "ARCHIVED",
  "WAITING"
];

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/mailbox-folders",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "INBOX",
    "OUTBOX",
    "ARCHIVED",
    "WAITING"
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/mailbox-folders",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json=[
        "INBOX",
        "OUTBOX",
        "ARCHIVED",
        "WAITING",
    ],
    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/mailbox-folders"
)

payload = [
  "INBOX",
  "OUTBOX",
  "ARCHIVED",
  "WAITING"
]

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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 := []string{
		"INBOX",
		"OUTBOX",
		"ARCHIVED",
		"WAITING",
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/mailbox-folders",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        [
          "INBOX",
          "OUTBOX",
          "ARCHIVED",
          "WAITING"
        ]
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/mailbox-folders"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new[]
{
    "INBOX",
    "OUTBOX",
    "ARCHIVED",
    "WAITING"
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/mailbox-folders",
    payload
);

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/mailbox-folders' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
    "INBOX",
    "OUTBOX",
    "ARCHIVED",
    "WAITING"
  ]'

A successful request returns 200 OK with the available folder values. These values can be used to build mailbox navigation or determine which envelope collections are available in the current mailbox.

[
  "INBOX",
  "OUTBOX",
  "ARCHIVED",
  "WAITING"
]

Request an envelope report

Use POST /api/v1/envelope/report to request a report for specific envelope UUIDs or for envelopes matching search parameters. The request schema requires uuids and searchParams to be specified separately, so provide only one of these properties in each request.

Create a report for selected envelopes

Node.js

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

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/report",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "uuids" => [
        "{envelopeUuid}",
        "{anotherEnvelopeUuid}"
    ]
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

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

response.raise_for_status()
print(response.text)

Ruby

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

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

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

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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][]string{
		"uuids": {
			"{envelopeUuid}",
			"{anotherEnvelopeUuid}",
		},
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/report",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "uuids": [
            "{envelopeUuid}",
            "{anotherEnvelopeUuid}"
          ]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/report"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

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

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/report",
    payload
);

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/report' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "uuids": [
      "{envelopeUuid}",
      "{anotherEnvelopeUuid}"
    ]
  }'

Create a report from search filters

Node.js

const payload = {
  searchParams: {
    scope: ["outbox"],
    status: ["COMPLETED"],
    sendDateFrom: "2026-09-01T00:00:00Z",
    sendDateTo: "2026-09-30T23:59:59Z",
    template: ["{templateUuid}"],
    sortField: "createdAt",
    sort: "desc"
  }
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/report",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "searchParams" => [
        "scope" => ["outbox"],
        "status" => ["COMPLETED"],
        "sendDateFrom" => "2026-09-01T00:00:00Z",
        "sendDateTo" => "2026-09-30T23:59:59Z",
        "template" => ["{templateUuid}"],
        "sortField" => "createdAt",
        "sort" => "desc"
    ]
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/report",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "searchParams": {
            "scope": ["outbox"],
            "status": ["COMPLETED"],
            "sendDateFrom": "2026-09-01T00:00:00Z",
            "sendDateTo": "2026-09-30T23:59:59Z",
            "template": ["{templateUuid}"],
            "sortField": "createdAt",
            "sort": "desc",
        },
    },
    timeout=30,
)

response.raise_for_status()
print(response.text)

Ruby

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

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

payload = {
  searchParams: {
    scope: ["outbox"],
    status: ["COMPLETED"],
    sendDateFrom: "2026-09-01T00:00:00Z",
    sendDateTo: "2026-09-30T23:59:59Z",
    template: ["{templateUuid}"],
    sortField: "createdAt",
    sort: "desc"
  }
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"searchParams": map[string]any{
			"scope":        []string{"outbox"},
			"status":       []string{"COMPLETED"},
			"sendDateFrom": "2026-09-01T00:00:00Z",
			"sendDateTo":   "2026-09-30T23:59:59Z",
			"template":     []string{"{templateUuid}"},
			"sortField":    "createdAt",
			"sort":         "desc",
		},
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/report",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "searchParams": {
            "scope": ["outbox"],
            "status": ["COMPLETED"],
            "sendDateFrom": "2026-09-01T00:00:00Z",
            "sendDateTo": "2026-09-30T23:59:59Z",
            "template": ["{templateUuid}"],
            "sortField": "createdAt",
            "sort": "desc"
          }
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/report"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    searchParams = new
    {
        scope = new[] { "outbox" },
        status = new[] { "COMPLETED" },
        sendDateFrom = "2026-09-01T00:00:00Z",
        sendDateTo = "2026-09-30T23:59:59Z",
        template = new[] { "{templateUuid}" },
        sortField = "createdAt",
        sort = "desc"
    }
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/report",
    payload
);

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/report' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "searchParams": {
      "scope": ["outbox"],
      "status": ["COMPLETED"],
      "sendDateFrom": "2026-09-01T00:00:00Z",
      "sendDateTo": "2026-09-30T23:59:59Z",
      "template": ["{templateUuid}"],
      "sortField": "createdAt",
      "sort": "desc"
    }
  }'

A successful request returns 201 Created, confirming that DocStudio accepted the report request. The Swagger operation does not define a response body or a separate report-retrieval endpoint for this operation.

Configure displayed envelope columns

Column endpoints manage additional envelope fields displayed in the mailbox envelope list. The configuration belongs to the mailbox supplied in the Mailbox header and is returned in the columns property of an envelope search response.

The create request uses fieldName to identify the searchable envelope field that should become a column. Column responses use name for the resulting display name, while type identifies how the field value is represented.

Add a displayed column

Use POST /api/v1/envelope/column to add a searchable envelope field as a displayed column. Save the returned UUID because it is required to update or delete the column.

Property	Type	Required	Description
fieldName	string	Yes	Searchable field name
type	string	Yes	Searchable field type
order	integer	No	Position of the column
visible	boolean	No	Column visibility
width	integer	No	Column width

Supported type values:

• text

• datetime

• selectDictionary

• einksign

• initials

• pades

• number

• money

• lookup

• duplicate

• attachment

• formula

• numberToText

• autonumber

• checkbox

• dropdown

• radio

• barcode

Node.js

const payload = {
  fieldName: "customer_name",
  type: "text",
  order: 5,
  visible: true,
  width: 220
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/column",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "fieldName" => "customer_name",
    "type" => "text",
    "order" => 5,
    "visible" => true,
    "width" => 220
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/column",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "fieldName": "customer_name",
        "type": "text",
        "order": 5,
        "visible": True,
        "width": 220,
    },
    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/column"
)

payload = {
  fieldName: "customer_name",
  type: "text",
  order: 5,
  visible: true,
  width: 220
}

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"fieldName": "customer_name",
		"type":      "text",
		"order":     5,
		"visible":   true,
		"width":     220,
	}

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

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/column",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "fieldName": "customer_name",
          "type": "text",
          "order": 5,
          "visible": true,
          "width": 220
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/column"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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.Net.Http.Json;

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    fieldName = "customer_name",
    type = "text",
    order = 5,
    visible = true,
    width = 220
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/column",
    payload
);

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/column' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "fieldName": "customer_name",
    "type": "text",
    "order": 5,
    "visible": true,
    "width": 220
  }'

A successful request returns 201 Created with the displayed column UUID. Use this UUID as {id} when updating the column or include it in extraFieldUuids when deleting columns.

{
  "uuid": "{columnUuid}"
}

Update a displayed column

Use PUT /api/v1/envelope/column/{id} to change the column order, visibility, or width. The {id} path parameter is the displayed column UUID returned by the create operation.

Node.js

const payload = {
  order: 3,
  visible: true,
  width: 260
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/column/{id}",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      "Content-Type": "application/json",
      Accept: "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 = [
    "order" => 3,
    "visible" => true,
    "width" => 260
];

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

curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Content-Type: application/json",
        "Accept: 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

response = requests.put(
    "https://api.docstudio.com/api/v1/envelope/column/{id}",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "order": 3,
        "visible": True,
        "width": 260,
    },
    timeout=30,
)

response.raise_for_status()
print(response.text)

Ruby

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

uri = URI(
  "https://api.docstudio.com/api/v1/envelope/column/{id}"
)

payload = {
  order: 3,
  visible: true,
  width: 260
}

request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Content-Type"] = "application/json"
request["Accept"] = "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{
		"order":   3,
		"visible": true,
		"width":   260,
	}

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

	request, err := http.NewRequest(
		http.MethodPut,
		"https://api.docstudio.com/api/v1/envelope/column/{id}",
		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",
	)
	request.Header.Set(
		"Accept",
		"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 = """
        {
          "order": 3,
          "visible": true,
          "width": 260
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/column/{id}"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "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()
      );
    }

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

.NET

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

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue(
        "Bearer",
        "{token}"
    );

client.DefaultRequestHeaders.Add(
    "Mailbox",
    "{mailboxUuid}"
);

client.DefaultRequestHeaders.Add(
    "Accept",
    "application/json"
);

var payload = new
{
    order = 3,
    visible = true,
    width = 260
};

using var response = await client.PutAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/column/{id}",
    payload
);

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 PUT \
  --url 'https://api.docstudio.com/api/v1/envelope/column/{id}' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "order": 3,
    "visible": true,
    "width": 260
  }'

A successful request returns 200 OK. The Swagger operation does not define a response body for this endpoint.

Delete displayed columns

Use DELETE /api/v1/envelope/column to remove one or more additional columns. Send the displayed column UUIDs in the extraFieldUuids request property.

Node.js

const payload = {
  extraFieldUuids: [
    "{columnUuid}",
    "{anotherColumnUuid}"
  ]
};

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

const responseBody = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed with status ${response.status}: ${responseBody}`
  );
}

console.log(responseBody);

PHP

<?php

$payload = [
    "extraFieldUuids" => [
        "{columnUuid}",
        "{anotherColumnUuid}"
    ]
];

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

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

$responseBody = curl_exec($curl);

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

$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($statusCode < 200 || $statusCode >= 300) {
    throw new RuntimeException(
        "Request failed with status {$statusCode}: {$responseBody}"
    );
}

echo $responseBody;

Python

import requests

payload = {
    "extraFieldUuids": [
        "{columnUuid}",
        "{anotherColumnUuid}"
    ]
}

response = requests.delete(
    "https://api.docstudio.com/api/v1/envelope/column",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    json=payload,
    timeout=30
)

response.raise_for_status()
print(response.text)

Ruby

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

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

payload = {
  extraFieldUuids: [
    "{columnUuid}",
    "{anotherColumnUuid}"
  ]
}

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

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

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

puts response.body

Go

package main

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

func main() {
	payload := map[string]any{
		"extraFieldUuids": []string{
			"{columnUuid}",
			"{anotherColumnUuid}",
		},
	}

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

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

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

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

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

	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"request failed with status %d: %s",
			response.StatusCode,
			responseBody,
		))
	}

	fmt.Println(string(responseBody))
}

Java

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

public class DeleteDisplayedColumns {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "extraFieldUuids": [
                "{columnUuid}",
                "{anotherColumnUuid}"
              ]
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://api.docstudio.com/api/v1/envelope/column"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Mailbox", "{mailboxUuid}")
            .header("Accept", "application/json")
            .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 with status " +
                response.statusCode() + ": " +
                response.body()
            );
        }

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

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        using var client = new HttpClient();

        var payload = new
        {
            extraFieldUuids = new[]
            {
                "{columnUuid}",
                "{anotherColumnUuid}"
            }
        };

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

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", "{token}");
        request.Headers.Add("Mailbox", "{mailboxUuid}");
        request.Headers.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json")
        );
        request.Content = JsonContent.Create(payload);

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

        if (!response.IsSuccessStatusCode)
        {
            throw new HttpRequestException(
                $"Request failed with status " +
                $"{(int)response.StatusCode}: {responseBody}"
            );
        }

        Console.WriteLine(responseBody);
    }
}

cURL

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

A successful request returns 200 OK. The Swagger operation does not define a response body for this endpoint.

Reset column settings

Use POST /api/v1/envelope/column-reset to reset the envelope-list column settings for the current mailbox. This operation changes the current column configuration, so retrieve and save the existing columns collection through POST /api/v1/envelope/search first if it may be needed later.

Node.js

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/column-reset",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer {token}",
      Mailbox: "{mailboxUuid}",
      Accept: "application/json"
    }
  }
);

const responseBody = await response.text();

if (!response.ok) {
  throw new Error(
    `Request failed with status ${response.status}: ${responseBody}`
  );
}

console.log(responseBody);

PHP

<?php

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {token}",
        "Mailbox: {mailboxUuid}",
        "Accept: application/json"
    ]
]);

$responseBody = curl_exec($curl);

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

$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($statusCode < 200 || $statusCode >= 300) {
    throw new RuntimeException(
        "Request failed with status {$statusCode}: {$responseBody}"
    );
}

echo $responseBody;

Python

import requests

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

response.raise_for_status()
print(response.text)

Ruby

require "net/http"
require "uri"

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

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer {token}"
request["Mailbox"] = "{mailboxUuid}"
request["Accept"] = "application/json"

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

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

puts response.body

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/column-reset",
		nil,
	)
	if err != nil {
		panic(err)
	}

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

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

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

	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic(fmt.Sprintf(
			"request failed with status %d: %s",
			response.StatusCode,
			responseBody,
		))
	}

	fmt.Println(string(responseBody))
}

Java

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

public class ResetColumnSettings {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(
                "https://api.docstudio.com/api/v1/envelope/column-reset"
            ))
            .header("Authorization", "Bearer {token}")
            .header("Mailbox", "{mailboxUuid}")
            .header("Accept", "application/json")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();

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

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

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

.NET

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class Program
{
    public static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(
            HttpMethod.Post,
            "https://api.docstudio.com/api/v1/envelope/column-reset"
        );

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", "{token}");
        request.Headers.Add("Mailbox", "{mailboxUuid}");
        request.Headers.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json")
        );

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

        if (!response.IsSuccessStatusCode)
        {
            throw new HttpRequestException(
                $"Request failed with status " +
                $"{(int)response.StatusCode}: {responseBody}"
            );
        }

        Console.WriteLine(responseBody);
    }
}

cURL

curl --request POST \
  --url "https://api.docstudio.com/api/v1/envelope/column-reset" \
  --header "Authorization: Bearer {token}" \
  --header "Mailbox: {mailboxUuid}" \
  --header "Accept: application/json"

A successful request returns 200 OK with the resulting column configuration. Each object contains the column UUID, name, type, order, visibility, and width.

[
  {
    "uuid": "{columnUuid}",
    "name": "Subject",
    "type": "text",
    "order": 0,
    "visible": true,
    "width": 220
  }
]

Related topics

• Check Envelope Status

• Envelope Sending Options

• List responses

• Envelope fields

• Envelope metadata

• Error handling and API error codes