docs(api): add MISSING_ENV_VAR error and envelope warning to recipients

docs(api): document MISSING_SIGNATURE_FIELD error
Thrown with HTTP 400 from envelope distribution when a signer has no signature field
2026-08-15 19:11:49 +10:00 · 2026-07-31 12:56:28 +00:00 · 2026-07-30 22:04:01 +00:00 · 2026-07-30 22:04:01 +00:00 · 2026-07-30 22:04:01 +00:00 · 2026-07-30 22:04:01 +00:00
11 changed files with 629 additions and 307 deletions
@@ -15,6 +15,8 @@ This guide provides a comprehensive troubleshooting matrix for the standard erro
 | `INVALID_REQUEST` | The overall request is malformed or invalid. | Review your API call parameters, including the URL, query parameters, and headers. Correct the request syntax. |
 | `RECIPIENT_EXPIRED` | The signing link or recipient access has expired. | Generate and resend a new invitation to the affected recipient. |
 | `LIMIT_EXCEEDED` | Your account usage quota has been exceeded. | Check your current plan limits. Upgrade your subscription or wait until your billing cycle renews. |
+| `MISSING_ENV_VAR` | A required environment variable is not configured on the server (500). | Primarily affects self-hosted instances: set the environment variable named in the error message and restart. On Documenso Cloud, contact support. |
+| `MISSING_SIGNATURE_FIELD` | A signer has no signature field placed on the document (400). Returned when distributing an envelope. | Add at least one signature field for every recipient with a signing role before calling `/envelope/distribute`. |
 | `NOT_FOUND` | The requested resource could not be found (404). | Verify the resource ID (envelope, document, webhook) passed in the URL. Ensure the resource has not been deleted. |
 | `NOT_IMPLEMENTED` | The requested feature is not currently supported by the server. | Consult the API documentation to verify available methods. Do not use this endpoint at this time. |
 | `NOT_SETUP` | The required configuration for this action is incomplete. | Access your account or integration settings and complete the necessary configuration before retrying. |
@@ -37,7 +39,28 @@ The following errors occur when attempting to perform actions on an envelope tha
 | `ENVELOPE_DRAFT` | The action cannot be performed because the envelope is still in a draft state. | Finalize the envelope configuration and transition it to the `PENDING` (sent) state before attempting this operation. |
 | `ENVELOPE_COMPLETED` | The action cannot be performed because the envelope is already completed. | No further modifications (e.g., adding signers, modifying documents) can be made to an envelope once the signing process is finished. |
 | `ENVELOPE_REJECTED` | The action cannot be performed because the envelope was rejected by a recipient. | The signing flow is permanently halted. Create a new envelope if you wish to resubmit the document. |
+| `ENVELOPE_CANCELLED` | The action cannot be performed because the envelope was cancelled (400). | Create a new envelope if you need to restart the signing process. |
 | `ENVELOPE_LEGACY` | The action cannot be performed because the envelope uses an obsolete format. | This envelope was created with a legacy version of the system. Recreate the envelope using the current API version to interact with it. |
+| `ENVELOPE_TSP_LOCKED` | An AES/QES envelope cannot be modified after it leaves the draft state (400). | Make changes while the envelope is in `DRAFT`, or create a new envelope. |
+
+## CSC Signing Errors
+
+These errors apply to Cloud Signature Consortium (CSC) signing flows.
+
+| Error Code | Description | Recommended Action |
+| :--- | :--- | :--- |
+| `CSC_INSTANCE_MODE_MISMATCH` | The requested signature level does not match the instance's CSC mode (400). | Use the signature level supported by the instance's signing configuration. |
+| `CSC_UNLICENSED` | CSC signing is not licensed for this instance (403). | Enable the CSC signing license before retrying. |
+| `CSC_PROVIDER_INFO_FAILED` | The CSC provider's discovery request failed or returned unusable information (500). | Check the provider URL, availability, and OAuth configuration. |
+| `CSC_PROVIDER_NO_TSA` | A timestamp authority is unavailable or unusable for CSC signing (500). | Configure `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` and verify provider timestamp access. |
+| `CSC_CREDENTIAL_LIST_EMPTY` | The CSC provider returned no signing credentials for the authenticated user (400). | Enrol a signing credential with the provider, then authenticate again. |
+| `CSC_CERT_INVALID` | The selected signing certificate is missing, invalid, or outside its validity period (400). | Select or renew a valid certificate, then authenticate again. |
+| `CSC_ALGORITHM_REFUSED` | The signing credential uses an unsupported key or digest algorithm (400). | Select a credential that satisfies the instance's CSC algorithm policy. |
+| `CSC_SAD_EXPIRED_PRE_SIGN` | The signature activation data is missing, expired, or unreadable before signing (400). | Repeat the credential authorization flow. |
+| `CSC_TSP_TIMEOUT` | The trust service provider did not complete the signing request before the timeout (408). | Retry the signing request after checking provider availability. |
+| `CSC_EMBED_FAILED` | The returned CSC signature could not be embedded into the envelope items (400). | Restart the signing attempt. If it fails again, contact support. |
+| `CSC_BASE_DOCUMENT_MUTATED` | The document changed between signature preparation and signing (500). | Restart signing from the current envelope state. |
+| `CSC_REQUEST_FAILED` | A CSC provider request failed without a more specific CSC error (500). | Check provider availability and configuration, then retry. |

 ## See Also

@@ -28,62 +28,35 @@ Each document contains one or more PDF files, a list of recipients, and the fiel

 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.
+| Property        | Type           | Description                                                    |
+| --------------- | -------------- | -------------------------------------------------------------- |
+| `id`            | string         | Unique identifier (e.g., `envelope_abc123`)                    |
+| `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`         |
+| `externalId`    | string \| null | Your custom identifier for the document                        |
+| `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                             |
+| `documentMeta`  | object         | Email settings, redirect URL, signing options                  |

 ### 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,
@@ -101,40 +74,22 @@ Documents created through the API have `source: "DOCUMENT"` — there is no sepa
  "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
+      "recipientId": 1
    }
  ],
  "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.",
@@ -19,13 +19,13 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 | `secondaryId`    | string         | Secondary identifier for audit logs          |
 | `type`           | string         | Field type (see [Field Types](#field-types)) |
 | `recipientId`    | number         | ID of the recipient assigned to this field   |
-| `envelopeId`     | number         | ID of the parent envelope                    |
+| `envelopeId`     | string         | ID of the parent envelope                    |
 | `envelopeItemId` | string         | ID of the PDF item the field is placed on    |
 | `page`           | number         | Page number (1-indexed)                      |
-| `positionX`      | number         | X coordinate as percentage (0-100)           |
-| `positionY`      | number         | Y coordinate as percentage (0-100)           |
-| `width`          | number         | Width as percentage of page (0-100)          |
-| `height`         | number         | Height as percentage of page (0-100)         |
+| `positionX`      | string         | X coordinate as percentage (0-100), a decimal serialized as a string |
+| `positionY`      | string         | Y coordinate as percentage (0-100), a decimal serialized as a string |
+| `width`          | string         | Width as percentage of page (0-100), a decimal serialized as a string |
+| `height`         | string         | Height as percentage of page (0-100), a decimal serialized as a string |
 | `customText`     | string         | Value entered by the recipient               |
 | `inserted`       | boolean        | Whether the field has been completed         |
 | `fieldMeta`      | object \| null | Type-specific configuration options          |
@@ -38,18 +38,19 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
  "secondaryId": "field_abc123",
  "type": "SIGNATURE",
  "recipientId": 123,
-  "envelopeId": 789,
-  "envelopeItemId": "envelope_item_xyz",
+  "envelopeId": "envelope_abcdefhiklmnorst",
+  "envelopeItemId": "envelope_item_abcdefhiklmnorst",
  "page": 1,
-  "positionX": 10,
-  "positionY": 80,
-  "width": 30,
-  "height": 5,
+  "positionX": "10",
+  "positionY": "80",
+  "width": "30",
+  "height": "5",
  "customText": "",
  "inserted": false,
  "fieldMeta": {
    "type": "signature",
-    "required": true
+    "required": true,
+    "overflow": "auto"
  }
 }
 ```
