Envelope Sending Options

This document contains alternative envelope-sending endpoints for share-code, Quick Send, public Quick Send, and One-time Send.

DocStudio provides several endpoints for sending envelopes in addition to the standard POST /api/v1/envelope/send flow. The correct endpoint depends on whether the envelope uses a reusable template, uploaded external documents, a public sending flow, or a one-time template.

Business goals

The envelope-sending endpoints support the following business goals:

• Send from a shared template. Use a share code and verification code to create and send an envelope without referencing the template UUID directly.

• Send external documents quickly. Upload existing files and define recipients without constructing template and envelope XML.

• Provide a public sending flow. Allow a signer to send one external document through a verification-code-based request.

• Use a template once. Send an envelope from inline template and envelope XML when the template must not remain available for reuse.

Choose a sending method

Endpoint	Use when	Key requirement
POST /api/v1/envelope/send	Send from an existing reusable template	Template UUID and template version
POST /api/v1/envelope/send-by-share-code	Send from a shared template	Share code and verification code
POST /api/v1/envelope/quick-send	Send one or more external documents from a mailbox	API token and Mailbox header
POST /api/v1/envelope/public-quick-send	Publicly send one external document	Verification code and signer email
POST /api/v1/envelope/one-time-send	Send from inline template and envelope XML	Template is marked as deleted after use

Use the standard Send Envelope endpoint when the template must remain reusable. The sections below describe the alternative sending methods.

Quick Send and Public Quick Send

Property	Quick Send	Public Quick Send
Authentication	API token and Mailbox header	Public verification-code flow
Files	One or more files parts	One file part
Recipient input	recipients array	One signer email
Endpoint	/api/v1/envelope/quick-send	/api/v1/envelope/public-quick-send

Send an envelope by share code

Use POST /api/v1/envelope/send-by-share-code when a template is made available through a share code. The request contains the share code, its verification code, and the envelope XML serialized as a JSON string.

See XML payloads for guidance on serializing envelope XML as a JSON string.

Request

Field	Type	Required	Description
shareCode	string	Yes	Share code that identifies the shared template
verificationCode	string	Yes	Verification code for the shared-template flow
data	string	Yes	Envelope XML serialized as a JSON string
agreed	boolean	No	Indicates whether the required agreement was accepted

Node.js

const payload = {
  shareCode: "{shareCode}",
  verificationCode: "{verificationCode}",
  data: "{envelopeXml}",
  agreed: true
};

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/send-by-share-code",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const body = await response.text();

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

console.log(body);

PHP

<?php

$payload = [
    "shareCode" => "{shareCode}",
    "verificationCode" => "{verificationCode}",
    "data" => "{envelopeXml}",
    "agreed" => true
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Accept: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

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

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

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

echo $body;

Python

import requests

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/send-by-share-code",
    headers={
        "Accept": "application/json",
    },
    json={
        "shareCode": "{shareCode}",
        "verificationCode": "{verificationCode}",
        "data": "{envelopeXml}",
        "agreed": True,
    },
    timeout=30,
)

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

Ruby

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

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

payload = {
  shareCode: "{shareCode}",
  verificationCode: "{verificationCode}",
  data: "{envelopeXml}",
  agreed: true
}

request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Accept"] = "application/json"
request.body = JSON.generate(payload)

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

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

puts response.body

Go

package main

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

func main() {
	payload := map[string]any{
		"shareCode":       "{shareCode}",
		"verificationCode": "{verificationCode}",
		"data":            "{envelopeXml}",
		"agreed":          true,
	}

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

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

	request.Header.Set(
		"Content-Type",
		"application/json",
	)
	request.Header.Set(
		"Accept",
		"application/json",
	)

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

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

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

	fmt.Println(string(body))
}

