docs(api): document placeholder positioning and per-entry field options

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-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:00 +00:00 · 2026-07-30 22:04:00 +00:00
4 changed files with 332 additions and 121 deletions
@@ -32,9 +32,9 @@ A document object contains the following properties:
 | --------------- | -------------- | -------------------------------------------------------------- |
 | `id`            | string         | Unique identifier (e.g., `envelope_abc123`)                    |
 | `type`          | string         | `DOCUMENT` or `TEMPLATE`                                       |
-| `status`        | string         | Current status: `DRAFT`, `PENDING`, `COMPLETED`, or `REJECTED` |
+| `status`        | string         | Current status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, or `CANCELLED` |
 | `title`         | string         | Document title                                                 |
-| `source`        | string         | How the document was created: `DOCUMENT`, `TEMPLATE`, `API`    |
+| `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                                             |
@@ -53,7 +53,7 @@ A document object contains the following properties:
  "id": "envelope_abc123xyz",
  "type": "DOCUMENT",
  "status": "PENDING",
-  "source": "API",
+  "source": "DOCUMENT",
  "visibility": "EVERYONE",
  "title": "Service Agreement",
  "externalId": "contract-2025-001",
@@ -73,13 +73,13 @@ A document object contains the following properties:
  ],
  "fields": [
    {
-      "id": "field_123",
+      "id": 123,
      "type": "SIGNATURE",
      "page": 1,
-      "positionX": 10,
-      "positionY": 80,
-      "width": 30,
-      "height": 5,
+      "positionX": "10",
+      "positionY": "80",
+      "width": "30",
+      "height": "5",
      "recipientId": 1
    }
  ],
@@ -99,6 +99,8 @@ A document object contains the following properties:
 }
 ```

+Field position and size values are stored as decimals and serialized as strings in API responses.
+
 ## List Documents

 Retrieve a paginated list of documents.
@@ -114,7 +116,7 @@ GET /envelope
 | `page`             | integer | Page number (default: 1)                                      |
 | `perPage`          | integer | Results per page (default: 10, max: 100)                      |
 | `type`             | string  | Filter by `DOCUMENT` or `TEMPLATE`                            |
-| `status`           | string  | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` |
+| `status`           | string  | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED` |
 | `source`           | string  | Filter by creation source                                     |
 | `folderId`         | string  | Filter by folder ID                                           |
 | `orderByColumn`    | string  | Sort field (only `createdAt` supported)                       |
@@ -154,8 +156,8 @@ const response = await fetch(`${BASE_URL}/envelope`, {
  },
 });

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

 // Filter by status
 const pendingResponse = await fetch(
@@ -197,12 +199,10 @@ const pendingDocs = await pendingResponse.json();
      ]
    }
  ],
-  "pagination": {
-    "page": 1,
-    "perPage": 10,
-    "totalPages": 5,
-    "totalItems": 42
-  }
+  "count": 42,
+  "currentPage": 1,
+  "perPage": 10,
+  "totalPages": 5
 }
 ```

@@ -628,6 +628,72 @@ The response includes signing URLs for each recipient:

 ---

+## Cancel Document
+
+Cancel a pending document. This changes its status from `PENDING` to `CANCELLED`.
+
+```
+POST /envelope/cancel
+```
+
+### Request Body
+
+| Field        | Type   | Required | Description                         |
+| ------------ | ------ | -------- | ----------------------------------- |
+| `envelopeId` | string | Yes      | Document ID                         |
+| `reason`     | string | No       | Reason for cancelling the document |
+
+### Code Examples
+
+<Tabs items={['curl', 'TypeScript']}>
+<Tab value="curl">
+```bash
+curl -X POST "https://app.documenso.com/api/v2/envelope/cancel" \
+  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "envelopeId": "envelope_abc123",
+    "reason": "The agreement is no longer needed."
+  }'
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+const response = await fetch('https://app.documenso.com/api/v2/envelope/cancel', {
+  method: 'POST',
+  headers: {
+    Authorization: 'api_xxxxxxxxxxxxxxxx',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    envelopeId: 'envelope_abc123',
+    reason: 'The agreement is no longer needed.',
+  }),
+});
+
+const { success } = await response.json();
+```
+</Tab>
+</Tabs>
+
+### Response
+
+```json
+{
+  "success": true
+}
+```
+
+### Behavior
+
+- Only documents in `PENDING` status can be cancelled. Other statuses return `400`.
+- Cancellation is not idempotent. Cancelling the same document again returns `400`.
+- The document owner and team members with `MANAGER` or higher permissions can cancel it. Requests for documents you cannot view return `404`; requests for visible documents without sufficient permissions return `401`.
+- A successful cancellation fires the `DOCUMENT_CANCELLED` webhook.
+- Cancellation emails are sent only to eligible non-CC, non-rejected recipients who were sent or opened the document.
+
+---
+
 ## Delete Document

 Delete a document. Completed documents cannot be deleted.
@@ -670,7 +736,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/delete',

 const { success } = await response.json();

-````
+```
 </Tab>
 </Tabs>

@@ -680,7 +746,7 @@ const { success } = await response.json();
 {
  "success": true
 }
