Skip to main content

​
Overview

Documenso uses API versioning to manage changes and ensure backward compatibility for existing integrations. The version is specified in the URL path.
The current recommended API version is v2. API v1 is deprecated but will continue to be supported.

​
API Versions

​
API v2 (Current)

Base URL: https://app.documenso.com/api/v2
  • Status: Active and recommended for all new integrations
  • Features:
    • Multipart file uploads
    • Improved error handling
    • Enhanced field positioning
    • Better pagination support
    • Consistent response formats
    • Multiple file support per document
Documentation: API v2 Reference

​
API v1 (Deprecated)

Base URL: https://app.documenso.com/api/v1
  • Status: Deprecated but supported
  • Features:
    • Presigned URL for file uploads
    • Basic document operations
    • Template support
    • Field and recipient management
While API v1 will continue to work, we strongly recommend migrating to v2 for new integrations. API v1 will receive only critical security updates and bug fixes.
Documentation: This section covers API v1

​
Deprecation Policy

When we deprecate an API version or specific endpoint:
  1. Announcement: We announce the deprecation in release notes and via email to registered developers
  2. Deprecation Period: The deprecated version continues to work for at least 12 months
  3. Migration Guide: We provide detailed migration guides and examples
  4. Support: We offer support during the transition period
  5. Sunset: After the deprecation period, the endpoint may be removed

​
API v1 Deprecation Timeline

  • Announced: March 2024
  • Deprecation Start: June 2024
  • Minimum Support Until: June 2025
  • Status: All v1 endpoints continue to function as documented

​
Versioning Strategy

​
URL-Based Versioning

We use URL-based versioning for clarity and simplicity: 
https://app.documenso.com/api/v1/documents
https://app.documenso.com/api/v2/envelope
This makes it easy to:
  • Switch between versions during migration
  • Run v1 and v2 in parallel
  • Test new features without affecting production

​
Breaking vs Non-Breaking Changes

Non-breaking changes may be made within a version:
  • Adding new optional parameters
  • Adding new endpoints
  • Adding new fields to responses
  • Improving error messages
Breaking changes require a new version:
  • Removing or renaming endpoints
  • Removing or renaming request/response fields
  • Changing field types or validation rules
  • Changing authentication mechanisms

​
Migration from v1 to v2

​
Key Differences

Featurev1v2
Base Path/api/v1/api/v2
Documents Endpoint/documents/envelope
File UploadPresigned URL (2-step)Multipart (1-step)
Field IdentifierPage number onlyPage number + file identifier
Multiple FilesNot supportedSupported
PaginationBasicEnhanced with metadata
Error FormatBasicConsistent structure

​
Migration Steps

  1. Update Base URL 
    // v1
const BASE_URL = 'https://app.documenso.com/api/v1';

// v2
const BASE_URL = 'https://app.documenso.com/api/v2';
  2. Update Document Creation 
    // v1: Two-step upload
const { uploadUrl, documentId } = await createDocument();
await fetch(uploadUrl, { method: 'PUT', body: pdf });

// v2: Single multipart request
const form = new FormData();
form.append('payload', JSON.stringify(payload));
form.append('files', pdfFile);
await fetch('/api/v2/envelope/create', { body: form });
  3. Update Field References 
    // v1: Simple page reference
{ pageNumber: 1, recipientId: 123 }

// v2: File identifier support
{ page: 1, identifier: 0, recipientId: 123 }
  4. Update Endpoint Paths 
    // v1
GET /api/v1/documents/:id
POST /api/v1/documents/:id/send

// v2
GET /api/v2/envelope/:envelopeId
POST /api/v2/envelope/distribute

​
Migration Guide

For a detailed migration guide with code examples, see:

​
Version Support

​
Current Support Status

VersionStatusNew FeaturesBug FixesSecurity Updates
v2Active✅ Yes✅ Yes✅ Yes
v1Deprecated❌ No⚠️ Critical only✅ Yes

​
Checking API Version

You can determine which version you’re using by inspecting the URL: 
# v1 API
curl https://app.documenso.com/api/v1/documents

# v2 API
curl https://app.documenso.com/api/v2/envelope
The OpenAPI specification is available for each version: 
# v1 OpenAPI spec
https://app.documenso.com/api/v1/openapi.json

# v2 OpenAPI spec
https://app.documenso.com/api/v2/openapi.json

​
Staying Updated

To stay informed about API changes:
  1. Release Notes: Check https://documenso.com/changelog
  2. GitHub: Watch the Documenso repository
  3. Developer Newsletter: Subscribe at https://documenso.com/developers
  4. API Status: Monitor https://status.documenso.com

​
See Also