Java

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

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "shareCode": "{shareCode}",
          "verificationCode": "{verificationCode}",
          "data": "{envelopeXml}",
          "agreed": true
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/send-by-share-code"
        ))
        .header(
            "Content-Type",
            "application/json"
        )
        .header(
            "Accept",
            "application/json"
        )
        .POST(
            HttpRequest.BodyPublishers.ofString(payload)
        )
        .build();

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

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

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

.NET

using System.Net.Http.Json;

using var client = new HttpClient();

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

var payload = new
{
    shareCode = "{shareCode}",
    verificationCode = "{verificationCode}",
    data = "{envelopeXml}",
    agreed = true
};

using var response = await client.PostAsJsonAsync(
    "https://api.docstudio.com/api/v1/envelope/send-by-share-code",
    payload
);

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

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

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope/send-by-share-code' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "shareCode": "{shareCode}",
    "verificationCode": "{verificationCode}",
    "data": "{envelopeXml}",
    "agreed": true
  }'

Response

A successful request returns 201 Created. Save the returned identifiers and token because they identify the created envelope and its mailbox context.

{
  "token": "{token}",
  "envelopeUuid": "{envelopeUuid}",
  "mailboxUuid": "{mailboxUuid}"
}

Field	Type	Description
token	UUID	Token returned for the share-code sending flow
envelopeUuid	UUID	UUID of the created envelope
mailboxUuid	UUID	UUID of the mailbox associated with the envelope

Quick Send external documents

Use POST /api/v1/envelope/quick-send to send existing files without preparing template XML. The request uses multipart/form-data and contains one or more files together with a JSON data part.

The operation requires an API token and the sender mailbox UUID in the Mailbox header.

Headers

Header	Required	Description
Authorization	Yes	Bearer authorization token
Mailbox	Yes	UUID of the sender mailbox
Accept	No	application/json

Request parts

Part	Type	Required	Description
files	array of binary files	Yes	External documents included in the envelope
data	JSON object	Yes	QuickSendDTO sent as a blob with Content-Type: application/json

The data object supports the following properties:

Property	Type	Required	Description
subject	string	Yes	Envelope subject
message	string	No	Message displayed to recipients
recipients	array	No	Recipients and their required actions
signatureAlgorithm	string	No	Signature algorithm: DSTU4145 or ECDSA_RSA
signatureContainer	string	No	Signature container: P7S, ASICE, or P7S_ENVELOPED
recipientExperience	object	No	Language, locale, and time-zone settings for recipients

Each object in recipients supports these properties:

Property	Type	Required	Description
recipient	string	Yes	Recipient identifier
approver	boolean	No	Requires the recipient to approve the document
signer	boolean	No	Requires the recipient to sign the document
eInkSignature	boolean	No	Enables an electronic handwritten signature action

The recipient value identifies the recipient. The example uses an email address. Set the recipient action fields required by the workflow.

When recipientExperience is included, provide its required properties:

Property	Example	Description
language	en	Recipient interface language
locale	en-US	Recipient locale
timezone	Europe/Kyiv	Recipient time zone

Practical example: Send a contract for signature

The following request uploads a PDF contract and sends it to a signer:

Node.js

import { openAsBlob } from "node:fs";

const payload = {
  subject: "Contract for signature",
  message: "Please review and sign the attached contract.",
  recipients: [
    {
      recipient: "[e-mail]",
      approver: false,
      signer: true,
      eInkSignature: false
    }
  ],
  signatureAlgorithm: "ECDSA_RSA",
  signatureContainer: "P7S",
  recipientExperience: {
    language: "en",
    locale: "en-US",
    timezone: "Europe/Kyiv"
  }
};

const form = new FormData();

form.append(
  "files",
  await openAsBlob("contract.pdf"),
  "contract.pdf"
);

form.append(
  "data",
  new Blob(
    [JSON.stringify(payload)],
    { type: "application/json" }
  )
);

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

const body = await response.text();

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

console.log(body);

PHP

<?php

