|
|
|
@@ -0,0 +1,250 @@
|
|
|
|
|
---
|
|
|
|
|
title: Migrating to Envelopes
|
|
|
|
|
description: Why Documenso unified documents and templates into envelopes, and how to migrate from the deprecated document and template create endpoints.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
|
|
|
|
|
import { Callout } from 'fumadocs-ui/components/callout';
|
|
|
|
|
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
|
|
|
|
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
|
|
|
|
|
|
|
|
|
## Summary
|
|
|
|
|
|
|
|
|
|
The following items have been deprecated and will be removed on the <strong>1st of March 2027</strong>:
|
|
|
|
|
|
|
|
|
|
- <strong>API V1</strong>
|
|
|
|
|
- <strong>A subset of SDK/API V2 endpoints</strong>
|
|
|
|
|
- <strong>Legacy documents and templates</strong>
|
|
|
|
|
- <strong>EmbedCreateDocumentV1</strong>
|
|
|
|
|
- <strong>EmbedCreateTemplateV1</strong>
|
|
|
|
|
- <strong>EmbedUpdateDocumentV1</strong>
|
|
|
|
|
- <strong>EmbedUpdateTemplateV1</strong>
|
|
|
|
|
|
|
|
|
|
The beta endpoint `/api/v2-beta` will also be removed, please use `/api/v2` instead which can be directly dropped in place.
|
|
|
|
|
|
|
|
|
|
Nothing breaks before 1st of March 2027 — you have time to 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 <strong>envelopes</strong>.
|
|
|
|
|
|
|
|
|
|
We will still reference documents and templates throughout documentation and the application as a method to distinguish them, but internally they are envelopes.
|
|
|
|
|
|
|
|
|
|
By moving to the new envelope system, you get access to:
|
|
|
|
|
|
|
|
|
|
- **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 parallel trees.
|
|
|
|
|
- **A better editor and signing experience** for you and your recipients.
|
|
|
|
|
|
|
|
|
|
## How to migrate
|
|
|
|
|
|
|
|
|
|
{/* prettier-ignore */}
|
|
|
|
|
<Steps>
|
|
|
|
|
<Step>
|
|
|
|
|
### Switch to the envelope endpoints
|
|
|
|
|
|
|
|
|
|
Replace each deprecated endpoint with its `/api/v2/envelope/*` equivalent from the [mapping tables](#endpoint-mapping-reference) below.
|
|
|
|
|
</Step>
|
|
|
|
|
<Step>
|
|
|
|
|
### Set the envelope `type` on create
|
|
|
|
|
|
|
|
|
|
A single endpoint, `POST /api/v2/envelope/create`, creates both documents and templates. Set `type` to `DOCUMENT` or `TEMPLATE`. You can now upload more than one PDF using the `files` field.
|
|
|
|
|
</Step>
|
|
|
|
|
<Step>
|
|
|
|
|
### Update how you store IDs
|
|
|
|
|
|
|
|
|
|
Envelope IDs are **strings** (for example `envelope_abc123`), not numbers. Update any code that stores, parses, or compares IDs.
|
|
|
|
|
</Step>
|
|
|
|
|
<Step>
|
|
|
|
|
### Test, then remove the old calls
|
|
|
|
|
|
|
|
|
|
Verify the new flow against your account, then delete the deprecated calls.
|
|
|
|
|
</Step>
|
|
|
|
|
</Steps>
|
|
|
|
|
|
|
|
|
|
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](/docs/developers/api/documents) and [Templates API](/docs/developers/api/templates) for the full envelope reference.
|
|
|
|
|
|
|
|
|
|
### Deprecated V1 API Endpoints
|
|
|
|
|
|
|
|
|
|
Verify these in the [V1 OpenAPI reference](https://openapi-v1.documenso.com).
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| -------------------------------------------------------- | ----------------------------------------------------- |
|
|
|
|
|
| `GET /api/v1/documents` | `GET /api/v2/envelope` |
|
|
|
|
|
| `GET /api/v1/documents/{id}` | `GET /api/v2/envelope/{envelopeId}` |
|
|
|
|
|
| `POST /api/v1/documents` | `POST /api/v2/envelope/create` |
|
|
|
|
|
| `POST /api/v1/documents/{id}/send` | `POST /api/v2/envelope/distribute` |
|
|
|
|
|
| `POST /api/v1/documents/{id}/resend` | `POST /api/v2/envelope/redistribute` |
|
|
|
|
|
| `DELETE /api/v1/documents/{id}` | `POST /api/v2/envelope/delete` |
|
|
|
|
|
| `GET /api/v1/documents/{id}/download` | `GET /api/v2/envelope/item/{envelopeItemId}/download` |
|
|
|
|
|
| `POST /api/v1/documents/{id}/recipients` | `POST /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}/fields` | `POST /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/templates` | `GET /api/v2/envelope` (with `type=TEMPLATE`) |
|
|
|
|
|
| `GET /api/v1/templates/{id}` | `GET /api/v2/envelope/{envelopeId}` |
|
|
|
|
|
| `POST /api/v1/templates` | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
|
|
|
|
|
| `DELETE /api/v1/templates/{id}` | `POST /api/v2/envelope/delete` |
|
|
|
|
|
| `POST /api/v1/templates/{templateId}/create-document` | `POST /api/v2/envelope/use` |
|
|
|
|
|
| `POST /api/v1/templates/{templateId}/generate-document` | `POST /api/v2/envelope/use` |
|
|
|
|
|
|
|
|
|
|
### Deprecated V2 API Endpoints
|
|
|
|
|
|
|
|
|
|
Verify these in the [V2 OpenAPI reference](https://openapi.documenso.com).
|
|
|
|
|
|
|
|
|
|
#### Documents
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ------------------------------------------------- | ----------------------------------------------------- |
|
|
|
|
|
| `GET /api/v2/document` | `GET /api/v2/envelope` |
|
|
|
|
|
| `GET /api/v2/document/{documentId}` | `GET /api/v2/envelope/{envelopeId}` |
|
|
|
|
|
| `POST /api/v2/document/get-many` | `POST /api/v2/envelope/get-many` |
|
|
|
|
|
| `POST /api/v2/document/create` | `POST /api/v2/envelope/create` |
|
|
|
|
|
| `POST /api/v2/document/create/beta` | `POST /api/v2/envelope/create` |
|
|
|
|
|
| `POST /api/v2/document/update` | `POST /api/v2/envelope/update` |
|
|
|
|
|
| `POST /api/v2/document/delete` | `POST /api/v2/envelope/delete` |
|
|
|
|
|
| `POST /api/v2/document/duplicate` | `POST /api/v2/envelope/duplicate` |
|
|
|
|
|
| `POST /api/v2/document/distribute` | `POST /api/v2/envelope/distribute` |
|
|
|
|
|
| `POST /api/v2/document/redistribute` | `POST /api/v2/envelope/redistribute` |
|
|
|
|
|
| `GET /api/v2/document/attachment` | `GET /api/v2/envelope/attachment` |
|
|
|
|
|
| `POST /api/v2/document/attachment/create` | `POST /api/v2/envelope/attachment/create` |
|
|
|
|
|
| `POST /api/v2/document/attachment/update` | `POST /api/v2/envelope/attachment/update` |
|
|
|
|
|
| `POST /api/v2/document/attachment/delete` | `POST /api/v2/envelope/attachment/delete` |
|
|
|
|
|
| `GET /api/v2/document/{documentId}/download` | `GET /api/v2/envelope/item/{envelopeItemId}/download` |
|
|
|
|
|
| `GET /api/v2/document/{documentId}/download-beta` | `GET /api/v2/envelope/item/{envelopeItemId}/download` |
|
|
|
|
|
|
|
|
|
|
#### Templates
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ------------------------------------- | ------------------------------------------------ |
|
|
|
|
|
| `GET /api/v2/template` | `GET /api/v2/envelope` (with `type=TEMPLATE`) |
|
|
|
|
|
| `GET /api/v2/template/{templateId}` | `GET /api/v2/envelope/{envelopeId}` |
|
|
|
|
|
| `POST /api/v2/template/get-many` | `POST /api/v2/envelope/get-many` |
|
|
|
|
|
| `POST /api/v2/template/create` | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
|
|
|
|
|
| `POST /api/v2/template/create/beta` | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
|
|
|
|
|
| `POST /api/v2/template/update` | `POST /api/v2/envelope/update` |
|
|
|
|
|
| `POST /api/v2/template/duplicate` | `POST /api/v2/envelope/duplicate` |
|
|
|
|
|
| `POST /api/v2/template/delete` | `POST /api/v2/envelope/delete` |
|
|
|
|
|
| `POST /api/v2/template/use` | `POST /api/v2/envelope/use` |
|
|
|
|
|
| `POST /api/v2/template/direct/create` | **Pending replacement** |
|
|
|
|
|
| `POST /api/v2/template/direct/delete` | **Pending replacement** |
|
|
|
|
|
| `POST /api/v2/template/direct/toggle` | **Pending replacement** |
|
|
|
|
|
|
|
|
|
|
#### Document fields
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ----------------------------------------- | ----------------------------------------- |
|
|
|
|
|
| `GET /api/v2/document/field/{fieldId}` | `GET /api/v2/envelope/field/{fieldId}` |
|
|
|
|
|
| `POST /api/v2/document/field/create` | `POST /api/v2/envelope/field/create-many` |
|
|
|
|
|
| `POST /api/v2/document/field/create-many` | `POST /api/v2/envelope/field/create-many` |
|
|
|
|
|
| `POST /api/v2/document/field/update` | `POST /api/v2/envelope/field/update-many` |
|
|
|
|
|
| `POST /api/v2/document/field/update-many` | `POST /api/v2/envelope/field/update-many` |
|
|
|
|
|
| `POST /api/v2/document/field/delete` | `POST /api/v2/envelope/field/delete` |
|
|
|
|
|
|
|
|
|
|
#### Template fields
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ----------------------------------------- | ----------------------------------------- |
|
|
|
|
|
| `GET /api/v2/template/field/{fieldId}` | `GET /api/v2/envelope/field/{fieldId}` |
|
|
|
|
|
| `POST /api/v2/template/field/create` | `POST /api/v2/envelope/field/create-many` |
|
|
|
|
|
| `POST /api/v2/template/field/create-many` | `POST /api/v2/envelope/field/create-many` |
|
|
|
|
|
| `POST /api/v2/template/field/update` | `POST /api/v2/envelope/field/update-many` |
|
|
|
|
|
| `POST /api/v2/template/field/update-many` | `POST /api/v2/envelope/field/update-many` |
|
|
|
|
|
| `POST /api/v2/template/field/delete` | `POST /api/v2/envelope/field/delete` |
|
|
|
|
|
|
|
|
|
|
#### Document recipients
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ---------------------------------------------- | ---------------------------------------------- |
|
|
|
|
|
| `GET /api/v2/document/recipient/{recipientId}` | `GET /api/v2/envelope/recipient/{recipientId}` |
|
|
|
|
|
| `POST /api/v2/document/recipient/create` | `POST /api/v2/envelope/recipient/create-many` |
|
|
|
|
|
| `POST /api/v2/document/recipient/create-many` | `POST /api/v2/envelope/recipient/create-many` |
|
|
|
|
|
| `POST /api/v2/document/recipient/update` | `POST /api/v2/envelope/recipient/update-many` |
|
|
|
|
|
| `POST /api/v2/document/recipient/update-many` | `POST /api/v2/envelope/recipient/update-many` |
|
|
|
|
|
| `POST /api/v2/document/recipient/delete` | `POST /api/v2/envelope/recipient/delete` |
|
|
|
|
|
|
|
|
|
|
#### Template recipients
|
|
|
|
|
|
|
|
|
|
| Deprecated endpoint | Replacement |
|
|
|
|
|
| ---------------------------------------------- | ---------------------------------------------- |
|
|
|
|
|
| `GET /api/v2/template/recipient/{recipientId}` | `GET /api/v2/envelope/recipient/{recipientId}` |
|
|
|
|
|
| `POST /api/v2/template/recipient/create` | `POST /api/v2/envelope/recipient/create-many` |
|
|
|
|
|
| `POST /api/v2/template/recipient/create-many` | `POST /api/v2/envelope/recipient/create-many` |
|
|
|
|
|
| `POST /api/v2/template/recipient/update` | `POST /api/v2/envelope/recipient/update-many` |
|
|
|
|
|
| `POST /api/v2/template/recipient/update-many` | `POST /api/v2/envelope/recipient/update-many` |
|
|
|
|
|
| `POST /api/v2/template/recipient/delete` | `POST /api/v2/envelope/recipient/delete` |
|
|
|
|
|
|
|
|
|
|
### Embedding components
|
|
|
|
|
|
|
|
|
|
| Deprecated component | Replacement |
|
|
|
|
|
| ----------------------- | --------------------- |
|
|
|
|
|
| `EmbedCreateDocumentV1` | `EmbedCreateEnvelope` |
|
|
|
|
|
| `EmbedCreateTemplateV1` | `EmbedCreateEnvelope` |
|
|
|
|
|
| `EmbedUpdateDocumentV1` | `EmbedUpdateEnvelope` |
|
|
|
|
|
| `EmbedUpdateTemplateV1` | `EmbedUpdateEnvelope` |
|
|
|
|
|
|
|
|
|
|
See the [embedding guide](/docs/developers/embedding) for the envelope components.
|
|
|
|
|
|
|
|
|
|
## FAQ
|
|
|
|
|
|
|
|
|
|
<Accordions>
|
|
|
|
|
<Accordion title="What happens on 1 March 2027?">
|
|
|
|
|
The deprecated V1 API, the V2 endpoints listed above, and the V1 embedding components are removed.
|
|
|
|
|
Requests to them will fail, so migrate to the envelope API before that date.
|
|
|
|
|
</Accordion>
|
|
|
|
|
<Accordion title="Will my existing documents and templates keep working?">
|
|
|
|
|
Yes. Documents and templates you already created remain in your account and continue to work. They will automatically be converted to envelopes. Only
|
|
|
|
|
the deprecated endpoints you call are going away — your data is not deleted.
|
|
|
|
|
</Accordion>
|
|
|
|
|
<Accordion title="Do I need a new API token?">
|
|
|
|
|
No. Authentication is unchanged — the same API token works for the envelope endpoints under
|
|
|
|
|
`https://app.documenso.com/api/v2`.
|
|
|
|
|
</Accordion>
|
|
|
|
|
<Accordion title="What is the difference between a document and a template now?">
|
|
|
|
|
Both are envelopes, distinguished by a `type` field of `DOCUMENT` or `TEMPLATE`. They share the same
|
|
|
|
|
endpoints, recipients, fields, and attachments.
|
|
|
|
|
</Accordion>
|
|
|
|
|
<Accordion title="I use an official SDK — what should I do?">
|
|
|
|
|
The function calls to the legacy endpoints will break on the 1st of March 2027. Update to the latest SDK version and switch to its envelope methods.
|
|
|
|
|
The deprecated document and
|
|
|
|
|
template methods map to the envelope endpoints in the tables above.
|
|
|
|
|
</Accordion>
|
|
|
|
|
<Accordion title="I need more time or help migrating">
|
|
|
|
|
Reach out to [support@documenso.com](mailto:support@documenso.com) with your use case and we will
|
|
|
|
|
help you plan the migration.
|
|
|
|
|
</Accordion>
|
|
|
|
|
</Accordions>
|
|
|
|
|
|
|
|
|
|
## Getting help
|
|
|
|
|
|
|
|
|
|
- [V2 OpenAPI reference](https://openapi.documenso.com) — the always up-to-date envelope API.
|
|
|
|
|
- [V1 OpenAPI reference](https://openapi-v1.documenso.com) — the deprecated V1 API.
|
|
|
|
|
- [support@documenso.com](mailto:support@documenso.com) — migration questions and extensions.
|
|
|
|
|
|
|
|
|
|
## See also
|
|
|
|
|
|
|
|
|
|
- [Documents API](/docs/developers/api/documents) — create and manage envelopes
|
|
|
|
|
- [Templates API](/docs/developers/api/templates) — work with templates and direct links
|
|
|
|
|
- [Fields API](/docs/developers/api/fields) and [Recipients API](/docs/developers/api/recipients)
|
|
|
|
|
- [API Versioning](/docs/developers/api/versioning) — how Documenso versions the public API
|
David Nguyen