> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/envelope-search.md). # Envelope Search This document contains endpoints for searching envelopes and workflows, retrieving mailbox filters, creating reports, and configuring envelope list columns. {% hint style="info" %} 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. {% endhint %} ### 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**
MethodEndpointPurpose
POST/api/v1/envelope/searchSearch envelopes available in the current mailbox
POST/api/v1/envelope/search/rolesRetrieve template roles for envelope search
POST/api/v1/envelope/search-reviewsSearch envelopes associated with editorial reviews
POST/api/v1/envelope/search-approvalsSearch envelopes associated with approval workflows
POST/api/v1/envelope/reportRequest an envelope report
POST/api/v1/envelope/mailbox-foldersRetrieve available mailbox folders
POST/api/v1/envelope/fieldsRetrieve searchable envelope fields
**Displayed columns**
MethodEndpointPurpose
POST/api/v1/envelope/columnAdd an envelope field as a displayed column
PUT/api/v1/envelope/column/{id}Update a displayed column
DELETE/api/v1/envelope/columnDelete displayed columns
POST/api/v1/envelope/column-resetReset 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.
HeaderRequiredDescription
AuthorizationYesBearer authorization token
MailboxYesCurrent mailbox UUID
Content-TypeConditionalapplication/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.
ParameterTypeRequiredDefaultDescription
offsetintegerNo0Number of envelopes to skip
limitintegerNo25Maximum number of envelopes to return
uuidOnlybooleanNoNot setRetrieve 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**
PropertyTypeDescription
labelarray of stringsEnvelope labels
scopearray of stringsEnvelope locations
statusarray of stringsEnvelope statuses
subjectstringEnvelope subject
createDateFromdate-timeEarliest envelope creation date
createDateTodate-timeLatest envelope creation date
receiveDateFromdate-timeEarliest envelope receipt date
receiveDateTodate-timeLatest envelope receipt date
expireDateFromdate-timeEarliest envelope expiration date
expireDateTodate-timeLatest envelope expiration date
sendDateFromdate-timeEarliest envelope sending date
sendDateTodate-timeLatest envelope sending date
archivedbooleanArchived or non-archived envelopes
deletedbooleanDeleted or non-deleted envelopes
templatearray of UUIDsTemplate UUIDs
activeRolearray of stringsActive template roles
senderarray of stringsEnvelope senders
recipientarray of stringsEnvelope recipients
sortFieldstringField used for sorting, createdAt by default
sortstringSort order
searchFieldsarray of objectsSearchable envelope field values
formarray of UUIDsForm UUIDs
metadataobjectMetadata key-value properties
templateVersionarray of UUIDsTemplate version UUIDs
Supported `scope` values: * `inbox` — received envelopes * `outbox` — sent envelopes * `draft` — draft envelopes * `shared` — shared envelopes Supported `status` values: {% columns %} {% column %} * `DRAFT` * `SENT` * `WAITING` {% endcolumn %} {% column %} * `COMPLETED` * `CANCELLED` {% endcolumn %} {% column %} * `EXPIRED` * `ON_APPROVAL` {% endcolumn %} {% endcolumns %} 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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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 '{}' ``` {% endtab %} {% endtabs %} **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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php ["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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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"] }' ``` {% endtab %} {% endtabs %} **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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php ["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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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" }' ``` {% endtab %} {% endtabs %} 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. ```json { "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.
PropertyDescription
dataEnvelopes returned for the current page
searchFieldsSearchable envelope fields available in the results
columnsCurrent envelope-list column configuration
sendersSenders represented in the results
templatesTemplates represented in the results
sendersInfoAdditional sender information
templatesInfoAdditional 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:
PropertyTypeRequiredDescription
namestringYesField name, minimum one character
valuestringNoString field value
numbernumberNoNumeric field value
fromdate-timeNoBeginning of a date-time range
todate-timeNoEnd of a date-time range
checkedbooleanNoCheckbox value
typestringNoSearchable 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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php ["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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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"] }' ``` {% endtab %} {% endtabs %} A successful request returns `200 OK` with the matching field names and types. The response can contain multiple searchable fields. ```json [ { "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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php ["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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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" } ] }' ``` {% endtab %} {% endtabs %} Add `from` and `to` to search a date-time range: ```json { "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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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}" ]' ``` {% endtab %} {% endtabs %} 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**
PropertyTypeDescription
scopearray of stringsEditorial review scopes
statusarray of stringsEditorial review statuses
subjectstringEnvelope subject
receiveDateFromdate-timeEarliest envelope receipt date
receiveDateTodate-timeLatest envelope receipt date
templatearray of UUIDsTemplate UUIDs
initiatorarray of UUIDsReview initiator mailbox UUIDs
participantarray of UUIDsEditorial review participant UUIDs
sortstringSort 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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php ["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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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" }' ``` {% endtab %} {% endtabs %} 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. ```json { "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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php "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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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 }' ``` {% endtab %} {% endtabs %} 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. ```json { "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: {% columns %} {% column %} * `INBOX` * `OUTBOX` * `DRAFT` {% endcolumn %} {% column %} * `ARCHIVED` * `DELETED` * `SHARED` {% endcolumn %} {% column %} * `EXPIRING` * `WAITING` * `EVERYTHING` {% endcolumn %} {% endcolumns %} {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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" ]' ``` {% endtab %} {% endtabs %} 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. ```json [ "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** {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php [ "{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; ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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}" ] }' ``` {% endtab %} {% endtabs %} **Create a report from search filters** {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php [ "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; ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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" } }' ``` {% endtab %} {% endtabs %} 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.
PropertyTypeRequiredDescription
fieldNamestringYesSearchable field name
typestringYesSearchable field type
orderintegerNoPosition of the column
visiblebooleanNoColumn visibility
widthintegerNoColumn width
Supported `type` values: {% columns %} {% column %} * `text` * `datetime` * `selectDictionary` * `einksign` * `initials` * `pades` {% endcolumn %} {% column %} * `number` * `money` * `lookup` * `duplicate` * `attachment` * `formula` {% endcolumn %} {% column %} * `numberToText` * `autonumber` * `checkbox` * `dropdown` * `radio` * `barcode` {% endcolumn %} {% endcolumns %} {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php "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; ``` {% endtab %} {% tab title="Python" %} ```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()) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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 }' ``` {% endtab %} {% endtabs %} 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. ```json { "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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); ``` {% endtab %} {% tab title="cURL" %} ```bash 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 }' ``` {% endtab %} {% endtabs %} 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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php [ "{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; ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); } } ``` {% endtab %} {% tab title="cURL" %} ```bash 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}" ] }' ``` {% endtab %} {% endtabs %} 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. {% tabs %} {% tab title="Node.js" %} ```javascript 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); ``` {% endtab %} {% tab title="PHP" %} ```php 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; ``` {% endtab %} {% tab title="Python" %} ```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) ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="Go" %} ```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)) } ``` {% endtab %} {% tab title="Java" %} ```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 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()); } } ``` {% endtab %} {% tab title=".NET" %} ```csharp 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); } } ``` {% endtab %} {% tab title="cURL" %} ```bash curl --request POST \ --url "https://api.docstudio.com/api/v1/envelope/column-reset" \ --header "Authorization: Bearer {token}" \ --header "Mailbox: {mailboxUuid}" \ --header "Accept: application/json" ``` {% endtab %} {% endtabs %} A successful request returns `200 OK` with the resulting column configuration. Each object contains the column UUID, name, type, order, visibility, and width. ```json [ { "uuid": "{columnUuid}", "name": "Subject", "type": "text", "order": 0, "visible": true, "width": 220 } ] ``` ### Related topics {% columns %} {% column %} * [Check Envelope Status](/api-reference/check-envelope-status.md) * [Envelope Sending Options](/guides/envelope-sending-options.md) * [List responses](/guides/list-responses.md) {% endcolumn %} {% column %} * [Envelope fields](/guides/envelope-fields.md) * [Envelope metadata](/guides/envelope-metadata.md) * [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md) {% endcolumn %} {% endcolumns %}