$payload = [
    "subject" => "Contract for signature",
    "message" => "Please review and sign the attached contract.",
    "recipients" => [
        [
            "recipient" => "[e-mail]",
            "approver" => false,
            "signer" => true,
            "eInkSignature" => false
        ]
    ],
    "signatureAlgorithm" => "ECDSA_RSA",
    "signatureContainer" => "P7S",
    "recipientExperience" => [
        "language" => "en",
        "locale" => "en-US",
        "timezone" => "Europe/Kyiv"
    ]
];

$form = [
    "files" => new CURLFile(
        "contract.pdf",
        "application/pdf",
        "contract.pdf"
    ),
    "data" => new CURLStringFile(
        json_encode($payload),
        "data.json",
        "application/json"
    )
];

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

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

$body = curl_exec($curl);

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

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

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

echo $body;

Python

import json

import requests

payload = {
    "subject": "Contract for signature",
    "message": "Please review and sign the attached contract.",
    "recipients": [
        {
            "recipient": "[e-mail]",
            "approver": False,
            "signer": True,
            "eInkSignature": False,
        }
    ],
    "signatureAlgorithm": "ECDSA_RSA",
    "signatureContainer": "P7S",
    "recipientExperience": {
        "language": "en",
        "locale": "en-US",
        "timezone": "Europe/Kyiv",
    },
}

with open("contract.pdf", "rb") as document:
    response = requests.post(
        "https://api.docstudio.com/api/v1/envelope/quick-send",
        headers={
            "Authorization": "Bearer {token}",
            "Mailbox": "{mailboxUuid}",
            "Accept": "application/json",
        },
        files={
            "files": (
                "contract.pdf",
                document,
                "application/pdf",
            ),
            "data": (
                None,
                json.dumps(payload),
                "application/json",
            ),
        },
        timeout=30,
    )

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

Ruby

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

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

payload = {
  subject: "Contract for signature",
  message: "Please review and sign the attached contract.",
  recipients: [
    {
      recipient: "[e-mail]",
      approver: false,
      signer: true,
      eInkSignature: false
    }
  ],
  signatureAlgorithm: "ECDSA_RSA",
  signatureContainer: "P7S",
  recipientExperience: {
    language: "en",
    locale: "en-US",
    timezone: "Europe/Kyiv"
  }
}

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

file = File.open("contract.pdf", "rb")

request.set_form(
  [
    [
      "files",
      file,
      {
        filename: "contract.pdf",
        content_type: "application/pdf"
      }
    ],
    [
      "data",
      JSON.generate(payload),
      {
        content_type: "application/json"
      }
    ]
  ],
  "multipart/form-data"
)

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

file.close

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

puts response.body

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"net/textproto"
	"os"
)

func main() {
	payload := map[string]any{
		"subject": "Contract for signature",
		"message": "Please review and sign the attached contract.",
		"recipients": []map[string]any{
			{
				"recipient":      "[e-mail]",
				"approver":       false,
				"signer":         true,
				"eInkSignature": false,
			},
		},
		"signatureAlgorithm": "ECDSA_RSA",
		"signatureContainer": "P7S",
		"recipientExperience": map[string]string{
			"language": "en",
			"locale":   "en-US",
			"timezone": "Europe/Kyiv",
		},
	}

	var requestBody bytes.Buffer
	writer := multipart.NewWriter(&requestBody)

	file, err := os.Open("contract.pdf")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	filePart, err := writer.CreateFormFile(
		"files",
		"contract.pdf",
	)
	if err != nil {
		panic(err)
	}

	if _, err := io.Copy(filePart, file); err != nil {
		panic(err)
	}

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

	headers := make(textproto.MIMEHeader)
	headers.Set(
		"Content-Disposition",
		`form-data; name="data"`,
	)
	headers.Set(
		"Content-Type",
		"application/json",
	)

	dataPart, err := writer.CreatePart(headers)
	if err != nil {
		panic(err)
	}

	if _, err := dataPart.Write(jsonData); err != nil {
		panic(err)
	}

	if err := writer.Close(); err != nil {
		panic(err)
	}

	request, err := http.NewRequest(
		http.MethodPost,
		"https://api.docstudio.com/api/v1/envelope/quick-send",
		&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",
		writer.FormDataContentType(),
	)

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

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

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

	fmt.Println(string(body))
}

