How To Create and Send Envelopes with Documenso

13 nov. 2025

How to create and send envelopes with Documenso

As part of the Documenso 2.0 rollout, we’ve introduced a new Envelopes API. Envelopes are the natural progression of documents and templates, designed to simplify multi-document signing workflows.

Envelopes allow you to:

• Use multiple PDF files in a single workflow
• Avoid having to merge everything into one large PDF
• Work with either document or template envelope types

The envelopes API is available under our v2 API which has now exited beta with the release of Documenso 2.0!

In this article, we'll explore how you can create and configure envelopes via the API. We'll go over uploading multiple files, adding recipients, fields and configuring the meta information.

Creating an envelope

You create an envelope by making a POST request to the /api/v2/envelope/create endpoint with a multipart/form-data payload. The payload must contain the following fields at the minimum:

• payload.title - The name you want to use for the envelope.
• payload.type - The type of the envelope you want to create. You can choose either DOCUMENT or TEMPLATE depending on the type of documents you want to send.

The request should also contain the files you want to send in the envelope. You can add multiple files to the request.

cURL example:

curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: multipart/form-data" \
-F 'payload={
  "type": "DOCUMENT",
  "title": "Envelope Full Field Test"
}' \
-F "files=@./your-first-pdf.pdf;type=application/pdf" \
-F "files=@./your-second-pdf.pdf;type=application/pdf"

Node.js Fetch example:

import fs from "fs";
import path from "path";

const __dirname = path.resolve();
const endpoint = "https://app.documenso.com/api/v2/envelope/create";
const token = "<YOUR_TOKEN>";

const firstPDF = fs.readFileSync(path.join(__dirname, "./your-first-pdf.pdf"));
const secondPDF = fs.readFileSync(path.join(__dirname, "./your-second-pdf.pdf"));

const formData = new FormData();
formData.append("payload", JSON.stringify({
  type: "DOCUMENT",
  title: "Envelope Full Field Test"
}));
formData.append("files", new File([firstPDF], "first-pdf.pdf", { type: "application/pdf" }));
formData.append("files", new File([secondPDF], "second-pdf.pdf", { type: "application/pdf" }));

const response = await fetch(endpoint, {
  method: "POST",
  body: formData,
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Once you run either code, you should receive a response with the ID of the envelope and should be able to see the envelope in the UI.

Adding recipients

You can add multiple recipients to an envelope by providing the recipients field in the payload, which is an array of objects with the following properties:

• email (required)
• name (required)
• role (required) - Options: SIGNER, APPROVER, CC, VIEWER, APPROVER, ASSISTANT.
• signingOrder (optional) - The order in which the recipient will sign the envelope.

cURL example:

curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: multipart/form-data" \
-F 'payload={
  "type": "DOCUMENT",
  "title": "Envelope Full Field Test",
  "recipients": [
    {
      "email": "signer-first@documenso.com",
      "name": "Signer First",
      "role": "SIGNER",
      "signingOrder": 2
    },
    {
      "email": "signer-second@documenso.com",
      "name": "Signer Second",
      "role": "APPROVER",
      "signingOrder": 1
    }
  ]
}' \
-F "files=@./your-first-pdf.pdf;type=application/pdf" \
-F "files=@./your-second-pdf.pdf;type=application/pdf"

Adding fields

You can add one or more fields to a recipient by providing the fields field in the payload. The fields property is an array of objects with the following properties:

• type (required) - The type of the field you want to add. The available options are: SIGNATURE, FREE_SIGNATURE, INITIALS, NAME, EMAIL, DATE, TEXT, NUMBER, RADIO, CHECKBOX, DROPDOWN.
• page (required) - The page number of the field you want to add.
• positionX (required) - The X position of the field (0-100).
• positionY (required) - The Y position of the field (0-100).
• width (required) - The width of the field (0-100).
• height (required) - The height of the field (0-100).

cURL example:

curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
-H "Authorization: <YOUR_TOKEN>" \
-F 'payload={
  "type": "DOCUMENT",
  "title": "Envelope Full Field Test",
  "recipients": [
    {
      "email": "signer-first@documenso.com",
      "name": "Signer First",
      "role": "SIGNER",
      "signingOrder": 2,
      "fields": [
        {
          "type": "SIGNATURE",
          "page": 1,
          "positionX": 20,
          "positionY": 20,
          "width": 49,
          "height": 4.9
        }
      ]
    }
  ]
}' \
-F "files=@./your-first-pdf.pdf;type=application/pdf" \
-F "files=@./your-second-pdf.pdf;type=application/pdf"

Adding meta information

You can further configure the envelope by providing the meta field in the payload. The meta property is an object with properties such as:

• subject
• message
• timezone
• dateFormat

Sending the envelope

Once you created and configured the envelope to your liking, you can send it to the recipients using the api/v2/envelope/distribute endpoint.

cURL example:

curl "https://app.documenso.com/api/v2/envelope/distribute" \
-X POST \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
--data '{
  "envelopeId": "envelope_meswwzicykehufle"
}'

Completed envelopes retrieval

Once the envelope is completed, you can download its documents individually with a GET request to the api/v2/envelope/item/{envelopeItemId}/download endpoint.