documenso/apps/documentation/pages/developers/public-api/reference.mdx

---
title: API Reference
description: Reference documentation for the Documenso public API.
---

import { Callout, Steps } from 'nextra/components';

# API Reference

On this page we will refer to both Documents and Templates as Envelopes for convenience, unless otherwise specified.

<Callout type="info">
  This page is used to demonstrate some of the endpoints and how to use them. For the full API
  reference, please see the [API Reference](https://openapi.documenso.com/).
</Callout>

## Get Envelope

For the vast majority of use cases, you will need to retrieve the envelope to get details for further operations.

The main details you generally want to extract are the following:

- **Recipients** - The individuals who will be signing the document
- **Fields** - The fields the user will sign
- **Items** - The PDF files the user will see and sign

This is done by doing a the following GET [request](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/create)

```sh
curl -X GET "https://app.documenso.com/api/v2/envelope/envelope_xxxxxxxxxxxxx" \
  -H "Authorization: api_xxxxxxxxxxxxxx"
```

A successful response looks as follows:

```json
{
  "internalVersion": 2,
  "type": "TEMPLATE",
  "status": "DRAFT",
  "source": "TEMPLATE",
  "visibility": "EVERYONE",
  "templateType": "PRIVATE",
  "id": "envelope_xxxxxxxxxxxxxxxx",
  "secondaryId": "template_9",
  "externalId": null,
  "createdAt": "2025-11-12T11:36:38.391Z",
  "updatedAt": "2025-11-12T11:36:55.648Z",
  "completedAt": null,
  "deletedAt": null,
  "title": "Title",
  "recipients": [
    {
      "envelopeId": "envelope_xxxxxxxxxxxxxxxx",
      "role": "SIGNER",
      "readStatus": "NOT_OPENED",
      "signingStatus": "NOT_SIGNED",
      "sendStatus": "NOT_SENT",
      "id": 0,
      "email": "recipient+1@documenso.com",
      "name": "",
      "token": "cxH2Ss79Hj94M1U3PxRAG",
      "documentDeletedAt": null,
      "expired": null,
      "signedAt": null,
      "authOptions": {
        "accessAuth": [],
        "actionAuth": []
      },
      "signingOrder": 1,
      "rejectionReason": null
    }
  ]
  "envelopeItems": [
    {
      "envelopeId": "envelope_xxxxxxxxxxxxxxxx",
      "id": "envelope_item_xxxxxxxxxxxxxxxxx",
      "title": "FileOne",
      "order": 1
    }
  ],
  // Other attributes
}
```

## Create Envelope

This example request will create a document with the following:

- Two PDF files
- Two recipients with one field each

You will need to:

- Replace api_xxxxxxxxxxxxxx with your API key
- Replace the file paths with the actual paths to your files

Note that the identifier on a field is linking to the files you upload. It can either be the index of the file or the filename. In this example it uses the index of the file.

```sh
curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
  -H "Authorization: api_xxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "type": "DOCUMENT",
    "title": "Envelope Full Field Test",
    "recipients": [
      {
        "email": "recipient+1@example.com",
        "name": "Recipient One",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 0,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 0,
            "positionY": 0,
            "width": 50,
            "height": 50
          }
        ]
      },
      {
        "email": "recipient-2@example.com",
        "name": "Recipient Two",
        "role": "SIGNER",
        "fields": [
          {
            "identifier": 1,
            "type": "SIGNATURE",
            "page": 1,
            "positionX": 0,
            "positionY": 0,
            "width": 50,
            "height": 50
          }
        ]
      }
    ]
  }' \
  -F "files=@./field-font-alignment.pdf;type=application/pdf" \
  -F "files=@./field-meta.pdf;type=application/pdf"
```

<Callout type="info">
  See the full request and response formats for the create endpoint
  [here](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/create)
</Callout>

## Use Template

Documenso allows you to generate documents from templates. This is useful when you have a standard document format you want to reuse.

The API endpoint for generating a document from a template is `/api/v2/envelopes/use`, and it takes a JSON payload with the following fields:

<Callout type="info">
  See the full request and response formats for the use endpoint
  [here](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/use)
</Callout>

<Steps>

### Grab the Template ID

The first step is to retrieve the ID of the template you want to use. This can be done via the API or from the Documenso UI.

You can get the ID by navigating to the template page and looking at the URL. The ID is the last part of the URL which looks like this "envelope_xxxxxxxx"

### Retrieve the Recipient(s) ID(s)

Once you have the template ID, you will want to retrieve the full template so you can see the recipients.

This is optional, and you only will want to do this if you want to modify the recipient details prior to creating the new document.

See the [Get Envelope](#get-envelope) section for more details on how to retrieve the envelope.

### Generate the Document

To generate a document from the template, you need to make a POST request to the [`/api/v2/envelope/use`](https://openapi.documenso.com/reference#tag/envelope/POST/envelope/use) endpoint.

You will need to replace the following:

- `api_xxxxxxxxxxxxxx` with your API key
- `envelope_xxxxxxxxxxxxxxx` with the template ID
- `RECIPIENT_ID_HERE` with the recipient ID you want to modify prior to sending
- `RECIPIENT_EMAIL_HERE` with the new recipient email you want to use
- `RECIPIENT_NAME_HERE` with the new recipient name you want to use

If you want to send the document immediately, you can add the `distributeDocument` parameter to the payload.

```sh
curl -X POST "https://app.documenso.com/api/v2/envelope/use" \
  -H "Authorization: api_xxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "envelopeId": "envelope_xxxxxxxxxxxxxxx",
    "recipients": [
      {
        "id": RECIPIENT_ID_HERE,
        "email": "RECIPIENT_EMAIL_HERE",
        "name": "RECIPIENT_NAME_HERE"
      }
    ]
  }'
```

#### Generate the Document with Custom Files

You can also generate a document from a template using custom PDF files to replace the template's default PDF files.

To do this, you will need to grab the `envelopeItemId` of the item you want to replace, this is found in the GET request in the previous step.

You will need to replace the following:

- `CUSTOM_FILE_NAME_HERE.pdf` with the custom file name
- `envelope_item_xxxxxxxxxxxxxxxxx` with the `envelopeItemId` of the item you want to replace

```sh
curl -X POST "https://app.documenso.com/api/v2/envelope/use" \
  -H "Authorization: api_xxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
    "envelopeId": "envelope_xxxxxxxxxxxxxxx",
    "recipients": [
      {
        "id": RECIPIENT_ID_HERE,
        "email": "RECIPIENT_EMAIL_HERE",
        "name": "RECIPIENT_NAME_HERE"
      }
    ],
    "customDocumentData": [
      {
        "identifier": "CUSTOM_FILE_NAME_HERE.pdf",
        "envelopeItemId": "envelope_item_xxxxxxxxxxxxxxxxx"
      }
    ]
  }' \
  -F "files=@./CUSTOM_FILE_NAME_HERE.pdf;type=application/pdf"
```

You can now access the document in your Documenso account dashboard.

#### Pre-fill Fields On Document Creation

The API allows you to pre-fill fields on document creation. This is useful when you want to create a document from an existing template and pre-fill the fields with specific values.

```json
{
  "prefillFields": [
    {
      "id": 21,
      "type": "text",
      "label": "my-label",
      "placeholder": "my-placeholder",
      "value": "my-value"
    },
    {
      "id": 22,
      "type": "number",
      "label": "my-label",
      "placeholder": "my-placeholder",
      "value": "123"
    },
    {
      "id": 23,
      "type": "checkbox",
      "label": "my-label",
      "placeholder": "my-placeholder",
      "value": ["option-1", "option-2"]
    }
  ]
  // Other payload properties...
}
```

</Steps>

## Add Recipients

The API allows you to add recipients to an envelope via the [`/api/v2/envelope/recipient/create-many`](https://openapi.documenso.com/reference#tag/envelope-recipients/POST/envelope/recipient/create-many) endpoint.

The following is an example of a request which creates 2 new recipients on the envelope.

```sh
curl https://app.documenso.com/api/v2/envelope/recipient/create-many \
  --request POST \
  --header 'Authorization: api_xxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "envelopeId": "envelope_brxkyaxywuxkyeuv",
    "data": [
      {
        "name": "Recipient Name",
        "email": "example@documenso.com",
        "role": "SIGNER"
      },
      {
        "name": "Recipient Two",
        "email": "example+2@documenso.com",
        "role": "APPROVER"
      }
    ]
  }'
```

## Add Fields

The API allows you to add fields to an envelope via the [`/api/v2/envelope/field/create-many`](https://openapi.documenso.com/reference#tag/envelope-fields/POST/envelope/field/create-many) endpoint.

Before adding fields to an envelope, you will need the following details:

- **Envelope ID** - Which envelope the field will be added to
- **Recipient ID** - Which recipient the field will be added to
- **Envelope Item ID** - Which file the field will be added to. If blank, the field will be added to the first file.

See the [Get Envelope](#get-envelope) section for more details on how to retrieve these details.

### Coordinate-Based Positioning

The following is an example of a request which creates 2 new fields on the first page of the envelope.

Note that width, height, positionX and positionY are percentage numbers between 0 and 100, which scale the field relative to the size of the PDF.

```sh
curl https://app.documenso.com/api/v2/envelope/field/create-many \
  --request POST \
  --header 'Authorization: api_xxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "envelopeId": "envelope_xxxxxxxxxx",
    "data": [
      {
        "recipientId": recipient_id_here,
        "envelopeItemId": "envelope_item_id_here",
        "type": "TEXT",
        "page": 1,
        "positionX": 0,
        "positionY": 0,
        "width": 50,
        "height": 50,
        "fieldMeta": {
          "type": "text",
          "label": "First test field"
        }
      },
      {
        "recipientId": recipient_id_here,
        "envelopeItemId": "envelope_item_id_here",
        "type": "TEXT",
        "page": 1,
        "positionX": 50,
        "positionY": 50,
        "width": 50,
        "height": 50,
        "fieldMeta": {
          "type": "text",
          "label": "Second test field"
        }
      }
    ]
  }'
```

### Placeholder-Based Positioning

Instead of specifying exact coordinates, you can position fields using placeholder text in the PDF. The API will search for the text and place the field at that location.

This is useful when:

- You have PDFs with designated placeholder text (e.g., `{{signature}}`, `[SIGN HERE]`)
- You want field positions to adapt to document content changes
- You're working with templated documents generated from other systems

```sh
curl https://app.documenso.com/api/v2/envelope/field/create-many \
  --request POST \
  --header 'Authorization: api_xxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "envelopeId": "envelope_xxxxxxxxxx",
    "data": [
      {
        "recipientId": recipient_id_here,
        "type": "SIGNATURE",
        "placeholder": "{{signature}}"
      },
      {
        "recipientId": recipient_id_here,
        "type": "NAME",
        "placeholder": "{{name}}",
        "width": 30,
        "height": 5
      }
    ]
  }'
```

#### Placeholder Parameters

| Parameter     | Type    | Required | Description                                                                                                      |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `placeholder` | string  | Yes      | Text to search for in the PDF. The field is placed at the location of this text.                                 |
| `width`       | number  | No       | Override the field width (percentage). If omitted, uses the placeholder text width.                              |
| `height`      | number  | No       | Override the field height (percentage). If omitted, uses the placeholder text height.                            |
| `matchAll`    | boolean | No       | When `true`, creates a field at every occurrence of the placeholder. Default is `false` (first occurrence only). |

<Callout type="info">
  The placeholder text is automatically covered with a white rectangle after field creation, so it
  won't appear in the final signed document.
</Callout>

#### Multiple Occurrences

If your PDF contains the same placeholder text multiple times (e.g., initials on every page), use `matchAll: true` to create fields at all occurrences:

```json
{
  "recipientId": 123,
  "type": "INITIALS",
  "placeholder": "{{initials}}",
  "matchAll": true
}
```

This will create one INITIALS field for each occurrence of `{{initials}}` in the PDF.

#### Mixing Positioning Methods

You can combine coordinate-based and placeholder-based positioning in the same request:

```json
{
  "envelopeId": "envelope_xxxxxxxxxx",
  "data": [
    {
      "recipientId": 123,
      "type": "SIGNATURE",
      "placeholder": "{{signature}}"
    },
    {
      "recipientId": 123,
      "type": "DATE",
      "page": 1,
      "positionX": 70,
      "positionY": 85,
      "width": 20,
      "height": 3
    }
  ]
}
```

Field meta allows you to further configure fields, for example it will allow you to add multiple items for checkboxes or radios.

A successful request will return a JSON response with the newly added fields.