Java

import java.io.ByteArrayOutputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.UUID;

public class Main {
  public static void main(String[] args) throws Exception {
    String boundary =
        "DocStudioBoundary" +
        UUID.randomUUID();

    String payload = """
        {
          "subject": "Contract for signature",
          "message": "Please review and sign the attached contract.",
          "recipients": [
            {
              "recipient": "[e-mail]",
              "approver": false,
              "signer": true,
              "eInkSignature": false
            }
          ],
          "signatureAlgorithm": "ECDSA_RSA",
          "signatureContainer": "P7S",
          "recipientExperience": {
            "language": "en",
            "locale": "en-US",
            "timezone": "Europe/Kyiv"
          }
        }
        """;

    ByteArrayOutputStream body =
        new ByteArrayOutputStream();

    writeText(body, "--" + boundary + "\r\n");
    writeText(
        body,
        "Content-Disposition: form-data; " +
        "name=\"files\"; " +
        "filename=\"contract.pdf\"\r\n"
    );
    writeText(
        body,
        "Content-Type: application/pdf\r\n\r\n"
    );
    body.write(
        Files.readAllBytes(
            Path.of("contract.pdf")
        )
    );
    writeText(body, "\r\n");

    writeText(body, "--" + boundary + "\r\n");
    writeText(
        body,
        "Content-Disposition: form-data; " +
        "name=\"data\"\r\n"
    );
    writeText(
        body,
        "Content-Type: application/json\r\n\r\n"
    );
    writeText(body, payload);
    writeText(body, "\r\n");

    writeText(
        body,
        "--" + boundary + "--\r\n"
    );

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/quick-send"
        ))
        .header(
            "Authorization",
            "Bearer {token}"
        )
        .header(
            "Mailbox",
            "{mailboxUuid}"
        )
        .header(
            "Accept",
            "application/json"
        )
        .header(
            "Content-Type",
            "multipart/form-data; boundary=" + boundary
        )
        .POST(
            HttpRequest.BodyPublishers.ofByteArray(
                body.toByteArray()
            )
        )
        .build();

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

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

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

  private static void writeText(
      ByteArrayOutputStream output,
      String value
  ) throws Exception {
    output.write(
        value.getBytes(StandardCharsets.UTF_8)
    );
  }
}

.NET

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

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 = """
{
  "subject": "Contract for signature",
  "message": "Please review and sign the attached contract.",
  "recipients": [
    {
      "recipient": "[e-mail]",
      "approver": false,
      "signer": true,
      "eInkSignature": false
    }
  ],
  "signatureAlgorithm": "ECDSA_RSA",
  "signatureContainer": "P7S",
  "recipientExperience": {
    "language": "en",
    "locale": "en-US",
    "timezone": "Europe/Kyiv"
  }
}
""";

using var form =
    new MultipartFormDataContent();

using var fileContent =
    new StreamContent(
        File.OpenRead("contract.pdf")
    );

fileContent.Headers.ContentType =
    new MediaTypeHeaderValue(
        "application/pdf"
    );

form.Add(
    fileContent,
    "files",
    "contract.pdf"
);

using var dataContent = new StringContent(
    payload,
    Encoding.UTF8,
    "application/json"
);

form.Add(
    dataContent,
    "data"
);

using var response = await client.PostAsync(
    "https://api.docstudio.com/api/v1/envelope/quick-send",
    form
);

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

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

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope/quick-send' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Accept: application/json' \
  --form 'files=@contract.pdf;type=application/pdf' \
  --form 'data={
    "subject": "Contract for signature",
    "message": "Please review and sign the attached contract.",
    "recipients": [
      {
        "recipient": "[e-mail]",
        "approver": false,
        "signer": true,
        "eInkSignature": false
      }
    ],
    "signatureAlgorithm": "ECDSA_RSA",
    "signatureContainer": "P7S",
    "recipientExperience": {
      "language": "en",
      "locale": "en-US",
      "timezone": "Europe/Kyiv"
    }
  };type=application/json'

