API Reference

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

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 (opens in a new tab).

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 (opens in a new tab)

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

A successful response looks as follows:

{
  "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.

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"

See the full request and response formats for the create endpoint here (opens in a new tab)

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:

See the full request and response formats for the use endpoint here (opens in a new tab)

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 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 (opens in a new tab) 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.

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

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.

{
  "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...
}

Add Recipients

The API allows you to add recipients to an envelope via the /api/v2/envelope/recipient/create-many (opens in a new tab) endpoint.

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

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 (opens in a new tab) 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 section for more details on how to retrieve these details.

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.

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"
        }
      }
    ]
  }'

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.

Versioning Get Started