-````
+```

 ---

@@ -694,9 +760,11 @@ POST /envelope/get-many

 ### Request Body

-| Field         | Type  | Required | Description           |
-| ------------- | ----- | -------- | --------------------- |
-| `envelopeIds` | array | Yes      | Array of document IDs |
+| Field      | Type   | Required | Description                                                                  |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| `ids`      | object | Yes      | ID selector containing `type` and `ids`                                      |
+| `ids.type` | string | Yes      | `envelopeId`, `documentId`, or `templateId`                                  |
+| `ids.ids`  | array  | Yes      | 1-20 IDs: strings for `envelopeId`; numbers for `documentId` or `templateId` |

 ### Code Examples

@@ -707,12 +775,17 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/get-many" \
  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
-    "envelopeIds": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
+    "ids": {
+      "type": "envelopeId",
+      "ids": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
+    }
  }'
 ```
 </Tab>
 <Tab value="TypeScript">
 ```typescript
+const requestedIds = ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'];
+
 const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many', {
  method: 'POST',
  headers: {
@@ -720,16 +793,36 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
-    envelopeIds: ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'],
+    ids: {
+      type: 'envelopeId',
+      ids: requestedIds,
+    },
  }),
 });

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

-````
+```
 </Tab>
 </Tabs>

+### Response
+
+```json
+{
+  "data": [
+    {
+      "id": "envelope_abc123",
+      "type": "DOCUMENT",
+      "status": "PENDING",
+      "title": "Service Agreement"
+    }
+  ]
+}
+```
+
+The endpoint silently omits envelopes you cannot access instead of returning `404`. Compare `data.length` with `requestedIds.length` to detect omissions.
+
 ---

 ## Document Statuses
@@ -740,6 +833,7 @@ const documents = await response.json();
 | `PENDING` | Document has been sent. Waiting for recipients to sign. |
 | `COMPLETED` | All recipients have signed. Document is sealed. |
 | `REJECTED` | A recipient rejected the document. |
+| `CANCELLED` | The document was cancelled by its owner or a team member with `MANAGER` or higher permissions. |

 ### Status Transitions

@@ -747,11 +841,13 @@ const documents = await response.json();
 flowchart LR
  DRAFT --> PENDING --> COMPLETED
  PENDING --> REJECTED
+  PENDING --> CANCELLED
 ```

 - **DRAFT to PENDING**: Call the distribute endpoint
 - **PENDING to COMPLETED**: All recipients complete their signing
 - **PENDING to REJECTED**: A recipient rejects the document
+- **PENDING to CANCELLED**: The document owner or a team member with `MANAGER` or higher permissions cancels the document

 <Callout type="warn">
  You cannot modify recipients or fields after a document moves to `PENDING` status.
@@ -773,8 +869,8 @@ flowchart LR
 | Parameter  | Values                                      | Description               |
 | ---------- | ------------------------------------------- | ------------------------- |
 | `type`     | `DOCUMENT`, `TEMPLATE`                      | Filter by envelope type   |
-| `status`   | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` | Filter by status          |
-| `source`   | `DOCUMENT`, `TEMPLATE`, `API`               | Filter by creation source |
+| `status`   | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED` | Filter by status          |
+| `source`   | `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK`          | Filter by creation source |
 | `folderId` | string                                      | Filter by folder          |

 ### Sorting
@@ -800,10 +896,10 @@ async function getAllPendingDocuments() {
      },
    );

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

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

@@ -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 width
  height: 8, // 8% of page height
 };
@@ -479,6 +557,33 @@ This approach is useful when generating PDFs programmatically or using templates

 See 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();
@@ -119,7 +119,7 @@ Full reference in the [V2 OpenAPI reference](https://openapi.documenso.com).
 | ------------------------------------------------- | ----------------------------------------------------- |
 | `GET /api/v2/document`                            | `GET /api/v2/envelope`                                |
 | `GET /api/v2/document/{documentId}`               | `GET /api/v2/envelope/{envelopeId}`                   |
-| `POST /api/v2/document/get-many`                  | `POST /api/v2/envelope/get-many`                      |
+| `POST /api/v2/document/get-many`                  | `POST /api/v2/envelope/get-many` (body changes from `documentIds: number[]` to `ids: { type: "documentId"; ids: number[] }`) |
 | `POST /api/v2/document/create`                    | `POST /api/v2/envelope/create`                        |
 | `POST /api/v2/document/create/beta`               | `POST /api/v2/envelope/create`                        |
 | `POST /api/v2/document/update`                    | `POST /api/v2/envelope/update`                        |
@@ -140,7 +140,7 @@ Full reference in the [V2 OpenAPI reference](https://openapi.documenso.com).
 | ------------------------------------- | ------------------------------------------------ |
 | `GET /api/v2/template`                | `GET /api/v2/envelope` (with `type=TEMPLATE`)    |
 | `GET /api/v2/template/{templateId}`   | `GET /api/v2/envelope/{envelopeId}`              |
-| `POST /api/v2/template/get-many`      | `POST /api/v2/envelope/get-many`                 |
+| `POST /api/v2/template/get-many`      | `POST /api/v2/envelope/get-many` (body changes from `templateIds: number[]` to `ids: { type: "templateId"; ids: number[] }`) |
 | `POST /api/v2/template/create`        | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
 | `POST /api/v2/template/create/beta`   | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
 | `POST /api/v2/template/update`        | `POST /api/v2/envelope/update`                   |
@@ -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	a43d09be9b	docs(api): document placeholder positioning and per-entry field options	2026-07-31 12:56:28 +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
ephraimduncan	b076a70d98	docs(api): document cancel endpoint and fix get-many body shape - add Cancel Document section: PENDING-only, not idempotent, access rules, webhook and emails - replace fabricated envelopeIds get-many body with the real nested ids selector (max 20) - document the data wrapper and silent filtering of inaccessible IDs - add CANCELLED to status table, state diagram, transitions and filters - replace nonexistent API source value with the real enum; fix pagination shape and fences - warn in migration guide that get-many body shape changed from documentIds	2026-07-30 22:04:00 +00:00