A successful request returns 201 Created with the envelope UUID:

{
  "uuid": "{envelopeUuid}"
}

Public Quick Send

Use POST /api/v1/envelope/public-quick-send to send one external document through a public verification-code-based flow. Unlike Quick Send, this endpoint accepts one file and does not define a Mailbox header.

The request uses multipart/form-data. The data part must be sent as a JSON blob with Content-Type: application/json.

Treat verification codes as sensitive values. Do not include them in URLs, client-side logs, or application logs.

Request parts

Part	Type	Required	Description
file	binary file	Yes	External document included in the envelope
data	JSON object	Yes	Public sending configuration

The data object contains the following properties:

Property	Type	Required	Description
verificationCode	string	Yes	Verification code for the public sending flow
agreed	boolean	No	Indicates whether the required agreement was accepted
signer	email	Yes	Email address of the signer

Practical example: Publicly send one document

Node.js

import { openAsBlob } from "node:fs";

const payload = {
  verificationCode: "{verificationCode}",
  agreed: true,
  signer: "[e-mail]"
};

const form = new FormData();

form.append(
  "file",
  await openAsBlob("agreement.pdf"),
  "agreement.pdf"
);

form.append(
  "data",
  new Blob(
    [JSON.stringify(payload)],
    { type: "application/json" }
  )
);

const response = await fetch(
  "https://api.docstudio.com/api/v1/envelope/public-quick-send",
  {
    method: "POST",
    headers: {
      Accept: "application/json"
    },
    body: form
  }
);

const body = await response.text();

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

console.log(body);

PHP

<?php

$payload = [
    "verificationCode" => "{verificationCode}",
    "agreed" => true,
    "signer" => "[e-mail]"
];

$form = [
    "file" => new CURLFile(
        "agreement.pdf",
        "application/pdf",
        "agreement.pdf"
    ),
    "data" => new CURLStringFile(
        json_encode($payload),
        "data.json",
        "application/json"
    )
];

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

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json"
    ],
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true
]);

$body = curl_exec($curl);

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

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

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

echo $body;

Python

import json

import requests

payload = {
    "verificationCode": "{verificationCode}",
    "agreed": True,
    "signer": "[e-mail]",
}

with open("agreement.pdf", "rb") as document:
    response = requests.post(
        "https://api.docstudio.com/api/v1/envelope/public-quick-send",
        headers={
            "Accept": "application/json",
        },
        files={
            "file": (
                "agreement.pdf",
                document,
                "application/pdf",
            ),
            "data": (
                None,
                json.dumps(payload),
                "application/json",
            ),
        },
        timeout=30,
    )

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

Ruby

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

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

payload = {
  verificationCode: "{verificationCode}",
  agreed: true,
  signer: "[e-mail]"
}

request = Net::HTTP::Post.new(uri)
request["Accept"] = "application/json"

file = File.open("agreement.pdf", "rb")

request.set_form(
  [
    [
      "file",
      file,
      {
        filename: "agreement.pdf",
        content_type: "application/pdf"
      }
    ],
    [
      "data",
      JSON.generate(payload),
      {
        content_type: "application/json"
      }
    ]
  ],
  "multipart/form-data"
)

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

file.close

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

puts response.body

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"net/textproto"
	"os"
)

