Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2025-11-14 00:32:43 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
47466a2db9e28176098d17dacff9e569d9159ec7
documenso/apps/documentation/pages/developers/public-api/reference.mdx
David Nguyen 4304fc1d35 chore: add envelope docs (#2186)
2025-11-13 11:50:06 +11:00

366 lines
11 KiB
Plaintext
Raw Blame History

---
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.
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"
}
}
]
}'
```
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.
Reference in New Issue View Git Blame Copy Permalink