Elgato_dark/documenso
1
0
Fork 0
mirror of https://github.com/documenso/documenso synced 2026-04-21 21:37:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
documenso/apps/docs/content/docs/developers/api/documents.mdx
Lucas Smith b92c53dbb2
feat: docs v2 (#2460) 
Co-authored-by: Catalin Pit <catalinpit@gmail.com>
2026-02-27 22:05:27 +11:00

815 lines
22 KiB
Text
Raw Blame History

---
title: Documents API
description: Create, manage, and send documents for signing via the API.
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Callout type="warn">
This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference,
see the [OpenAPI Reference](https://openapi.documenso.com).
</Callout>
## Overview
[Documents](/docs/users/documents) (called "envelopes" in the API) are the core resource in Documenso. You can:
1. create documents with recipients and fields
2. send them for signing
3. track their status
4. retrieve the completed PDFs
Each document contains one or more PDF files, a list of recipients, and the fields they need to fill.
## Document Object
A document object contains the following properties:
| Property | Type | Description |
| --------------- | -------------- | -------------------------------------------------------------- |
| `id` | string | Unique identifier (e.g., `envelope_abc123`) |
| `type` | string | `DOCUMENT` or `TEMPLATE` |
| `status` | string | Current status: `DRAFT`, `PENDING`, `COMPLETED`, or `REJECTED` |
| `title` | string | Document title |
| `source` | string | How the document was created: `DOCUMENT`, `TEMPLATE`, `API` |
| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` |
| `externalId` | string \| null | Your custom identifier for the document |
| `createdAt` | string | ISO 8601 timestamp |
| `updatedAt` | string | ISO 8601 timestamp |
| `completedAt` | string \| null | Timestamp when all recipients completed signing |
| `deletedAt` | string \| null | Timestamp if soft-deleted |
| `recipients` | array | List of recipients and their signing status |
| `fields` | array | Signature and form fields on the document |
| `envelopeItems` | array | PDF files attached to the document |
| `documentMeta` | object | Email settings, redirect URL, signing options |
### Example Document Object
```json
{
"id": "envelope_abc123xyz",
"type": "DOCUMENT",
"status": "PENDING",
"source": "API",
"visibility": "EVERYONE",
"title": "Service Agreement",
"externalId": "contract-2025-001",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:35:00.000Z",
"completedAt": null,
"deletedAt": null,
"recipients": [
{
"id": 1,
"email": "signer@example.com",
"name": "John Smith",
"role": "SIGNER",
"signingStatus": "NOT_SIGNED",
"signingOrder": 1
}
],
"fields": [
{
"id": "field_123",
"type": "SIGNATURE",
"page": 1,
"positionX": 10,
"positionY": 80,
"width": 30,
"height": 5,
"recipientId": 1
}
],
"envelopeItems": [
{
"id": "envelope_item_xyz",
"title": "contract.pdf",
"order": 1
}
],
"documentMeta": {
"subject": "Please sign this document",
"message": "Hi, please review and sign this agreement.",
"timezone": "America/New_York",
"redirectUrl": "https://example.com/thank-you"
}
}
```
## List Documents
Retrieve a paginated list of documents.
```
GET /envelope
```
### Query Parameters
| Parameter | Type | Description |
| ------------------ | ------- | ------------------------------------------------------------- |
| `page` | integer | Page number (default: 1) |
| `perPage` | integer | Results per page (default: 10, max: 100) |
| `type` | string | Filter by `DOCUMENT` or `TEMPLATE` |
| `status` | string | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` |
| `source` | string | Filter by creation source |
| `folderId` | string | Filter by folder ID |
| `orderByColumn` | string | Sort field (only `createdAt` supported) |
| `orderByDirection` | string | Sort direction: `asc` or `desc` (default: `desc`) |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
# List all documents
curl -X GET "https://app.documenso.com/api/v2/envelope" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
# Filter by status and paginate
curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING&page=1&perPage=20" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
# List only documents (not templates)
curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
````
</Tab>
<Tab value="TypeScript">
```typescript
const API_TOKEN = process.env.DOCUMENSO_API_TOKEN;
const BASE_URL = 'https://app.documenso.com/api/v2';
// List all documents
const response = await fetch(`${BASE_URL}/envelope`, {
method: 'GET',
headers: {
Authorization: API_TOKEN,
},
});
const { data, pagination } = await response.json();
console.log(`Found ${pagination.totalItems} documents`);
// Filter by status
const pendingResponse = await fetch(
`${BASE_URL}/envelope?status=PENDING&page=1&perPage=20`,
{
method: 'GET',
headers: {
Authorization: API_TOKEN,
},
}
);
const pendingDocs = await pendingResponse.json();
````
</Tab>
</Tabs>
### Response
```json
{
"data": [
{
"id": "envelope_abc123",
"type": "DOCUMENT",
"status": "PENDING",
"title": "Service Agreement",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:35:00.000Z",
"recipients": [
{
"id": 1,
"email": "signer@example.com",
"name": "John Smith",
"role": "SIGNER",
"signingStatus": "NOT_SIGNED"
}
]
}
],
"pagination": {
"page": 1,
"perPage": 10,
"totalPages": 5,
"totalItems": 42
}
}
```
---
## Get Document
Retrieve a single document by ID.
```
GET /envelope/{envelopeId}
```
### Path Parameters
| Parameter | Type | Description |
| ------------ | ------ | ----------------------------------------- |
| `envelopeId` | string | The document ID (e.g., `envelope_abc123`) |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X GET "https://app.documenso.com/api/v2/envelope/envelope_abc123" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
```
</Tab>
<Tab value="TypeScript">
```typescript
const envelopeId = 'envelope_abc123';
const response = await fetch(`https://app.documenso.com/api/v2/envelope/${envelopeId}`, {
method: 'GET',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
},
});
const document = await response.json();
console.log(document.title, document.status);
````
</Tab>
</Tabs>
### Response
Returns the full document object including recipients, fields, and envelope items.
```json
{
"id": "envelope_abc123",
"type": "DOCUMENT",
"status": "PENDING",
"title": "Service Agreement",
"recipients": [...],
"fields": [...],
"envelopeItems": [...],
"documentMeta": {...}
}
````
---
## Create Document
Create a new document with optional recipients and fields in a single request.
```
POST /envelope/create
Content-Type: multipart/form-data
```
### Request Body
The request uses `multipart/form-data` with two parts:
| Part | Type | Description |
| --------- | ------- | ---------------------- |
| `payload` | JSON | Document configuration |
| `files` | File(s) | One or more PDF files |
### Payload Schema
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------- |
| `type` | string | Yes | Must be `DOCUMENT` |
| `title` | string | Yes | Document title |
| `externalId` | string | No | Your custom identifier |
| `visibility` | string | No | `EVERYONE`, `ADMIN`, or `MANAGER_AND_ABOVE` |
| `folderId` | string | No | Folder ID to create the document in |
| `recipients` | array | No | Recipients with optional fields |
| `meta` | object | No | Email subject, message, redirect URL, etc. |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: multipart/form-data" \
-F 'payload={
"type": "DOCUMENT",
"title": "Service Agreement",
"externalId": "contract-2025-001",
"recipients": [
{
"email": "signer@example.com",
"name": "John Smith",
"role": "SIGNER",
"fields": [
{
"identifier": 0,
"type": "SIGNATURE",
"page": 1,
"positionX": 10,
"positionY": 80,
"width": 30,
"height": 5
},
{
"identifier": 0,
"type": "DATE",
"page": 1,
"positionX": 50,
"positionY": 80,
"width": 20,
"height": 3
}
]
}
],
"meta": {
"subject": "Please sign this agreement",
"message": "Hi John, please review and sign the attached agreement.",
"redirectUrl": "https://example.com/thank-you"
}
}' \
-F "files=@./contract.pdf;type=application/pdf"
```
</Tab>
<Tab value="TypeScript">
```typescript
import fs from 'fs';
import FormData from 'form-data';
const form = new FormData();
const payload = {
type: 'DOCUMENT',
title: 'Service Agreement',
externalId: 'contract-2025-001',
recipients: [
{
email: 'signer@example.com',
name: 'John Smith',
role: 'SIGNER',
fields: [
{
identifier: 0,
type: 'SIGNATURE',
page: 1,
positionX: 10,
positionY: 80,
width: 30,
height: 5,
},
{
identifier: 0,
type: 'DATE',
page: 1,
positionX: 50,
positionY: 80,
width: 20,
height: 3,
},
],
},
],
meta: {
subject: 'Please sign this agreement',
message: 'Hi John, please review and sign the attached agreement.',
redirectUrl: 'https://example.com/thank-you',
},
};
form.append('payload', JSON.stringify(payload));
form.append('files', fs.createReadStream('./contract.pdf'), {
contentType: 'application/pdf',
});
const response = await fetch('https://app.documenso.com/api/v2/envelope/create', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
},
body: form,
});
const { id } = await response.json();
console.log('Created document:', id);
````
</Tab>
</Tabs>
### Response
```json
{
"id": "envelope_abc123xyz"
}
````
### Field Positioning
Field positions use percentage values (0-100) relative to the PDF page:
| Parameter | Description |
| ------------ | ---------------------------------------------------------- |
| `positionX` | Horizontal position from left edge (0 = left, 100 = right) |
| `positionY` | Vertical position from top edge (0 = top, 100 = bottom) |
| `width` | Field width as percentage of page width |
| `height` | Field height as percentage of page height |
| `page` | Page number (1-indexed) |
| `identifier` | File index (0 for first file) or filename |
### Field Types
| Type | Description |
| ----------- | --------------------------- |
| `SIGNATURE` | Signature field |
| `INITIALS` | Initials field |
| `NAME` | Auto-filled recipient name |
| `EMAIL` | Auto-filled recipient email |
| `DATE` | Signing date |
| `TEXT` | Free text input |
| `NUMBER` | Numeric input |
| `CHECKBOX` | Checkbox selection |
| `RADIO` | Radio button group |
| `DROPDOWN` | Dropdown selection |
### Recipient Roles
| Role | Description |
| ---------- | ----------------------------------------- |
| `SIGNER` | Must sign the document |
| `APPROVER` | Must approve before signers can sign |
| `CC` | Receives a copy but doesn't sign |
| `VIEWER` | Can view the document but takes no action |
---
## Update Document
Update a document's properties. Only works on documents in `DRAFT` status.
```
POST /envelope/update
```
### Request Body
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------ |
| `envelopeId` | string | Yes | Document ID |
| `data` | object | No | Document properties to update |
| `meta` | object | No | Email and signing settings to update |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/update" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"envelopeId": "envelope_abc123",
"data": {
"title": "Updated Service Agreement",
"externalId": "contract-2025-001-v2"
},
"meta": {
"subject": "Updated: Please sign this agreement",
"redirectUrl": "https://example.com/signed"
}
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/envelope/update', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
envelopeId: 'envelope_abc123',
data: {
title: 'Updated Service Agreement',
externalId: 'contract-2025-001-v2',
},
meta: {
subject: 'Updated: Please sign this agreement',
redirectUrl: 'https://example.com/signed',
},
}),
});
const document = await response.json();
```
</Tab>
</Tabs>
---
## Send Document
Send a document to recipients for signing. This changes the status from `DRAFT` to `PENDING`.
```
POST /envelope/distribute
````
### Request Body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `envelopeId` | string | Yes | Document ID |
| `meta` | object | No | Override email settings for this send |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
# Basic send
curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"envelopeId": "envelope_abc123"
}'
# Send with custom email settings
curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"envelopeId": "envelope_abc123",
"meta": {
"subject": "Action Required: Sign Agreement",
"message": "Please sign this document by end of day.",
"timezone": "America/New_York"
}
}'
````
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/envelope/distribute', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
envelopeId: 'envelope_abc123',
meta: {
subject: 'Action Required: Sign Agreement',
message: 'Please sign this document by end of day.',
},
}),
});
const { id, recipients } = await response.json();
// Recipients now include signing URLs
recipients.forEach((r) => {
console.log(`${r.email}: ${r.signingUrl}`);
});
````
</Tab>
</Tabs>
### Response
The response includes signing URLs for each recipient:
```json
{
"success": true,
"id": "envelope_abc123",
"recipients": [
{
"id": 1,
"name": "John Smith",
"email": "signer@example.com",
"token": "abc123xyz",
"role": "SIGNER",
"signingOrder": 1,
"signingUrl": "https://app.documenso.com/sign/abc123xyz"
}
]
}
````
<Callout type="info">
Use the `signingUrl` to redirect recipients directly to the signing page, or let them use the
email link.
</Callout>
---
## Delete Document
Delete a document. Completed documents cannot be deleted.
```
POST /envelope/delete
```
### Request Body
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `envelopeId` | string | Yes | Document ID |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/delete" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"envelopeId": "envelope_abc123"
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/envelope/delete', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
envelopeId: 'envelope_abc123',
}),
});
const { success } = await response.json();
````
</Tab>
</Tabs>
### Response
```json
{
"success": true
}
````
---
## Get Multiple Documents
Retrieve multiple documents by their IDs in a single request.
```
POST /envelope/get-many
```
### Request Body
| Field | Type | Required | Description |
| ------------- | ----- | -------- | --------------------- |
| `envelopeIds` | array | Yes | Array of document IDs |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/get-many" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"envelopeIds": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
envelopeIds: ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'],
}),
});
const documents = await response.json();
````
</Tab>
</Tabs>
---
## Document Statuses
| Status | Description |
| --- | --- |
| `DRAFT` | Document is being prepared. Recipients have not been notified. |
| `PENDING` | Document has been sent. Waiting for recipients to sign. |
| `COMPLETED` | All recipients have signed. Document is sealed. |
| `REJECTED` | A recipient rejected the document. |
### Status Transitions
```mermaid
flowchart LR
DRAFT --> PENDING --> COMPLETED
PENDING --> REJECTED
```
- **DRAFT to PENDING**: Call the distribute endpoint
- **PENDING to COMPLETED**: All recipients complete their signing
- **PENDING to REJECTED**: A recipient rejects the document
<Callout type="warn">
You cannot modify recipients or fields after a document moves to `PENDING` status.
</Callout>
---
## Filtering and Pagination
### Pagination Parameters
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | --------------------------- |
| `page` | integer | 1 | Page number |
| `perPage` | integer | 10 | Results per page (max: 100) |
### Filter Parameters
| Parameter | Values | Description |
| ---------- | ------------------------------------------- | ------------------------- |
| `type` | `DOCUMENT`, `TEMPLATE` | Filter by envelope type |
| `status` | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` | Filter by status |
| `source` | `DOCUMENT`, `TEMPLATE`, `API` | Filter by creation source |
| `folderId` | string | Filter by folder |
### Sorting
| Parameter | Values | Description |
| ------------------ | ------------- | -------------------------------- |
| `orderByColumn` | `createdAt` | Field to sort by |
| `orderByDirection` | `asc`, `desc` | Sort direction (default: `desc`) |
### Example: Fetch All Pending Documents
```typescript
async function getAllPendingDocuments() {
const documents = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://app.documenso.com/api/v2/envelope?status=PENDING&page=${page}&perPage=100`,
{
headers: { Authorization: 'api_xxxxxxxxxxxxxxxx' },
},
);
const { data, pagination } = await response.json();
documents.push(...data);
hasMore = page < pagination.totalPages;
page++;
}
return documents;
}
```
---
## See Also
- [Recipients API](/docs/developers/api/recipients) - Add and manage document recipients
- [Fields API](/docs/developers/api/fields) - Add signature and form fields
- [Templates API](/docs/developers/api/templates) - Create reusable document templates
- [Webhooks](/docs/developers/webhooks) - Get notified when documents are signed
Reference in a new issue View git blame Copy permalink