# 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:**

```bash
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:**

```javascript
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:**

```bash
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:**

```bash
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:**

```bash
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.