Documenso
API Reference

Migrating to Envelopes

Why Documenso unified documents and templates into envelopes, and how to migrate from the deprecated document and template create endpoints.

Summary

The following items have been deprecated and will be removed on the 1st of March 2027:

  • API V1
  • A subset of SDK/API V2 endpoints
  • Legacy documents and templates
  • EmbedCreateDocumentV1
  • EmbedCreateTemplateV1
  • EmbedUpdateDocumentV1
  • EmbedUpdateTemplateV1

The beta endpoint /api/v2-beta will also be removed. Use /api/v2 instead, which is a drop-in replacement.

Nothing breaks before 1st of March 2027, so you can migrate at your own pace.

What are legacy documents and templates

These are documents and templates created by the following endpoints:

  • POST /api/v2/document/create
  • POST /api/v2/document/create/beta
  • POST /api/v2/template/create
  • POST /api/v2/template/create/beta
  • POST /api/v1/documents
  • POST /api/v1/templates
  • POST /api/v1/templates/create-document
  • POST /api/v1/templates/generate-document

What replaces legacy documents and templates

At the end of 2025 we introduced a unified system for documents and templates, called envelopes.

We still reference documents and templates throughout the documentation and application to distinguish them, but internally they are envelopes.

Moving to the envelope system gives you:

  • Multiple PDFs in one envelope. Send several documents to sign in a single request.
  • One API for documents and templates. Learn one set of endpoints instead of two misaligned ones.
  • A better editor and signing experience for you and your recipients.

How to migrate

Switch to the envelope endpoints

