Skip to main content
API v1 is deprecated, but will continue to be supported. For new integrations, please use API v2.

​
Base URL

https://app.documenso.com/api/v1
For self-hosted instances, replace with your instance URL.

​
Authentication

All API v1 requests require an API key in the Authorization header. The API supports both bearer token format and direct token format: 
# Bearer token format (recommended)
Authorization: Bearer api_xxxxxxxxxxxxxxxx

# Direct token format
Authorization: api_xxxxxxxxxxxxxxxx

​
Creating an API Token

  1. Log in to your Documenso account
  2. Navigate to Settings > API Tokens
  3. Click “Create API Token”
  4. Give your token a descriptive name
  5. Copy the token immediately (it will only be shown once)
API tokens are tied to a specific team. Make sure you’re in the correct team context when creating tokens.

​
Quick Start

Here’s a complete example of creating and sending a document: 
import { initClient } from '@ts-rest/core';
import { ApiContractV1 } from '@documenso/api/v1/contract';

const client = initClient(ApiContractV1, {
  baseUrl: 'https://app.documenso.com/api/v1',
  baseHeaders: {
    authorization: 'Bearer api_xxxxxxxxxxxxxxxx',
  },
});

// 1. Create a document
const { status, body } = await client.createDocument({
  body: {
    title: 'Service Agreement',
    recipients: [
      {
        name: 'John Doe',
        email: 'john@example.com',
        role: 'SIGNER',
      },
    ],
    meta: {
      subject: 'Please sign this document',
      message: 'Hi {signer.name}, please sign the following document.',
    },
  },
});

const { uploadUrl, documentId } = body;

// 2. Upload the PDF
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/octet-stream' },
  body: pdfBuffer,
});

// 3. Add fields
await client.createField({
  params: { id: documentId.toString() },
  body: {
    type: 'SIGNATURE',
    recipientId: body.recipients[0].recipientId,
    pageNumber: 1,
    pageX: 10,
    pageY: 80,
    pageWidth: 30,
    pageHeight: 5,
  },
});

// 4. Send the document
await client.sendDocument({
  params: { id: documentId.toString() },
  body: { sendEmail: true },
});

​
API Endpoints

​
Documents

  • GET /api/v1/documents - List all documents
  • GET /api/v1/documents/:id - Get a single document
  • POST /api/v1/documents - Create a new document
  • DELETE /api/v1/documents/:id - Delete a document
  • POST /api/v1/documents/:id/send - Send document for signing
  • POST /api/v1/documents/:id/resend - Resend to specific recipients
  • GET /api/v1/documents/:id/download - Download signed document

​
Templates

  • GET /api/v1/templates - List all templates
  • GET /api/v1/templates/:id - Get a single template
  • POST /api/v1/templates - Create a new template
  • DELETE /api/v1/templates/:id - Delete a template
  • POST /api/v1/templates/:templateId/generate-document - Generate document from template

​
Recipients

  • POST /api/v1/documents/:id/recipients - Add a recipient
  • PATCH /api/v1/documents/:id/recipients/:recipientId - Update a recipient
  • DELETE /api/v1/documents/:id/recipients/:recipientId - Remove a recipient

​
Fields

  • POST /api/v1/documents/:id/fields - Add field(s) to a document
  • PATCH /api/v1/documents/:id/fields/:fieldId - Update a field
  • DELETE /api/v1/documents/:id/fields/:fieldId - Remove a field

​
Response Formats

​
Successful Response

Successful requests return a 200 status code with a JSON body: 
{
  "id": 123,
  "title": "My Document",
  "status": "PENDING",
  "recipients": [...]
}

​
Error Response

Failed requests return an appropriate HTTP status code with an error message: 
{
  "message": "Document not found"
}

​
Common Status Codes

CodeDescription
200Success
400Bad request - invalid parameters
401Unauthorized - invalid or missing API key
404Not found - resource doesn’t exist
500Internal server error

​
OpenAPI Specification

The complete OpenAPI specification for API v1 is available at: 
https://app.documenso.com/api/v1/openapi.json
You can also view the interactive documentation at: 
https://openapi-v1.documenso.com

​
Rate Limits

API v1 requests are subject to rate limiting to ensure fair usage:
  • Rate limit: 100 requests per minute per API token
  • Burst limit: 10 requests per second
When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Best Practices

​
1. Error Handling

Always check the response status and handle errors appropriately: 
const { status, body } = await client.createDocument({ body: payload });

if (status !== 200) {
  console.error('Failed to create document:', body.message);
  throw new Error(body.message);
}

​
2. Idempotency

Use the externalId field to ensure idempotency: 
await client.createDocument({
  body: {
    title: 'Contract',
    externalId: 'order-12345', // Your unique identifier
    recipients: [...],
  },
});

​
3. Webhook Integration

Instead of polling for document status, use webhooks to receive real-time updates: 
// Configure webhooks in your account settings
// Listen for events like DOCUMENT_COMPLETED

​
Migration to v2

We recommend migrating to API v2 for new integrations. v2 offers improved performance, better error handling, and new features.

​
Key Differences

  1. Document Creation: v2 uses multipart/form-data instead of presigned URLs
  2. Endpoint Structure: v2 uses /api/v2/envelope instead of /api/v1/documents
  3. Field Positioning: v2 supports multiple file uploads with field identifiers
  4. Response Format: v2 includes pagination metadata and consistent error formats
See the v2 API documentation for details.

​
See Also