mirror of
https://github.com/documenso/documenso.git
synced 2026-08-15 02:53:32 +10:00
963 lines
28 KiB
Plaintext
963 lines
28 KiB
Plaintext
---
|
|
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';
|
|
|
|
<EnvelopeWarning />
|
|
|
|
<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`) |
|
|
| `secondaryId` | string | Legacy identifier in prefixed form (`document_123` for documents, `template_123` for templates) |
|
|
| `internalVersion` | number | Internal envelope schema version |
|
|
| `type` | string | `DOCUMENT` or `TEMPLATE` |
|
|
| `status` | string | Current status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, or `CANCELLED` |
|
|
| `title` | string | Document title |
|
|
| `source` | string | How the document was created: `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK` |
|
|
| `visibility` | string | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE` |
|
|
| `templateType` | string | Template visibility: `PUBLIC`, `PRIVATE`, or `ORGANISATION` (only meaningful for templates) |
|
|
| `externalId` | string \| null | Your custom identifier for the document |
|
|
| `userId` | number | ID of the user who owns the document |
|
|
| `teamId` | number | ID of the team the document belongs to |
|
|
| `folderId` | string \| null | ID of the folder containing the document |
|
|
| `templateId` | number \| null | Legacy ID of the template this document was created from |
|
|
| `authOptions` | object \| null | Access and action authentication requirements |
|
|
| `formValues` | object \| null | Pre-filled form values |
|
|
| `publicTitle` | string | Public title shown on profile and direct-link pages |
|
|
| `publicDescription` | string | Public description shown on profile and direct-link pages |
|
|
| `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 |
|
|
| `directLink` | object \| null | Direct-link signing configuration (`id`, `token`, `enabled`, `directTemplateRecipientId`) |
|
|
| `team` | object | Owning team (`id`, `url`) |
|
|
| `user` | object | Document owner (`id`, `name`, `email`) |
|
|
| `documentMeta` | object | Email settings, redirect URL, signing options |
|
|
|
|
Documents created through the API have `source: "DOCUMENT"` — there is no separate `API` source value. To tag documents created by your integration, set `externalId` when creating them.
|
|
|
|
### Example Document Object
|
|
|
|
```json
|
|
{
|
|
"id": "envelope_abc123xyz",
|
|
"secondaryId": "document_123",
|
|
"internalVersion": 2,
|
|
"type": "DOCUMENT",
|
|
"status": "PENDING",
|
|
"source": "DOCUMENT",
|
|
"visibility": "EVERYONE",
|
|
"templateType": "PRIVATE",
|
|
"title": "Service Agreement",
|
|
"externalId": "contract-2025-001",
|
|
"userId": 1,
|
|
"teamId": 1,
|
|
"folderId": null,
|
|
"templateId": null,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"publicTitle": "",
|
|
"publicDescription": "",
|
|
"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": 123,
|
|
"secondaryId": "field_abc123",
|
|
"type": "SIGNATURE",
|
|
"recipientId": 1,
|
|
"envelopeId": "envelope_abc123xyz",
|
|
"envelopeItemId": "envelope_item_xyz",
|
|
"page": 1,
|
|
"positionX": "10",
|
|
"positionY": "80",
|
|
"width": "30",
|
|
"height": "5",
|
|
"customText": "",
|
|
"inserted": false,
|
|
"fieldMeta": null
|
|
}
|
|
],
|
|
"envelopeItems": [
|
|
{
|
|
"id": "envelope_item_xyz",
|
|
"envelopeId": "envelope_abc123xyz",
|
|
"documentDataId": "doc_data_abc123",
|
|
"title": "contract.pdf",
|
|
"order": 1
|
|
}
|
|
],
|
|
"directLink": null,
|
|
"team": {
|
|
"id": 1,
|
|
"url": "your-team"
|
|
},
|
|
"user": {
|
|
"id": 1,
|
|
"name": "Jane Smith",
|
|
"email": "jane@example.com"
|
|
},
|
|
"documentMeta": {
|
|
"subject": "Please sign this document",
|
|
"message": "Hi, please review and sign this agreement.",
|
|
"timezone": "America/New_York",
|
|
"redirectUrl": "https://example.com/thank-you"
|
|
}
|
|
}
|
|
```
|
|
|
|
Field position and size values are stored as decimals and serialized as strings in API responses.
|
|
|
|
## 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`, `CANCELLED` |
|
|
| `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, count } = await response.json();
|
|
console.log(`Found ${count} 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"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"count": 42,
|
|
"currentPage": 1,
|
|
"perPage": 10,
|
|
"totalPages": 5
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
<Callout type="info">
|
|
This endpoint automatically scans uploaded PDFs for [placeholder patterns](/docs/users/documents/advanced/pdf-placeholders) like `{"{{signature, r1}}"}` and creates fields at those locations.
|
|
</Callout>
|
|
|
|
```
|
|
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>
|
|
|
|
---
|
|
|
|
## Cancel Document
|
|
|
|
Cancel a pending document. This changes its status from `PENDING` to `CANCELLED`.
|
|
|
|
```
|
|
POST /envelope/cancel
|
|
```
|
|
|
|
### Request Body
|
|
|
|
| Field | Type | Required | Description |
|
|
| ------------ | ------ | -------- | ----------------------------------- |
|
|
| `envelopeId` | string | Yes | Document ID |
|
|
| `reason` | string | No | Reason for cancelling the document |
|
|
|
|
### Code Examples
|
|
|
|
<Tabs items={['curl', 'TypeScript']}>
|
|
<Tab value="curl">
|
|
```bash
|
|
curl -X POST "https://app.documenso.com/api/v2/envelope/cancel" \
|
|
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"envelopeId": "envelope_abc123",
|
|
"reason": "The agreement is no longer needed."
|
|
}'
|
|
```
|
|
</Tab>
|
|
<Tab value="TypeScript">
|
|
```typescript
|
|
const response = await fetch('https://app.documenso.com/api/v2/envelope/cancel', {
|
|
method: 'POST',
|
|
headers: {
|
|
Authorization: 'api_xxxxxxxxxxxxxxxx',
|
|
'Content-Type': 'application/json',
|
|
},
|
|
body: JSON.stringify({
|
|
envelopeId: 'envelope_abc123',
|
|
reason: 'The agreement is no longer needed.',
|
|
}),
|
|
});
|
|
|
|
const { success } = await response.json();
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"success": true
|
|
}
|
|
```
|
|
|
|
### Behavior
|
|
|
|
- Only documents in `PENDING` status can be cancelled. Other statuses return `400`.
|
|
- Cancellation is not idempotent. Cancelling the same document again returns `400`.
|
|
- The document owner and team members with `MANAGER` or higher permissions can cancel it. Requests for documents you cannot view return `404`; requests for visible documents without sufficient permissions return `401`.
|
|
- A successful cancellation fires the `DOCUMENT_CANCELLED` webhook.
|
|
- Cancellation emails are sent only to eligible non-CC, non-rejected recipients who were sent or opened the document.
|
|
|
|
---
|
|
|
|
## 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 |
|
|
| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
|
|
| `ids` | object | Yes | ID selector containing `type` and `ids` |
|
|
| `ids.type` | string | Yes | `envelopeId`, `documentId`, or `templateId` |
|
|
| `ids.ids` | array | Yes | 1-20 IDs: strings for `envelopeId`; numbers for `documentId` or `templateId` |
|
|
|
|
### 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 '{
|
|
"ids": {
|
|
"type": "envelopeId",
|
|
"ids": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
|
|
}
|
|
}'
|
|
```
|
|
</Tab>
|
|
<Tab value="TypeScript">
|
|
```typescript
|
|
const requestedIds = ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'];
|
|
|
|
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({
|
|
ids: {
|
|
type: 'envelopeId',
|
|
ids: requestedIds,
|
|
},
|
|
}),
|
|
});
|
|
|
|
const { data } = await response.json();
|
|
|
|
```
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
### Response
|
|
|
|
```json
|
|
{
|
|
"data": [
|
|
{
|
|
"id": "envelope_abc123",
|
|
"type": "DOCUMENT",
|
|
"status": "PENDING",
|
|
"title": "Service Agreement"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The endpoint silently omits envelopes you cannot access instead of returning `404`. Compare `data.length` with `requestedIds.length` to detect omissions.
|
|
|
|
---
|
|
|
|
## 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. |
|
|
| `CANCELLED` | The document was cancelled by its owner or a team member with `MANAGER` or higher permissions. |
|
|
|
|
### Status Transitions
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
DRAFT --> PENDING --> COMPLETED
|
|
PENDING --> REJECTED
|
|
PENDING --> CANCELLED
|
|
```
|
|
|
|
- **DRAFT to PENDING**: Call the distribute endpoint
|
|
- **PENDING to COMPLETED**: All recipients complete their signing
|
|
- **PENDING to REJECTED**: A recipient rejects the document
|
|
- **PENDING to CANCELLED**: The document owner or a team member with `MANAGER` or higher permissions cancels 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`, `CANCELLED` | Filter by status |
|
|
| `source` | `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK` | 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, currentPage, totalPages } = await response.json();
|
|
documents.push(...data);
|
|
|
|
hasMore = currentPage < 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
|