Replace each deprecated endpoint with its /api/v2/envelope/* equivalent from the mapping tables below.

Set the envelope type on create

A single endpoint, POST /api/v2/envelope/create, can create both documents and templates. Set type to DOCUMENT or TEMPLATE. You can now upload more than one PDF using the files field.

Update how you store IDs

Envelope IDs are strings (for example envelope_abc123), not numbers. Update any code that stores, parses, or compares IDs.

Test, then remove the old calls

Verify the new flow against your account, then delete the deprecated calls.

The main data differences are as follows:

  • ID format changed from number to string (e.g. 42 to envelope_abc123)
  • pageNumber becomes page
  • pageX becomes positionX
  • pageY becomes positionY

See the Documents API and Templates API for the full envelope reference.

Deprecated V1 API Endpoints

Full reference in the V1 OpenAPI reference.

Deprecated endpointReplacement
GET /api/v1/documentsGET /api/v2/envelope
GET /api/v1/documents/{id}GET /api/v2/envelope/{envelopeId}
POST /api/v1/documentsPOST /api/v2/envelope/create
POST /api/v1/documents/{id}/sendPOST /api/v2/envelope/distribute
POST /api/v1/documents/{id}/resendPOST /api/v2/envelope/redistribute
DELETE /api/v1/documents/{id}POST /api/v2/envelope/delete
GET /api/v1/documents/{id}/downloadGET /api/v2/envelope/item/{envelopeItemId}/download
POST /api/v1/documents/{id}/recipientsPOST /api/v2/envelope/recipient/create-many
PATCH /api/v1/documents/{id}/recipients/{recipientId}POST /api/v2/envelope/recipient/update-many
DELETE /api/v1/documents/{id}/recipients/{recipientId}POST /api/v2/envelope/recipient/delete
POST /api/v1/documents/{id}/fieldsPOST /api/v2/envelope/field/create-many
PATCH /api/v1/documents/{id}/fields/{fieldId}POST /api/v2/envelope/field/update-many
DELETE /api/v1/documents/{id}/fields/{fieldId}POST /api/v2/envelope/field/delete
GET /api/v1/templatesGET /api/v2/envelope (with type=TEMPLATE)
GET /api/v1/templates/{id}GET /api/v2/envelope/{envelopeId}
POST /api/v1/templatesPOST /api/v2/envelope/create (type=TEMPLATE)
DELETE /api/v1/templates/{id}POST /api/v2/envelope/delete
POST /api/v1/templates/{templateId}/create-documentPOST /api/v2/envelope/use
POST /api/v1/templates/{templateId}/generate-documentPOST /api/v2/envelope/use

Deprecated V2 API Endpoints

Full reference in the V2 OpenAPI reference.

Documents

Deprecated endpointReplacement
GET /api/v2/documentGET /api/v2/envelope
GET /api/v2/document/{documentId}GET /api/v2/envelope/{envelopeId}
POST /api/v2/document/get-manyPOST /api/v2/envelope/get-many
POST /api/v2/document/createPOST /api/v2/envelope/create
POST /api/v2/document/create/betaPOST /api/v2/envelope/create
POST /api/v2/document/updatePOST /api/v2/envelope/update
POST /api/v2/document/deletePOST /api/v2/envelope/delete
POST /api/v2/document/duplicatePOST /api/v2/envelope/duplicate
POST /api/v2/document/distributePOST /api/v2/envelope/distribute
POST /api/v2/document/redistributePOST /api/v2/envelope/redistribute
GET /api/v2/document/attachmentGET /api/v2/envelope/attachment
POST /api/v2/document/attachment/createPOST /api/v2/envelope/attachment/create
POST /api/v2/document/attachment/updatePOST /api/v2/envelope/attachment/update
POST /api/v2/document/attachment/deletePOST /api/v2/envelope/attachment/delete
GET /api/v2/document/{documentId}/downloadGET /api/v2/envelope/item/{envelopeItemId}/download
GET /api/v2/document/{documentId}/download-betaGET /api/v2/envelope/item/{envelopeItemId}/download

Templates

Deprecated endpointReplacement
GET /api/v2/templateGET /api/v2/envelope (with type=TEMPLATE)
GET /api/v2/template/{templateId}GET /api/v2/envelope/{envelopeId}
POST /api/v2/template/get-manyPOST /api/v2/envelope/get-many
POST /api/v2/template/createPOST /api/v2/envelope/create (type=TEMPLATE)
POST /api/v2/template/create/betaPOST /api/v2/envelope/create (type=TEMPLATE)
POST /api/v2/template/updatePOST /api/v2/envelope/update
POST /api/v2/template/duplicatePOST /api/v2/envelope/duplicate
POST /api/v2/template/deletePOST /api/v2/envelope/delete
POST /api/v2/template/usePOST /api/v2/envelope/use
POST /api/v2/template/direct/createPending replacement
POST /api/v2/template/direct/deletePending replacement
POST /api/v2/template/direct/togglePending replacement

Document fields

Deprecated endpointReplacement
GET /api/v2/document/field/{fieldId}GET /api/v2/envelope/field/{fieldId}
POST /api/v2/document/field/createPOST /api/v2/envelope/field/create-many
POST /api/v2/document/field/create-manyPOST /api/v2/envelope/field/create-many
POST /api/v2/document/field/updatePOST /api/v2/envelope/field/update-many
POST /api/v2/document/field/update-manyPOST /api/v2/envelope/field/update-many
POST /api/v2/document/field/deletePOST /api/v2/envelope/field/delete

Template fields

Deprecated endpointReplacement
GET /api/v2/template/field/{fieldId}GET /api/v2/envelope/field/{fieldId}
POST /api/v2/template/field/createPOST /api/v2/envelope/field/create-many
POST /api/v2/template/field/create-manyPOST /api/v2/envelope/field/create-many
POST /api/v2/template/field/updatePOST /api/v2/envelope/field/update-many
POST /api/v2/template/field/update-manyPOST /api/v2/envelope/field/update-many
POST /api/v2/template/field/deletePOST /api/v2/envelope/field/delete

Document recipients

Deprecated endpointReplacement
GET /api/v2/document/recipient/{recipientId}GET /api/v2/envelope/recipient/{recipientId}
POST /api/v2/document/recipient/createPOST /api/v2/envelope/recipient/create-many
POST /api/v2/document/recipient/create-manyPOST /api/v2/envelope/recipient/create-many
POST /api/v2/document/recipient/updatePOST /api/v2/envelope/recipient/update-many
POST /api/v2/document/recipient/update-manyPOST /api/v2/envelope/recipient/update-many
POST /api/v2/document/recipient/deletePOST /api/v2/envelope/recipient/delete

Template recipients

Deprecated endpointReplacement
GET /api/v2/template/recipient/{recipientId}GET /api/v2/envelope/recipient/{recipientId}
POST /api/v2/template/recipient/createPOST /api/v2/envelope/recipient/create-many
POST /api/v2/template/recipient/create-manyPOST /api/v2/envelope/recipient/create-many
POST /api/v2/template/recipient/updatePOST /api/v2/envelope/recipient/update-many
POST /api/v2/template/recipient/update-manyPOST /api/v2/envelope/recipient/update-many
POST /api/v2/template/recipient/deletePOST /api/v2/envelope/recipient/delete

Embedding components

Deprecated componentReplacement
EmbedCreateDocumentV1EmbedCreateEnvelope
EmbedCreateTemplateV1EmbedCreateEnvelope
EmbedUpdateDocumentV1EmbedUpdateEnvelope
EmbedUpdateTemplateV1EmbedUpdateEnvelope

See the embedding guide for the envelope components.

FAQ

Getting help

See also

API Versioning

Versioning information for the Documenso public API.

Developer Mode

Advanced development tools for debugging field IDs, recipient IDs, coordinates and integrating with the Documenso API.

On this page

SummaryWhat are legacy documents and templatesWhat replaces legacy documents and templatesHow to migrateSwitch to the envelope endpointsSet the envelope type on createUpdate how you store IDsTest, then remove the old callsDeprecated V1 API EndpointsDeprecated V2 API EndpointsDocumentsTemplatesDocument fieldsTemplate fieldsDocument recipientsTemplate recipientsEmbedding componentsFAQGetting helpSee also