func main() {
	payload := map[string]any{
		"verificationCode": "{verificationCode}",
		"agreed":           true,
		"signer":           "[e-mail]",
	}

	var requestBody bytes.Buffer
	writer := multipart.NewWriter(&requestBody)

	file, err := os.Open("agreement.pdf")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	filePart, err := writer.CreateFormFile(
		"file",
		"agreement.pdf",
	)
	if err != nil {
		panic(err)
	}

	if _, err := io.Copy(filePart, file); err != nil {
		panic(err)
	}

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

	headers := make(textproto.MIMEHeader)
	headers.Set(
		"Content-Disposition",
		`form-data; name="data"`,
	)
	headers.Set(
		"Content-Type",
		"application/json",
	)

	dataPart, err := writer.CreatePart(headers)
	if err != nil {
		panic(err)
	}

	if _, err := dataPart.Write(jsonData); err != nil {
		panic(err)
	}

	if err := writer.Close(); err != nil {
		panic(err)
	}

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

	request.Header.Set(
		"Accept",
		"application/json",
	)
	request.Header.Set(
		"Content-Type",
		writer.FormDataContentType(),
	)

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

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

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

	fmt.Println(string(body))
}

Java

import java.io.ByteArrayOutputStream;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.UUID;

public class Main {
  public static void main(String[] args) throws Exception {
    String boundary =
        "DocStudioBoundary" +
        UUID.randomUUID();

    String payload = """
        {
          "verificationCode": "{verificationCode}",
          "agreed": true,
          "signer": "[e-mail]"
        }
        """;

    ByteArrayOutputStream body =
        new ByteArrayOutputStream();

    writeText(body, "--" + boundary + "\r\n");
    writeText(
        body,
        "Content-Disposition: form-data; " +
        "name=\"file\"; " +
        "filename=\"agreement.pdf\"\r\n"
    );
    writeText(
        body,
        "Content-Type: application/pdf\r\n\r\n"
    );
    body.write(
        Files.readAllBytes(
            Path.of("agreement.pdf")
        )
    );
    writeText(body, "\r\n");

    writeText(body, "--" + boundary + "\r\n");
    writeText(
        body,
        "Content-Disposition: form-data; " +
        "name=\"data\"\r\n"
    );
    writeText(
        body,
        "Content-Type: application/json\r\n\r\n"
    );
    writeText(body, payload);
    writeText(body, "\r\n");

    writeText(
        body,
        "--" + boundary + "--\r\n"
    );

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://api.docstudio.com/api/v1/envelope/public-quick-send"
        ))
        .header(
            "Accept",
            "application/json"
        )
        .header(
            "Content-Type",
            "multipart/form-data; boundary=" + boundary
        )
        .POST(
            HttpRequest.BodyPublishers.ofByteArray(
                body.toByteArray()
            )
        )
        .build();

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

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

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

  private static void writeText(
      ByteArrayOutputStream output,
      String value
  ) throws Exception {
    output.write(
        value.getBytes(StandardCharsets.UTF_8)
    );
  }
}

.NET

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

using var client = new HttpClient();

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

var payload = """
{
  "verificationCode": "{verificationCode}",
  "agreed": true,
  "signer": "[e-mail]"
}
""";

using var form =
    new MultipartFormDataContent();

using var fileContent =
    new StreamContent(
        File.OpenRead("agreement.pdf")
    );

fileContent.Headers.ContentType =
    new MediaTypeHeaderValue(
        "application/pdf"
    );

form.Add(
    fileContent,
    "file",
    "agreement.pdf"
);

using var dataContent = new StringContent(
    payload,
    Encoding.UTF8,
    "application/json"
);

form.Add(
    dataContent,
    "data"
);

using var response = await client.PostAsync(
    "https://api.docstudio.com/api/v1/envelope/public-quick-send",
    form
);

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

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

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope/public-quick-send' \
  --header 'Accept: application/json' \
  --form 'file=@agreement.pdf;type=application/pdf' \
  --form 'data={
    "verificationCode": "{verificationCode}",
    "agreed": true,
    "signer": "[e-mail]"
  };type=application/json'

A successful request returns 201 Created. The response uses id as the envelope identifier:

{
  "id": "{envelopeUuid}"
}

Use Send Envelope when the document flow requires a reusable template.

Quick Send returns the envelope identifier in uuid. Public Quick Send returns it in id.

