The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
fix(trpc): v2 field position updates silently dropped; rewrite fields API docs (#3136)
Ephraim Duncan132c4b08c5d5
diff --git a/apps/docs/content/docs/developers/api/common-errors.mdx b/apps/docs/content/docs/developers/api/common-errors.mdxindex f26eba13c..91fcb9313 100644--- a/apps/docs/content/docs/developers/api/common-errors.mdx+++ b/apps/docs/content/docs/developers/api/common-errors.mdx@@ -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 Alsodiff --git a/apps/docs/content/docs/developers/api/fields.mdx b/apps/docs/content/docs/developers/api/fields.mdxindex 71f680a62..0cec72339 100644--- a/apps/docs/content/docs/developers/api/fields.mdx+++ b/apps/docs/content/docs/developers/api/fields.mdx@@ -6,6 +6,8 @@ description: Add signature and form fields to documents 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).@@ -19,13 +21,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 +40,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"}}```@@ -61,7 +64,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';| Type | Description | Auto-filled || ---------------- | ----------------------------------------- | ----------- || `SIGNATURE` | Drawn, typed, or uploaded signature | No |-| `FREE_SIGNATURE` | Unrestricted signature without validation | No |+| `FREE_SIGNATURE` | Legacy free-form signature. Accepted by the v2 create schema but rejected by the v1 API and unsupported in the signing UI — avoid in new integrations | No || `INITIALS` | Recipient's initials | No || `NAME` | Recipient's full name | Yes || `EMAIL` | Recipient's email address | Yes |@@ -134,10 +137,12 @@ 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 |++Each entry in `data` requires a `type`, a `recipientId`, and a position — either explicit coordinates (`page`, `positionX`, `positionY`, `width`, `height`) or a [text placeholder](#placeholder-based-field-positioning) (`placeholder` with optional `width`, `height`, and `matchAll`). Optional per-entry properties: `envelopeItemId` (which PDF in the envelope to place the field on; defaults to the first item) and `fieldMeta`.### Code Examples@@ -148,32 +153,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 +204,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 +244,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 +255,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 +336,10 @@ 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 |++Each entry in `data` requires the field `id` and `type`. Position properties (`page`, `positionX`, `positionY`, `width`, `height`), `envelopeItemId`, and `fieldMeta` are optional — only supplied values are updated. Placeholder positioning is not supported when updating; use coordinates.### Code Examples@@ -311,17 +350,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 +377,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 +396,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 +521,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 +535,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 widthheight: 8, // 8% of page height};@@ -479,6 +557,33 @@ This approach is useful when generating PDFs programmatically or using templatesSee the [PDF Placeholders](/docs/users/documents/advanced/pdf-placeholders) guide for the full placeholder format reference, including supported field types, recipient identifiers, and field options.+### Placeholder Positioning via the API++`POST /envelope/field/create-many` accepts a placeholder position in place of coordinates. Instead of `page`, `positionX`, `positionY`, `width`, and `height`, pass:++| Field | Type | Required | Description |+| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |+| `placeholder` | string | Yes | Text to search for in the PDF (e.g. `{{name}}`). The field is placed at the bounding box of the first match. |+| `width` | number | No | Override the field width. Defaults to the width of the matched text. |+| `height` | number | No | Override the field height. Defaults to the height of the matched text. |+| `matchAll` | boolean | No | Create a field at every occurrence of the placeholder instead of only the first. |++```json+{+ "envelopeId": "envelope_abcdefhiklmnorst",+ "data": [+ {+ "type": "SIGNATURE",+ "recipientId": 456,+ "placeholder": "{{signature}}",+ "matchAll": true+ }+ ]+}+```++`POST /envelope/field/update-many` does not accept placeholders — field updates are coordinate-only.+---## Field Meta Options@@ -643,15 +748,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 +768,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 +782,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 +796,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 +815,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();diff --git a/apps/docs/content/docs/developers/api/index.mdx b/apps/docs/content/docs/developers/api/index.mdxindex e8d7139eb..ac64de966 100644--- a/apps/docs/content/docs/developers/api/index.mdx+++ b/apps/docs/content/docs/developers/api/index.mdx@@ -60,8 +60,8 @@ Authorization: api_xxxxxxxxxxxxxxxxhref="/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>diff --git a/apps/docs/content/docs/developers/api/recipients.mdx b/apps/docs/content/docs/developers/api/recipients.mdxindex 6751a400a..bb72afb92 100644--- a/apps/docs/content/docs/developers/api/recipients.mdx+++ b/apps/docs/content/docs/developers/api/recipients.mdx@@ -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": "[email protected]","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": "[email protected]",@@ -164,7 +166,7 @@ const response = await fetch('Content-Type': 'application/json',},body: JSON.stringify({- envelopeId: 'clu1abc2def3ghi4jkl',+ envelopeId: 'envelope_abcdefhiklmnorst',data: [{email: '[email protected]',@@ -196,7 +198,7 @@ const { data: recipients } = await response.json();"data": [{"id": 789,- "envelopeId": "clu1abc2def3ghi4jkl",+ "envelopeId": "envelope_abcdefhiklmnorst","email": "[email protected]","name": "John Doe","role": "SIGNER",@@ -209,7 +211,7 @@ const { data: recipients } = await response.json();},{"id": 790,- "envelopeId": "clu1abc2def3ghi4jkl",+ "envelopeId": "envelope_abcdefhiklmnorst","email": "[email protected]","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: '[email protected]',@@ -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: '[email protected]',diff --git a/apps/docs/content/docs/developers/api/teams.mdx b/apps/docs/content/docs/developers/api/teams.mdxindex 0d869c56c..258e015c0 100644--- a/apps/docs/content/docs/developers/api/teams.mdx+++ b/apps/docs/content/docs/developers/api/teams.mdx@@ -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--A team object contains the following properties:--| 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` |+## Team Context-### Example Team Object+<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>-```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_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_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_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_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 Responsesdiff --git a/apps/docs/content/docs/developers/api/templates.mdx b/apps/docs/content/docs/developers/api/templates.mdxindex b3f52e146..2d3675100 100644--- a/apps/docs/content/docs/developers/api/templates.mdx+++ b/apps/docs/content/docs/developers/api/templates.mdx@@ -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": "[email protected]",+ "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: '[email protected]',+ 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": "[email protected]",+ "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": "[email protected]",+ "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 ObjectA 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 typeconst 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": "[email protected]","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);````diff --git a/apps/docs/content/docs/developers/examples/common-workflows.mdx b/apps/docs/content/docs/developers/examples/common-workflows.mdxindex 5cac47f79..02f99506b 100644--- a/apps/docs/content/docs/developers/examples/common-workflows.mdx+++ b/apps/docs/content/docs/developers/examples/common-workflows.mdx@@ -262,8 +262,11 @@ Use templates for repeatable document workflows. This example creates an employmMap 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>@@ -297,7 +300,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 },});@@ -374,7 +377,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]}`,}),});@@ -386,9 +388,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,};}@@ -453,12 +471,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>@@ -476,8 +499,10 @@ Send the same document to multiple recipients in parallel. Useful for policy ackFetch 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)@@ -540,7 +565,6 @@ async function bulkSendFromTemplate(recipients: [{ id: signerSlot.id, email: recipient.email, name: recipient.name },],- distributeDocument: true,externalId: `bulk-${Date.now()}-${recipient.email}`,}),});@@ -551,10 +575,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,};}),);@@ -627,14 +667,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')"+ fielse- echo " Failed: $(echo $RESPONSE | jq -r '.message')"+ echo " Failed to create: $(echo $RESPONSE | jq -r '.message')"fi# Rate limiting delay@@ -837,13 +887,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">```typescriptconst 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,@@ -897,7 +949,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 {@@ -911,8 +963,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;}}diff --git a/apps/docs/content/docs/developers/getting-started/authentication.mdx b/apps/docs/content/docs/developers/getting-started/authentication.mdxindex 82d42bb1a..42d4311da 100644--- a/apps/docs/content/docs/developers/getting-started/authentication.mdx+++ b/apps/docs/content/docs/developers/getting-started/authentication.mdx@@ -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--+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.@@ -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>diff --git a/apps/docs/content/docs/developers/getting-started/first-api-call.mdx b/apps/docs/content/docs/developers/getting-started/first-api-call.mdxindex e87b85438..3f9083959 100644--- a/apps/docs/content/docs/developers/getting-started/first-api-call.mdx+++ b/apps/docs/content/docs/developers/getting-started/first-api-call.mdx@@ -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```javascriptconst 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 signingecho "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 limit or plan quota. If `Retry-After` is present, retry the request. || `500` | Server error - retry or contact support |### Error Response Format@@ -485,7 +485,9 @@ 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 has a limit of 1000 requests per minute for each IP address, and your organisation can have a lower limit. Each response includes `X-RateLimit-Remaining` and `X-RateLimit-Reset` (an epoch timestamp in seconds). A windowed rate-limit `429` response includes `Retry-After`. Wait for that number of seconds before you send the request again. A quota `429` response does not include `Retry-After` because a wait cannot correct the quota error. If `Retry-After` is not present, do not send the request again automatically.++Refer to [Error Handling Patterns](/docs/developers/examples/common-workflows#error-handling-patterns) for more retry information.```javascriptasync function fetchWithRetry(url, options, maxRetries = 3) {@@ -493,8 +495,15 @@ 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 retryAfter = response.headers.get('Retry-After');++ if (!retryAfter) {+ return response;+ }++ const retryAfterSeconds = Number.parseInt(retryAfter, 10);+ console.log(`Rate limit. Wait ${retryAfterSeconds} seconds...`);+ await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));continue;}diff --git a/apps/remix/app/components/general/app-command-menu.tsx b/apps/remix/app/components/general/app-command-menu.tsxindex 2e42b5c4e..7a53ff249 100644--- a/apps/remix/app/components/general/app-command-menu.tsx+++ b/apps/remix/app/components/general/app-command-menu.tsx@@ -599,18 +599,10 @@ export const AppCommandMenu = ({ open, onOpenChange }: AppCommandMenuProps) => {isVisibleCountCapped ? (<Trans>{formatChipCount(totalVisibleCount, isVisibleCountCapped)} results</Trans>) : (- <Plural- value={totalVisibleCount}- one="# result"- other="# results"- />+ <Plural value={totalVisibleCount} one="# result" other="# results" />)) : (- <Plural- value={totalVisibleCount}- one="# item"- other="# items"- />+ <Plural value={totalVisibleCount} one="# item" other="# items" />)}</span></div>diff --git a/packages/lib/utils/render-custom-email-template.test.ts b/packages/lib/utils/render-custom-email-template.test.tsindex b1bd4d2c7..d790f60fd 100644--- a/packages/lib/utils/render-custom-email-template.test.ts+++ b/packages/lib/utils/render-custom-email-template.test.ts@@ -8,15 +8,15 @@ describe('renderCustomEmailTemplate', () => {});it('replaces multiple variables separated by whitespace', () => {- expect(- renderCustomEmailTemplate('Hi {name}, sign at {url}', { name: 'Sam', url: 'https://x' }),- ).toBe('Hi Sam, sign at https://x');+ expect(renderCustomEmailTemplate('Hi {name}, sign at {url}', { name: 'Sam', url: 'https://x' })).toBe(+ 'Hi Sam, sign at https://x',+ );});it('replaces adjacent variables and variables separated by a non-whitespace character', () => {- expect(- renderCustomEmailTemplate('{day}/{month}/{year}', { day: '01', month: '02', year: '2026' }),- ).toBe('01/02/2026');+ expect(renderCustomEmailTemplate('{day}/{month}/{year}', { day: '01', month: '02', year: '2026' })).toBe(+ '01/02/2026',+ );expect(renderCustomEmailTemplate('{firstName}-{lastName}', {diff --git a/packages/trpc/server/envelope-router/envelope-fields/update-envelope-fields.ts b/packages/trpc/server/envelope-router/envelope-fields/update-envelope-fields.tsindex 390caea84..735dd5ab3 100644--- a/packages/trpc/server/envelope-router/envelope-fields/update-envelope-fields.ts+++ b/packages/trpc/server/envelope-router/envelope-fields/update-envelope-fields.ts@@ -29,7 +29,17 @@ export const updateEnvelopeFieldsRoute = authenticatedProcedureid: 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,});