@@ -134,10 +135,10 @@ POST /envelope/field/create-many

 ### Request Body

-| Field       | Type   | Required | Description                     |
-| ----------- | ------ | -------- | ------------------------------- |
-| `documentId`| number | Yes      | The document ID                 |
-| `fields`    | array  | Yes      | Array of field configurations   |
+| Field        | Type   | Required | Description                     |
+| ------------ | ------ | -------- | ------------------------------- |
+| `envelopeId` | string | Yes      | The envelope ID                 |
+| `data`       | array  | Yes      | Array of field configurations   |

 ### Code Examples

@@ -148,32 +149,32 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
-    "documentId": 123,
-    "fields": [
+    "envelopeId": "envelope_abcdefhiklmnorst",
+    "data": [
      {
        "type": "SIGNATURE",
        "recipientId": 456,
-        "pageNumber": 1,
-        "pageX": 10,
-        "pageY": 80,
+        "page": 1,
+        "positionX": 10,
+        "positionY": 80,
        "width": 30,
        "height": 5
      },
      {
        "type": "DATE",
        "recipientId": 456,
-        "pageNumber": 1,
-        "pageX": 50,
-        "pageY": 80,
+        "page": 1,
+        "positionX": 50,
+        "positionY": 80,
        "width": 20,
        "height": 3
      },
      {
        "type": "TEXT",
        "recipientId": 456,
-        "pageNumber": 1,
-        "pageX": 10,
-        "pageY": 70,
+        "page": 1,
+        "positionX": 10,
+        "positionY": 70,
        "width": 40,
        "height": 4,
        "fieldMeta": {
@@ -199,32 +200,32 @@ const response = await fetch(
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
-      documentId: 123,
-      fields: [
+      envelopeId: 'envelope_abcdefhiklmnorst',
+      data: [
        {
          type: 'SIGNATURE',
          recipientId: 456,
-          pageNumber: 1,
-          pageX: 10,
-          pageY: 80,
+          page: 1,
+          positionX: 10,
+          positionY: 80,
          width: 30,
          height: 5,
        },
        {
          type: 'DATE',
          recipientId: 456,
-          pageNumber: 1,
-          pageX: 50,
-          pageY: 80,
+          page: 1,
+          positionX: 50,
+          positionY: 80,
          width: 20,
          height: 3,
        },
        {
          type: 'TEXT',
          recipientId: 456,
-          pageNumber: 1,
-          pageX: 10,
-          pageY: 70,
+          page: 1,
+          positionX: 10,
+          positionY: 70,
          width: 40,
          height: 4,
          fieldMeta: {
@@ -239,8 +240,8 @@ const response = await fetch(
  }
 );

-const { fields } = await response.json();
-console.log(`Created ${fields.length} fields`);
+const { data } = await response.json();
+console.log(`Created ${data.length} fields`);

 ````
 </Tab>
@@ -250,36 +251,68 @@ console.log(`Created ${fields.length} fields`);

 ```json
 {
-  "fields": [
+  "data": [
    {
      "id": 101,
+      "secondaryId": "field_abc123",
+      "envelopeId": "envelope_abcdefhiklmnorst",
+      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "SIGNATURE",
      "recipientId": 456,
      "page": 1,
-      "positionX": 10,
-      "positionY": 80,
-      "width": 30,
-      "height": 5
+      "positionX": "10",
+      "positionY": "80",
+      "width": "30",
+      "height": "5",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": {
+        "type": "signature",
+        "fontSize": 18,
+        "overflow": "auto"
+      }
    },
    {
      "id": 102,
+      "secondaryId": "field_def456",
+      "envelopeId": "envelope_abcdefhiklmnorst",
+      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "DATE",
      "recipientId": 456,
      "page": 1,
-      "positionX": 50,
-      "positionY": 80,
-      "width": 20,
-      "height": 3
+      "positionX": "50",
+      "positionY": "80",
+      "width": "20",
+      "height": "3",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": {
+        "type": "date",
+        "fontSize": 12,
+        "textAlign": "left",
+        "overflow": "auto"
+      }
    },
    {
      "id": 103,
+      "secondaryId": "field_ghi789",
+      "envelopeId": "envelope_abcdefhiklmnorst",
+      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
      "type": "TEXT",
      "recipientId": 456,
      "page": 1,
-      "positionX": 10,
-      "positionY": 70,
-      "width": 40,
-      "height": 4
+      "positionX": "10",
+      "positionY": "70",
+      "width": "40",
+      "height": "4",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": {
+        "type": "text",
+        "label": "Job Title",
+        "placeholder": "Enter your job title",
+        "required": true
+      }
    }
  ]
 }
@@ -299,8 +332,8 @@ POST /envelope/field/update-many

 | Field        | Type   | Required | Description                   |
 | ------------ | ------ | -------- | ----------------------------- |
-| `documentId` | number | Yes      | The document ID               |
-| `fields`     | array  | Yes      | Array of field update objects |
+| `envelopeId` | string | Yes      | The envelope ID               |
+| `data`       | array  | Yes      | Array of field update objects |

 ### Code Examples

@@ -311,17 +344,17 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
-    "documentId": 123,
-    "fields": [
+    "envelopeId": "envelope_abcdefhiklmnorst",
+    "data": [
      {
        "id": 101,
        "type": "SIGNATURE",
-        "pageY": 85
+        "positionY": 85
      },
      {
        "id": 102,
        "type": "DATE",
-        "pageY": 85
+        "positionY": 85
      }
    ]
  }'
@@ -338,16 +371,16 @@ const response = await fetch(
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
-      documentId: 123,
-      fields: [
-        { id: 101, type: 'SIGNATURE', pageY: 85 },
-        { id: 102, type: 'DATE', pageY: 85 },
+      envelopeId: 'envelope_abcdefhiklmnorst',
+      data: [
+        { id: 101, type: 'SIGNATURE', positionY: 85 },
+        { id: 102, type: 'DATE', positionY: 85 },
      ],
    }),
  }
 );

-const { fields } = await response.json();
+const { data } = await response.json();

 ````
 </Tab>
@@ -357,9 +390,48 @@ const { fields } = await response.json();

 ```json
 {
-  "fields": [
-    { "id": 101, "type": "SIGNATURE", "positionY": 85 },
-    { "id": 102, "type": "DATE", "positionY": 85 }
+  "data": [
+    {
+      "id": 101,
+      "secondaryId": "field_abc123",
+      "envelopeId": "envelope_abcdefhiklmnorst",
+      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
+      "type": "SIGNATURE",
+      "recipientId": 456,
+      "page": 1,
+      "positionX": "10",
+      "positionY": "85",
+      "width": "30",
+      "height": "5",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": {
+        "type": "signature",
+        "fontSize": 18,
+        "overflow": "auto"
+      }
+    },
+    {
+      "id": 102,
+      "secondaryId": "field_def456",
+      "envelopeId": "envelope_abcdefhiklmnorst",
+      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
+      "type": "DATE",
+      "recipientId": 456,
+      "page": 1,
+      "positionX": "50",
+      "positionY": "85",
+      "width": "20",
+      "height": "3",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": {
+        "type": "date",
+        "fontSize": 12,
+        "textAlign": "left",
+        "overflow": "auto"
+      }
+    }
  ]
 }
 ````
@@ -443,8 +515,8 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
 (0,0) ─────────────────────────── (100,0)
  │                                   │
  │    ┌─────────┐                    │
-  │    │  Field  │ (pageX: 10,        │
-  │    │         │  pageY: 20,        │
+  │    │  Field  │ (positionX: 10,    │
+  │    │         │  positionY: 20,    │
  │    └─────────┘  width: 30,        │
  │                 height: 5)        │
  │                                   │
@@ -457,9 +529,9 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
 const field = {
  type: 'SIGNATURE',
  recipientId: 123,
-  pageNumber: 1,
-  pageX: 60, // 60% from left
-  pageY: 85, // 85% from top (near bottom)
+  page: 1,
+  positionX: 60, // 60% from left
+  positionY: 85, // 85% from top (near bottom)
  width: 30, // 30% of page width
  height: 8, // 8% of page height
 };
@@ -643,15 +715,15 @@ All field types support these base options:
 Create a document with a signature block containing multiple field types:

 ```typescript
-async function addSignatureBlock(documentId: number, recipientId: number) {
-  const fields = [
+async function addSignatureBlock(envelopeId: string, recipientId: number) {
+  const data = [
    // Signature
    {
      type: 'SIGNATURE',
      recipientId,
-      pageNumber: 1,
-      pageX: 10,
-      pageY: 80,
+      page: 1,
+      positionX: 10,
+      positionY: 80,
      width: 30,
      height: 8,
      fieldMeta: {
@@ -663,9 +735,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
    {
      type: 'NAME',
      recipientId,
-      pageNumber: 1,
-      pageX: 10,
-      pageY: 90,
+      page: 1,
+      positionX: 10,
+      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
@@ -677,9 +749,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
    {
      type: 'DATE',
      recipientId,
-      pageNumber: 1,
-      pageX: 50,
-      pageY: 80,
+      page: 1,
+      positionX: 50,
+      positionY: 80,
      width: 20,
      height: 4,
      fieldMeta: {
@@ -691,9 +763,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
    {
      type: 'TEXT',
      recipientId,
-      pageNumber: 1,
-      pageX: 50,
-      pageY: 90,
+      page: 1,
+      positionX: 50,
+      positionY: 90,
      width: 30,
      height: 4,
      fieldMeta: {
@@ -710,7 +782,7 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
      Authorization: 'api_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
-    body: JSON.stringify({ documentId, fields }),
+    body: JSON.stringify({ envelopeId, data }),
  });

  return response.json();
@@ -60,8 +60,8 @@ Authorization: api_xxxxxxxxxxxxxxxx
    href="/docs/developers/api/templates"
  />
  <Card
-    title="Teams"
-    description="Manage teams and team members."
+    title="Team-scoped access"
+    description="Use team-scoped API tokens with envelope endpoints."
    href="/docs/developers/api/teams"
  />
 </Cards>
@@ -6,6 +6,8 @@ description: Add and manage envelope recipients via 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).
@@ -16,7 +18,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 ```json
 {
  "id": 123,
-  "envelopeId": "clu1abc2def3ghi4jkl",
+  "envelopeId": "envelope_abcdefhiklmnorst",
  "email": "signer@example.com",
  "name": "John Doe",
  "role": "SIGNER",
@@ -134,7 +136,7 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/create-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
-    "envelopeId": "clu1abc2def3ghi4jkl",
+    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "email": "signer@example.com",
@@ -164,7 +166,7 @@ const response = await fetch(
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
-      envelopeId: 'clu1abc2def3ghi4jkl',
+      envelopeId: 'envelope_abcdefhiklmnorst',
      data: [
        {
          email: 'signer@example.com',
@@ -196,7 +198,7 @@ const { data: recipients } = await response.json();
  "data": [
    {
      "id": 789,
-      "envelopeId": "clu1abc2def3ghi4jkl",
+      "envelopeId": "envelope_abcdefhiklmnorst",
      "email": "signer@example.com",
      "name": "John Doe",
      "role": "SIGNER",
@@ -209,7 +211,7 @@ const { data: recipients } = await response.json();
    },
    {
      "id": 790,
-      "envelopeId": "clu1abc2def3ghi4jkl",
+      "envelopeId": "envelope_abcdefhiklmnorst",
      "email": "approver@example.com",
      "name": "Jane Smith",
      "role": "APPROVER",
@@ -262,7 +264,7 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/recipient/update-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
-    "envelopeId": "clu1abc2def3ghi4jkl",
+    "envelopeId": "envelope_abcdefhiklmnorst",
    "data": [
      {
        "id": 789,
@@ -284,7 +286,7 @@ const response = await fetch(
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
-      envelopeId: 'clu1abc2def3ghi4jkl',
+      envelopeId: 'envelope_abcdefhiklmnorst',
      data: [
        {
          id: 789,
@@ -387,7 +389,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/recipien
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
-    envelopeId: 'clu1abc2def3ghi4jkl',
+    envelopeId: 'envelope_abcdefhiklmnorst',
    data: [
      {
        email: 'approver@example.com',
@@ -462,7 +464,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/recipien
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
-    envelopeId: 'clu1abc2def3ghi4jkl',
+    envelopeId: 'envelope_abcdefhiklmnorst',
    data: [
      {
        email: 'signer@example.com',
@@ -1,44 +1,29 @@
 ---
-title: Teams API
-description: Manage team resources, documents, and templates with team-scoped API tokens.
+title: Team-Scoped API Access
+description: Use team-scoped API tokens with document and template envelopes.
 ---

 import { Callout } from 'fumadocs-ui/components/callout';
 import { Step, Steps } from 'fumadocs-ui/components/steps';
 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>

-## Team Object
+## Team Context

-A team object contains the following properties:
+<Callout type="info">
+  The V2 REST API does not expose `/team/*` endpoints. Create and manage teams, members, and team
+  settings in the Documenso web application. This page explains how a team-scoped token applies
+  that team context to supported API resources.
+</Callout>

-| Property          | Type           | Description                                         |
-| ----------------- | -------------- | --------------------------------------------------- |
-| `id`              | number         | Unique team identifier                              |
-| `name`            | string         | Team display name                                   |
-| `url`             | string         | Unique team URL slug                                |
-| `createdAt`       | string         | ISO 8601 timestamp                                  |
-| `avatarImageId`   | string \| null | ID of the team's avatar image                       |
-| `organisationId`  | string         | ID of the parent organisation                       |
-| `currentTeamRole` | string         | Your role in the team: `ADMIN`, `MANAGER`, `MEMBER` |
-
-### Example Team Object
-
-```json
-{
-  "id": 123,
-  "name": "Engineering",
-  "url": "engineering",
-  "createdAt": "2025-01-15T10:30:00.000Z",
-  "avatarImageId": null,
-  "organisationId": "org_abc123",
-  "currentTeamRole": "ADMIN"
-}
-```
+The API resolves the team from your token. You do not pass a team ID when creating, listing, or
+using envelopes. The token's team ID determines which resources the request can access.

 ## Team-Scoped API Tokens

@@ -156,26 +141,26 @@ Retrieve all documents belonging to the team:
 <Tab value="curl">
 ```bash
 # List all team documents
-curl -X GET "https://app.documenso.com/api/v2/envelope" \
+curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"

 # Filter by status
-curl -X GET "https://app.documenso.com/api/v2/envelope?status=PENDING" \
+curl -X GET "https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=PENDING" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"
 ````

 </Tab>
 <Tab value="TypeScript">
 ```typescript
-const response = await fetch('https://app.documenso.com/api/v2/envelope', {
+const response = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
  },
 });

-const { data, pagination } = await response.json();
-console.log(`Found ${pagination.totalItems} team documents`);
+const { data, count } = await response.json();
+console.log(`Found ${count} team documents`);

 ````
 </Tab>
@@ -190,10 +175,11 @@ Templates created with a team token are shared across the team.
 <Tabs items={['curl', 'TypeScript']}>
 <Tab value="curl">
 ```bash
-curl -X POST "https://app.documenso.com/api/v2/template/create" \
+curl -X POST "https://app.documenso.com/api/v2/envelope/create" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: multipart/form-data" \
  -F 'payload={
+    "type": "TEMPLATE",
    "title": "NDA Template",
    "recipients": [
      {
@@ -223,6 +209,7 @@ curl -X POST "https://app.documenso.com/api/v2/template/create" \
 const form = new FormData();

 const payload = {
+  type: 'TEMPLATE',
  title: 'NDA Template',
  recipients: [
    {
@@ -249,7 +236,7 @@ form.append('files', fs.createReadStream('./nda-template.pdf'), {
  contentType: 'application/pdf',
 });

-const response = await fetch('https://app.documenso.com/api/v2/template/create', {
+const response = await fetch('https://app.documenso.com/api/v2/envelope/create', {
  method: 'POST',
  headers: {
    Authorization: TEAM_API_TOKEN,
@@ -257,8 +244,8 @@ const response = await fetch('https://app.documenso.com/api/v2/template/create',
  body: form,
 });

-const template = await response.json();
-console.log('Created team template:', template.id);
+const { id } = await response.json();
+console.log('Created team template envelope:', id);
 ````
 </Tab>
 </Tabs>
@@ -268,14 +255,14 @@ console.log('Created team template:', template.id);
 <Tabs items={['curl', 'TypeScript']}>
 <Tab value="curl">
 ```bash
-curl -X GET "https://app.documenso.com/api/v2/template" \
+curl -X GET "https://app.documenso.com/api/v2/envelope?type=TEMPLATE" \
  -H "Authorization: api_team_xxxxxxxxxxxxxxxx"
 ````

 </Tab>
 <Tab value="TypeScript">
 ```typescript
-const response = await fetch('https://app.documenso.com/api/v2/template', {
+const response = await fetch('https://app.documenso.com/api/v2/envelope?type=TEMPLATE', {
  method: 'GET',
  headers: {
    Authorization: TEAM_API_TOKEN,
@@ -330,19 +317,19 @@ const SALES_TEAM_TOKEN = process.env.SALES_TEAM_API_TOKEN;
 const LEGAL_TEAM_TOKEN = process.env.LEGAL_TEAM_API_TOKEN;

 // Get pending documents from sales team
-const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=PENDING', {
+const salesResponse = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=PENDING', {
  headers: { Authorization: SALES_TEAM_TOKEN },
 });
 const salesDocs = await salesResponse.json();

 // Get completed documents from legal team
-const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?status=COMPLETED', {
+const legalResponse = await fetch('https://app.documenso.com/api/v2/envelope?type=DOCUMENT&status=COMPLETED', {
  headers: { Authorization: LEGAL_TEAM_TOKEN },
 });
 const legalDocs = await legalResponse.json();

-console.log(`Sales team: ${salesDocs.pagination.totalItems} pending`);
-console.log(`Legal team: ${legalDocs.pagination.totalItems} completed`);
+console.log(`Sales team: ${salesDocs.count} pending`);
+console.log(`Legal team: ${legalDocs.count} completed`);
 ```

 ## Error Responses
@@ -13,7 +13,194 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
  see the [OpenAPI Reference](https://openapi.documenso.com).
 </Callout>

-## Template Object
+## Use a Template Envelope
+
+New integrations should create a document from a template envelope with the Envelope API.
+
+```
+POST /envelope/use
+Content-Type: multipart/form-data
+```
+
+The request uses `multipart/form-data`:
+
+| Part      | Type    | Required | Description                                                        |
+| --------- | ------- | -------- | ------------------------------------------------------------------ |
+| `payload` | JSON    | Yes      | Template envelope ID, recipient details, and document settings     |
+| `files`   | File(s) | No       | Replacement PDFs referenced by entries in `customDocumentData`     |
+
+### Payload Schema
+
+| Field                | Type    | Required | Description                                                              |
+| -------------------- | ------- | -------- | ------------------------------------------------------------------------ |
+| `envelopeId`         | string  | Yes      | ID of the template envelope                                              |
+| `externalId`         | string  | No       | Your identifier for the created document envelope                        |
+| `recipients`         | array   | No       | Recipient details mapped to recipients in the template                    |
+| `distributeDocument` | boolean | No       | If `true`, create the document as pending and distribute it               |
+| `customDocumentData` | array   | No       | Maps uploaded replacement PDFs to template envelope items                 |
+| `folderId`           | string  | No       | Folder in which to create the document                                    |
+| `prefillFields`      | array   | No       | Field values to prefill before distribution                               |
+| `override`           | object  | No       | Template values to override for the created document                      |
+| `attachments`        | array   | No       | Link attachments to add to the document                                   |
+| `formValues`         | object  | No       | PDF form values to apply                                                   |
+
+Each recipient entry accepts the following fields:
+
+| Field          | Type    | Required | Description                                  |
+| -------------- | ------- | -------- | -------------------------------------------- |
+| `id`           | number  | Yes      | Recipient ID from the template envelope      |
+| `email`        | string  | Yes      | Recipient email address                      |
+| `name`         | string  | No       | Recipient display name                       |
+| `signingOrder` | number  | No       | Recipient position in sequential signing     |
+
+Each `customDocumentData` entry maps an uploaded file to a template item:
+
+| Field            | Type             | Required | Description                                                     |
+| ---------------- | ---------------- | -------- | --------------------------------------------------------------- |
+| `identifier`     | string \| number | Yes      | Uploaded filename or zero-based file index                      |
+| `envelopeItemId` | string           | Yes      | Template envelope item whose PDF the uploaded file replaces     |
+
+### Code Examples
+
+<Tabs items={['curl', 'TypeScript']}>
+<Tab value="curl">
+```bash
+curl -X POST "https://app.documenso.com/api/v2/envelope/use" \
+  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
+  -F 'payload={
+    "envelopeId": "envelope_template123",
+    "externalId": "contract-2025-001",
+    "recipients": [
+      {
+        "id": 1,
+        "email": "john.doe@example.com",
+        "name": "John Doe"
+      }
+    ],
+    "prefillFields": [
+      {
+        "id": 101,
+        "type": "text",
+        "value": "Senior Software Engineer"
+      }
+    ],
+    "distributeDocument": false
+  }'
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+const form = new FormData();
+
+form.append(
+  'payload',
+  JSON.stringify({
+    envelopeId: 'envelope_template123',
+    externalId: 'contract-2025-001',
+    recipients: [
+      {
+        id: 1,
+        email: 'john.doe@example.com',
+        name: 'John Doe',
+      },
+    ],
+    prefillFields: [
+      {
+        id: 101,
+        type: 'text',
+        value: 'Senior Software Engineer',
+      },
+    ],
+    distributeDocument: false,
+  }),
+);
+
+const response = await fetch('https://app.documenso.com/api/v2/envelope/use', {
+  method: 'POST',
+  headers: {
+    Authorization: 'api_xxxxxxxxxxxxxxxx',
+  },
+  body: form,
+});
+
+const document = await response.json();
+console.log('Created document envelope:', document.id);
+```
+</Tab>
+</Tabs>
+
+### Response
+
+```json
+{
+  "id": "envelope_document123",
+  "recipients": [
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john.doe@example.com",
+      "token": "recipient_token",
+      "role": "SIGNER",
+      "signingOrder": 1,
+      "signingUrl": "https://app.documenso.com/sign/recipient_token"
+    }
+  ]
+}
+```
+
+### Distribute the Created Envelope
+
+If you leave `distributeDocument` unset or set it to `false`, distribute the created document with
+`POST /envelope/distribute`. Its response confirms delivery and includes each recipient's signing URL.
+
+```typescript
+const distributionResponse = await fetch(
+  'https://app.documenso.com/api/v2/envelope/distribute',
+  {
+    method: 'POST',
+    headers: {
+      Authorization: 'api_xxxxxxxxxxxxxxxx',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      envelopeId: document.id,
+    }),
+  },
+);
+
+const distribution = await distributionResponse.json();
+console.log('Signing URL:', distribution.recipients[0].signingUrl);
+```
+
+```json
+{
+  "success": true,
+  "id": "envelope_document123",
+  "recipients": [
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john.doe@example.com",
+      "token": "recipient_token",
+      "role": "SIGNER",
+      "signingOrder": 1,
+      "signingUrl": "https://app.documenso.com/sign/recipient_token"
+    }
+  ]
+}
+```
+
+---
+
+## Deprecated Template Endpoint Reference
+
+<Callout type="warn">
+  Every `/template/*` endpoint below is deprecated. Use the Envelope API for new integrations and
+  follow [Migrating to Envelopes](/docs/developers/api/migrate-to-envelopes) to replace existing calls.
+  The legacy reference remains here to support migrations.
+</Callout>
+
+## Legacy Template Object

 A template object contains the following properties:

@@ -91,7 +278,7 @@ A template object contains the following properties:
 }
 ```

-## List Templates
+## List Templates (Deprecated)

 Retrieve a paginated list of templates.

@@ -139,8 +326,8 @@ const response = await fetch(`${BASE_URL}/template`, {
  },
 });

-const { data, pagination } = await response.json();
-console.log(`Found ${pagination.totalItems} templates`);
+const { data, count } = await response.json();
+console.log(`Found ${count} templates`);

 // Filter by type
 const privateResponse = await fetch(
@@ -181,18 +368,16 @@ const privateTemplates = await privateResponse.json();
      ]
    }
  ],
-  "pagination": {
-    "page": 1,
-    "perPage": 10,
-    "totalPages": 3,
-    "totalItems": 25
-  }
+  "count": 25,
+  "currentPage": 1,
+  "perPage": 10,
+  "totalPages": 3
 }
 ```

 ---

-## Get Template
+## Get Template (Deprecated)

 Retrieve a single template by ID.

@@ -238,9 +423,9 @@ Returns the full template object including recipients, fields, and metadata.

 ---

-## Create Document from Template
+## Create Document from Template (Deprecated)

-Create a new document using a template. This is the primary way to use templates programmatically.
+Create a new document using the deprecated template endpoint.

 <Callout type="info">
  This endpoint does not support [PDF placeholder parsing](/docs/users/documents/advanced/pdf-placeholders). Use `POST /envelope/create` for placeholder-based field positioning.
@@ -415,32 +600,57 @@ const prefilledDocument = await prefillResponse.json();

 ### Response

-Returns the created document object with recipients and signing URLs.
+The endpoint returns the full legacy document object. The selected fields below show both the numeric
+legacy `id` and canonical `envelopeId`. Recipient entries do not include a `signingUrl`.

 ```json
 {
-  "id": "envelope_xyz789",
-  "type": "DOCUMENT",
+  "id": 789,
+  "envelopeId": "envelope_xyz789",
  "status": "PENDING",
-  "title": "Employment Contract",
  "source": "TEMPLATE",
+  "title": "Employment Contract",
  "externalId": "contract-2025-001",
  "recipients": [
    {
      "id": 1,
+      "envelopeId": "envelope_xyz789",
+      "documentId": 789,
+      "templateId": null,
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "SIGNER",
      "signingStatus": "NOT_SIGNED",
-      "signingUrl": "https://app.documenso.com/sign/abc123"
+      "signingOrder": 1
    }
  ]
 }
-````
+```
+
+To send a document created with `distributeDocument: false` and receive signing links, call
+`POST /envelope/distribute` with its `envelopeId`:
+
+```typescript
+const document = await response.json();
+
+const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
+  method: 'POST',
+  headers: {
+    Authorization: API_TOKEN,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    envelopeId: document.envelopeId,
+  }),
+});
+
+const distribution = await distributionResponse.json();
+console.log('Signing URL:', distribution.recipients[0].signingUrl);
+```

 ---

-## Override Template Settings
+## Override Template Settings (Deprecated)

 When creating a document from a template, you can override various settings:

@@ -488,7 +698,7 @@ const response = await fetch(`${BASE_URL}/template/use`, {

 ---

-## Prefill Fields
+## Prefill Fields (Deprecated)

 Prefill field values when creating a document from a template. This is useful for populating known data before sending.

@@ -577,7 +787,7 @@ const response = await fetch(`${BASE_URL}/template/use`, {

 ---

-## Update Template
+## Update Template (Deprecated)

 Update a template's properties.

@@ -643,7 +853,7 @@ const template = await response.json();

 ---

-## Duplicate Template
+## Duplicate Template (Deprecated)

 Create a copy of an existing template.

@@ -695,7 +905,7 @@ console.log('New template ID:', duplicatedTemplate.id);

 ---

-## Delete Template
+## Delete Template (Deprecated)

 Delete a template.

@@ -754,7 +964,7 @@ const { success } = await response.json();

 ---

-## Direct Link Templates
+## Direct Link Templates (Deprecated)

 Direct link templates allow recipients to create and sign documents without requiring you to explicitly create each document. When a recipient visits the direct link, a new document is automatically created from the template.

@@ -898,7 +1108,7 @@ const { success } = await response.json();

 ---

-## Custom Document Data
+## Custom Document Data (Deprecated)

 When creating a document from a template, you can replace the template's PDF with a custom PDF by using the `customDocumentData` parameter. This is useful when you need to generate the PDF dynamically while reusing the template's recipient and field configuration.

@@ -913,7 +1123,7 @@ See the [OpenAPI Reference](https://openapi.documenso.com) for the full request

 ---

-## Template Types
+## Template Types (Legacy)

 | Type      | Description                                                        |
 | --------- | ------------------------------------------------------------------ |
@@ -922,7 +1132,7 @@ See the [OpenAPI Reference](https://openapi.documenso.com) for the full request

 ---

-## Complete Example: Contract Workflow
+## Complete Legacy Example: Contract Workflow (Deprecated)

 This example demonstrates a complete workflow for using templates to send contracts.

@@ -996,16 +1206,29 @@ async function sendEmploymentContract(employeeData: {
        subject: `Employment Contract for ${employeeData.name}`,
        message: `Hi ${employeeData.name},\n\nPlease review and sign your employment contract.`,
      },
-      distributeDocument: true,
+      distributeDocument: false,
      externalId: `emp-contract-${Date.now()}`,
    }),
  });

  const document = await documentResponse.json();

+  // 5. Distribute the envelope and get recipient signing links
+  const distributionResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
+    method: 'POST',
+    headers: {
+      Authorization: API_TOKEN,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      envelopeId: document.envelopeId,
+    }),
+  });
+  const distribution = await distributionResponse.json();
+
  return {
-    documentId: document.id,
-    signingUrl: document.recipients[0].signingUrl,
+    envelopeId: document.envelopeId,
+    signingUrl: distribution.recipients[0].signingUrl,
  };
 }

@@ -1018,7 +1241,7 @@ const result = await sendEmploymentContract({
  startDate: '2025-03-01',
 });

-console.log('Document created:', result.documentId);
+console.log('Document created:', result.envelopeId);
 console.log('Signing URL:', result.signingUrl);
 ````

@@ -256,8 +256,11 @@ Use templates for repeatable document workflows. This example creates an employm
    Map template fields by label and build a <code>prefillFields</code> array
  </Step>
  <Step>
-    Call <code>POST /template/use</code> with recipients, prefill data, and{' '}
-    <code>distributeDocument: true</code>
+    Call <code>POST /template/use</code> with recipients and prefill data
+  </Step>
+  <Step>
+    Distribute the returned envelope via <code>POST /envelope/distribute</code> and read its signing
+    links
  </Step>
 </Steps>

@@ -291,7 +294,7 @@ type TemplateRecipient = {
 async function sendEmploymentContract(
  templateId: number,
  employee: EmployeeData,
-): Promise<{ documentId: string; signingUrl: string }> {
+): Promise<{ documentId: number; signingUrl: string }> {
  const templateResponse = await fetch(`${BASE_URL}/template/${templateId}`, {
    headers: { Authorization: API_TOKEN },
  });
@@ -368,7 +371,6 @@ async function sendEmploymentContract(
        subject: `Your Employment Contract at ${employee.department}`,
        message: `Hi ${employee.name},\n\nPlease review and sign your employment contract for the ${employee.position} position.\n\nStart date: ${employee.startDate}`,
      },
-      distributeDocument: true,
      externalId: `emp-${Date.now()}-${employee.email.split('@')[0]}`,
    }),
  });
@@ -380,9 +382,25 @@ async function sendEmploymentContract(

  const document = await createResponse.json();

+  const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
+    method: 'POST',
+    headers: {
+      Authorization: API_TOKEN,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ envelopeId: document.envelopeId }),
+  });
+
+  if (!distributeResponse.ok) {
+    const error = await distributeResponse.json();
+    throw new Error(`Failed to send document: ${error.message}`);
+  }
+
+  const distributeResult = await distributeResponse.json();
+
  return {
    documentId: document.id,
-    signingUrl: document.recipients[0].signingUrl,
+    signingUrl: distributeResult.recipients[0].signingUrl,
  };
 }

@@ -447,12 +465,17 @@ RESPONSE=$(curl -s -X POST "${BASE_URL}/template/use" \
      \"subject\": \"Your Employment Contract\",
      \"message\": \"Please review and sign your employment contract.\"
    },
-    \"distributeDocument\": true,
    \"externalId\": \"emp-$(date +%s)-alice\"
  }")

-echo "Document created:"
-echo $RESPONSE | jq '{id, signingUrl: .recipients[0].signingUrl}'
+ENVELOPE_ID=$(echo $RESPONSE | jq -r '.envelopeId')
+DISTRIBUTE_RESPONSE=$(curl -s -X POST "${BASE_URL}/envelope/distribute" \
+  -H "Authorization: ${API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"envelopeId\": \"${ENVELOPE_ID}\"}")
+
+echo "Document created: $(echo $RESPONSE | jq -r '.id')"
+echo "Signing URL: $(echo $DISTRIBUTE_RESPONSE | jq -r '.recipients[0].signingUrl')"
 ````

 </Tab>
@@ -470,8 +493,10 @@ Send the same document to multiple recipients in parallel. Useful for policy ack
    Fetch the template and get the signer recipient slot ID
  </Step>
  <Step>
-    For each recipient, call <code>POST /template/use</code> with{' '}
-    <code>distributeDocument: true</code>
+    For each recipient, call <code>POST /template/use</code>
+  </Step>
+  <Step>
+    Distribute each returned envelope via <code>POST /envelope/distribute</code>
  </Step>
  <Step>
    Process in batches with a short delay to respect rate limits (e.g. 1000 requests/minute)
@@ -534,7 +559,6 @@ async function bulkSendFromTemplate(
            recipients: [
              { id: signerSlot.id, email: recipient.email, name: recipient.name },
            ],
-            distributeDocument: true,
            externalId: `bulk-${Date.now()}-${recipient.email}`,
          }),
        });
@@ -545,10 +569,26 @@ async function bulkSendFromTemplate(
        }

        const document = await response.json();
+
+        const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
+          method: 'POST',
+          headers: {
+            Authorization: API_TOKEN,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ envelopeId: document.envelopeId }),
+        });
+
+        if (!distributeResponse.ok) {
+          const error = await distributeResponse.json();
+          throw new Error(error.message || 'Failed to distribute document');
+        }
+
+        const distributeResult = await distributeResponse.json();
        return {
          email: recipient.email,
-          envelopeId: document.id,
-          signingUrl: document.recipients[0].signingUrl,
+          envelopeId: document.envelopeId,
+          signingUrl: distributeResult.recipients[0].signingUrl,
        };
      }),
    );
@@ -621,14 +661,24 @@ for RECIPIENT in "${RECIPIENTS[@]}"; do
        \"email\": \"${EMAIL}\",
        \"name\": \"${NAME}\"
      }],
-      \"distributeDocument\": true,
      \"externalId\": \"bulk-$(date +%s)-${EMAIL}\"
    }")

-  if echo $RESPONSE | jq -e '.id' > /dev/null 2>&1; then
-    echo "  Success: $(echo $RESPONSE | jq -r '.id')"
+  if echo $RESPONSE | jq -e '.envelopeId' > /dev/null 2>&1; then
+    ENVELOPE_ID=$(echo $RESPONSE | jq -r '.envelopeId')
+    DISTRIBUTE_RESPONSE=$(curl -s -X POST "${BASE_URL}/envelope/distribute" \
+      -H "Authorization: ${API_TOKEN}" \
+      -H "Content-Type: application/json" \
+      -d "{\"envelopeId\": \"${ENVELOPE_ID}\"}")
+
+    if echo $DISTRIBUTE_RESPONSE | jq -e '.success' > /dev/null 2>&1; then
+      echo "  Success: ${ENVELOPE_ID}"
+      echo "  Signing URL: $(echo $DISTRIBUTE_RESPONSE | jq -r '.recipients[0].signingUrl')"
+    else
+      echo "  Failed to distribute: $(echo $DISTRIBUTE_RESPONSE | jq -r '.message')"
+    fi
  else
-    echo "  Failed: $(echo $RESPONSE | jq -r '.message')"
+    echo "  Failed to create: $(echo $RESPONSE | jq -r '.message')"
  fi

  # Rate limiting delay
@@ -831,13 +881,15 @@ After a document is completed, download the signed PDF with all signatures embed
  </Step>
 </Steps>

+The `version` query parameter accepts `original`, `pending`, or `signed`.
+
 <Tabs items={['TypeScript', 'curl']}>
 <Tab value="TypeScript">
 ```typescript
 const API_TOKEN = process.env.DOCUMENSO_API_TOKEN;
 const BASE_URL = 'https://app.documenso.com/api/v2';

-type DownloadVersion = 'signed' | 'original';
+type DownloadVersion = 'original' | 'pending' | 'signed';

 async function downloadDocument(
  envelopeId: string,
@@ -891,7 +943,7 @@ async function downloadAllCompletedDocuments(outputDir: string): Promise<void> {
      { headers: { Authorization: API_TOKEN } },
    );

-    const { data, pagination } = await response.json();
+    const { data, count, currentPage, perPage, totalPages } = await response.json();

    for (const envelope of data) {
      try {
@@ -905,8 +957,8 @@ async function downloadAllCompletedDocuments(outputDir: string): Promise<void> {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }

-    hasMore = page < pagination.totalPages;
-    page++;
+    hasMore = currentPage < totalPages;
+    page = currentPage + 1;
  }
 }

@@ -24,20 +24,18 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 {/* prettier-ignore */}
 <Steps>
 <Step>
-### Open settings
+### Select a team

- Log in to your Documenso account
- Click your avatar in the top right corner
- Select **Settings** from the dropdown menu
-
-![User dropdown menu](/public-api-images/documenso-user-dropdown-menu.webp)
+Log in to Documenso and open the team that the integration should access. API tokens are scoped to a
+team.

 </Step>

 <Step>
-### Navigate to the API Tokens tab
+### Open API Tokens

-Go to **Settings** and open the **API Tokens** tab.
+Go to **Team Settings** → **API Tokens**, or open
+`/t/{teamUrl}/settings/tokens` after replacing `{teamUrl}` with your team's URL.

 ![API tokens page](/public-api-images/api-tokens-page-documenso.webp)

@@ -48,7 +46,7 @@ Go to **Settings** and open the **API Tokens** tab.

 - Click **Create Token**
 - Enter a descriptive name (e.g., `production-backend`, `zapier-integration`)
- Select an expiration period: never expires, 7 days, 1 month, 3 months, 6 months, or 1 year
+- Select an expiration period: 7 days, 1 month, 3 months, 6 months, 12 months, or Never
 - Click **Create Token**

 </Step>
@@ -75,21 +73,21 @@ Include the token in the `Authorization` header of your HTTP requests.
 ### cURL

 ```bash
-curl https://app.documenso.com/api/v2/document \
+curl https://app.documenso.com/api/v2/envelope \
  -H "Authorization: api_xxxxxxxxxxxxxxxx"
 ```

 ### JavaScript / TypeScript

 ```typescript
-const response = await fetch('https://app.documenso.com/api/v2/document', {
+const response = await fetch('https://app.documenso.com/api/v2/envelope', {
  method: 'GET',
  headers: {
    Authorization: 'api_xxxxxxxxxxxxxxxx',
  },
 });

-const documents = await response.json();
+const envelopes = await response.json();
 ```

 ### Using the TypeScript SDK
@@ -129,7 +127,7 @@ SDKs are available for [TypeScript](https://github.com/documenso/sdk-typescript)

 ## Token Security

-API tokens grant full access to your account. Follow these practices to keep them secure:
+API tokens grant full API access to the team they were created for. Follow these practices to keep them secure:

 - **Never commit tokens to version control.** Use environment variables instead.
 - **Use descriptive names.** Names like `zapier-prod` or `backend-staging` help you identify token usage.
@@ -155,12 +153,11 @@ const client = new Documenso({

 ## Token Scope

-API tokens have full access to your account, including:
+API tokens have full API access to the team they were created for, including:

 - Creating, reading, updating, and deleting documents
 - Managing recipients and fields
 - Accessing templates
- Managing team resources (if the token owner has team access)

 There is currently no way to create tokens with limited scopes or permissions.

@@ -171,7 +168,7 @@ To revoke a token:
 {/* prettier-ignore */}
 <Steps>
  <Step>
-    Go to **Settings** > **API Tokens**
+    Go to **Team Settings** → **API Tokens**
  </Step>
  <Step>
    Find the token you want to revoke
@@ -194,7 +191,7 @@ Revoked tokens stop working immediately. Any integrations using that token will
  </Accordion>
  <Accordion title="401 Unauthorized — Expired token">Create a new token in settings.</Accordion>
  <Accordion title="403 Forbidden — Token doesn't have access to the resource">
-    Ensure you're accessing resources owned by the token's account.
+    Ensure you're accessing resources owned by the token's team.
  </Accordion>
 </Accordions>

@@ -78,12 +78,10 @@ A successful response returns a list of your documents (envelopes):
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
-  "pagination": {
-    "page": 1,
-    "perPage": 10,
-    "totalPages": 1,
-    "totalItems": 1
-  }
+  "count": 1,
+  "currentPage": 1,
+  "perPage": 10,
+  "totalPages": 1
 }
 ````

@@ -228,9 +226,12 @@ After creating a document, it's in `DRAFT` status. To send it to recipients, use
 <Tabs items={['curl', 'JavaScript']}>
 <Tab value="curl">
 ```bash
-curl -X POST "https://app.documenso.com/api/v2/envelope/envelope_abc123/distribute" \
+curl -X POST "https://app.documenso.com/api/v2/envelope/distribute" \
  -H "Authorization: YOUR_API_TOKEN" \
-  -H "Content-Type: application/json"
+  -H "Content-Type: application/json" \
+  -d '{
+    "envelopeId": "envelope_abc123"
+  }'
 ````

 </Tab>
@@ -238,16 +239,14 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/envelope_abc123/distribu
 ```javascript
 const envelopeId = 'envelope_abc123';

-const response = await fetch(
-  `https://app.documenso.com/api/v2/envelope/${envelopeId}/distribute`,
-  {
-    method: 'POST',
-    headers: {
-      Authorization: 'YOUR_API_TOKEN',
-      'Content-Type': 'application/json',
-    },
+const response = await fetch('https://app.documenso.com/api/v2/envelope/distribute', {
+  method: 'POST',
+  headers: {
+    Authorization: 'YOUR_API_TOKEN',
+    'Content-Type': 'application/json',
  },
-);
+  body: JSON.stringify({ envelopeId }),
+});

 const data = await response.json();
 console.log('Document sent:', data);
@@ -337,16 +336,14 @@ async function createAndSendDocument(pdfPath, recipientEmail, recipientName) {
  console.log('Created envelope:', envelope.id);

  // Step 2: Send the document for signing
-  const distributeResponse = await fetch(
-    `${BASE_URL}/envelope/${envelope.id}/distribute`,
-    {
-      method: 'POST',
-      headers: {
-        'Authorization': API_TOKEN,
-        'Content-Type': 'application/json',
-      },
-    }
-  );
+  const distributeResponse = await fetch(`${BASE_URL}/envelope/distribute`, {
+    method: 'POST',
+    headers: {
+      'Authorization': API_TOKEN,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ envelopeId: envelope.id }),
+  });

  if (!distributeResponse.ok) {
    const error = await distributeResponse.json();
@@ -422,9 +419,12 @@ echo "Created envelope: ${ENVELOPE_ID}"
 # Step 2: Send the document for signing

 echo "Sending document..."
-curl -s -X POST "${BASE_URL}/envelope/${ENVELOPE_ID}/distribute" \
+curl -s -X POST "${BASE_URL}/envelope/distribute" \
  -H "Authorization: ${API_TOKEN}" \
-  -H "Content-Type: application/json"
+  -H "Content-Type: application/json" \
+  -d "{
+    \"envelopeId\": \"${ENVELOPE_ID}\"
+  }"

 echo "Document sent for signing!"

@@ -441,7 +441,7 @@ The API returns standard HTTP status codes and JSON error responses:
 | `400` | Bad request - check your request payload |
 | `401` | Unauthorized - invalid or missing API token |
 | `404` | Not found - resource doesn't exist |
-| `429` | Rate limited - wait 60 seconds and retry |
+| `429` | Rate limited - wait for the duration in the `Retry-After` header |
 | `500` | Server error - retry or contact support |

 ### Error Response Format
@@ -485,7 +485,7 @@ The API returns standard HTTP status codes and JSON error responses:

 ### Handling Rate Limits

-The API allows 1000 requests per minute per IP address. Your organisation may have its own lower rate limits. When rate limited, wait at least 60 seconds before retrying:
+The API allows 1000 requests per minute per IP address. Your organisation may have its own lower rate limits. Every response includes `X-RateLimit-Remaining` and `X-RateLimit-Reset` (an epoch timestamp in seconds). When you receive a `429` response, read the `Retry-After` header and wait for that many seconds before retrying. See [Error Handling Patterns](/docs/developers/examples/common-workflows#error-handling-patterns) for a more complete retry strategy.

 ```javascript
 async function fetchWithRetry(url, options, maxRetries = 3) {
@@ -493,8 +493,9 @@ async function fetchWithRetry(url, options, maxRetries = 3) {
    const response = await fetch(url, options);

    if (response.status === 429) {
-      console.log('Rate limited, waiting 60 seconds...');
-      await new Promise((resolve) => setTimeout(resolve, 60000));
+      const retryAfterSeconds = Number.parseInt(response.headers.get('Retry-After') ?? '1', 10);
+      console.log(`Rate limited, waiting ${retryAfterSeconds} seconds...`);
+      await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
      continue;
    }

@@ -29,7 +29,17 @@ export const updateEnvelopeFieldsRoute = authenticatedProcedure
        id: envelopeId,
      },
      type: null,
-      fields,
+      fields: fields.map((field) => ({
+        id: field.id,
+        type: field.type,
+        pageNumber: field.page,
+        pageX: field.positionX,
+        pageY: field.positionY,
+        width: field.width,
+        height: field.height,
+        fieldMeta: field.fieldMeta,
+        envelopeItemId: field.envelopeItemId,
+      })),
      requestMetadata: ctx.metadata,
    });
Author	SHA1	Message	Date
ephraimduncan	ddd0da1473	docs(api): add MISSING_ENV_VAR error and envelope warning to recipients	2026-07-31 12:56:28 +00:00
ephraimduncan	1e1e15a7dc	docs(api): document MISSING_SIGNATURE_FIELD error Thrown with HTTP 400 from envelope distribution when a signer has no signature field	2026-07-30 22:04:01 +00:00
ephraimduncan	4e87121bef	docs: fix workflows, authentication, error codes and id formats - workflows: flat pagination shape, signing URLs via /envelope/distribute, pending version value - authentication: tokens are team-scoped; fix expiry options and use GET /envelope for the check - recipients: envelope IDs use the envelope_ prefix format, not cuid - common-errors: add ENVELOPE_CANCELLED, ENVELOPE_TSP_LOCKED and CSC_* codes	2026-07-30 22:04:01 +00:00
ephraimduncan	f353706e24	docs(api): filter team document lists by type GET /envelope without type returns templates as well as documents; add type=DOCUMENT to every document-list example so counts and results match the prose	2026-07-30 22:04:01 +00:00
ephraimduncan	eeae0e1e02	docs(api): make templates and teams pages envelope-first - lead templates page with POST /envelope/use and /envelope/distribute; label /template/* deprecated - legacy /template/use returns no signingUrl; document the real responses - teams page: /team/* REST endpoints are not exposed; reframe around team-scoped tokens - fix fabricated pagination wrappers; replace false Teams API card on the index page	2026-07-30 22:04:01 +00:00
ephraimduncan	3c9c490505	docs(getting-started): fix distribute route, pagination and retry advice - POST /envelope/{id}/distribute does not exist; use POST /envelope/distribute with body - list responses are flat (data, count, currentPage, perPage, totalPages), not nested pagination - replace fixed 60s sleep advice with Retry-After header handling	2026-07-30 22:04:01 +00:00
ephraimduncan	905e68fdea	fix(trpc): map v2 field update coordinates to service names - ZUpdateEnvelopeFieldsRequestSchema accepts page/positionX/positionY but the service consumes pageNumber/pageX/pageY, so position updates via POST /envelope/field/update-many were silently dropped; map the names in the route before calling updateEnvelopeFields - docs: show Decimal coordinates as serialized strings in field responses - docs: include the defaulted fieldMeta values returned when the request omits fieldMeta - docs: use real envelope/envelope-item ID formats in samples	2026-07-30 22:04:01 +00:00
ephraimduncan	ced5af4d5a	docs(api): rewrite fields examples for envelope field schemas - request is { envelopeId, data } not { documentId, fields } - coordinates are page/positionX/positionY not pageNumber/pageX/pageY - responses use the data wrapper; field type samples verified against the Zod schemas	2026-07-30 22:04:00 +00:00