One-time Send

Use POST /api/v1/envelope/one-time-send when the integration provides both the template XML and envelope XML in the request. The template is used for this sending operation and is then marked as deleted.

Do not use this endpoint when the template must remain available for future envelopes. Use Send Envelope with a reusable template instead.

Headers

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

Request

Field	Type	Required	Description
templateXml	string	Yes	Template XML serialized as a JSON string
envelopeXml	string	Yes	Envelope XML serialized as a JSON string
signatureAlgorithm	string	No	Signature algorithm: DSTU4145 or ECDSA_RSA
signatureContainer	string	No	Signature container: P7S, ASICE, or P7S_ENVELOPED

Node.js

const payload = {
  templateXml: "{templateXml}",
  envelopeXml: "{envelopeXml}",
  signatureAlgorithm: "ECDSA_RSA",
  signatureContainer: "P7S"
};

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

const body = await response.text();

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

console.log(body);

PHP

<?php

$payload = [
    "templateXml" => "{templateXml}",
    "envelopeXml" => "{envelopeXml}",
    "signatureAlgorithm" => "ECDSA_RSA",
    "signatureContainer" => "P7S"
];

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

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

$body = curl_exec($curl);

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

$status = curl_getinfo(
    $curl,
    CURLINFO_RESPONSE_CODE
);

curl_close($curl);

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

echo $body;

Python

import requests

response = requests.post(
    "https://api.docstudio.com/api/v1/envelope/one-time-send",
    headers={
        "Authorization": "Bearer {token}",
        "Mailbox": "{mailboxUuid}",
        "Accept": "application/json",
    },
    json={
        "templateXml": "{templateXml}",
        "envelopeXml": "{envelopeXml}",
        "signatureAlgorithm": "ECDSA_RSA",
        "signatureContainer": "P7S",
    },
    timeout=30,
)

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

Ruby

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

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

payload = {
  templateXml: "{templateXml}",
  envelopeXml: "{envelopeXml}",
  signatureAlgorithm: "ECDSA_RSA",
  signatureContainer: "P7S"
}

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

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

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

puts response.body

Go

package main

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

func main() {
	payload := map[string]string{
		"templateXml":        "{templateXml}",
		"envelopeXml":        "{envelopeXml}",
		"signatureAlgorithm": "ECDSA_RSA",
		"signatureContainer": "P7S",
	}

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

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

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

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

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

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

	fmt.Println(string(body))
}

Java

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

public class Main {
  public static void main(String[] args) throws Exception {
    String payload = """
        {
          "templateXml": "{templateXml}",
          "envelopeXml": "{envelopeXml}",
          "signatureAlgorithm": "ECDSA_RSA",
          "signatureContainer": "P7S"
        }
        """;

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

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

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

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

.NET

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

using var client = new HttpClient();

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

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

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

var payload = new
{
    templateXml = "{templateXml}",
    envelopeXml = "{envelopeXml}",
    signatureAlgorithm = "ECDSA_RSA",
    signatureContainer = "P7S"
};

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

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

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

Console.WriteLine(body);

cURL

curl --request POST \
  --url 'https://api.docstudio.com/api/v1/envelope/one-time-send' \
  --header 'Authorization: Bearer {token}' \
  --header 'Mailbox: {mailboxUuid}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "templateXml": "{templateXml}",
    "envelopeXml": "{envelopeXml}",
    "signatureAlgorithm": "ECDSA_RSA",
    "signatureContainer": "P7S"
  }'

Response

A successful request returns 201 Created with the created envelope UUID:

{
  "uuid": "{envelopeUuid}"
}

Error handling

Share-code sending can return 405 Method Not Allowed when the server disables share-code sending. For complete error response schemas and status codes, use the Swagger UI.

Related topics

• Send Envelope

• Upload Attachments

• Envelope Structure

• XML payloads

• Templates and reusable IDs

• Search Mailboxes and Contacts

• Error handling and API error codes