Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2026-08-23 23:02:22 +10:00
Code Issues Packages Projects Releases Wiki Activity

docs(api): rewrite fields examples for envelope field schemas

Browse Source 
- 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
This commit is contained in:
ephraimduncan
2026-07-30 22:04:00 +00:00
parent b076a70d98
commit ced5af4d5a
1 changed files with 129 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/docs/developers/api/fields.mdx
+129 -68
View File
@@ -19,7 +19,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
| `secondaryId` | string | Secondary identifier for audit logs | | `secondaryId` | string | Secondary identifier for audit logs |
| `type` | string | Field type (see [Field Types](#field-types)) | | `type` | string | Field type (see [Field Types](#field-types)) |
| `recipientId` | number | ID of the recipient assigned to this field | | `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 | | `envelopeItemId` | string | ID of the PDF item the field is placed on |
| `page` | number | Page number (1-indexed) | | `page` | number | Page number (1-indexed) |
| `positionX` | number | X coordinate as percentage (0-100) | | `positionX` | number | X coordinate as percentage (0-100) |
@@ -38,7 +38,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
"secondaryId": "field_abc123", "secondaryId": "field_abc123",
"type": "SIGNATURE", "type": "SIGNATURE",
"recipientId": 123, "recipientId": 123,
"envelopeId": 789, "envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz", "envelopeItemId": "envelope_item_xyz",
"page": 1, "page": 1,
"positionX": 10, "positionX": 10,
@@ -134,10 +134,10 @@ POST /envelope/field/create-many
### Request Body ### Request Body
| Field | Type | Required | Description | | Field | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------- | | ------------ | ------ | -------- | ------------------------------- |
| `documentId`| number | Yes | The document ID | | `envelopeId` | string | Yes | The envelope ID |
| `fields` | array | Yes | Array of field configurations | | `data` | array | Yes | Array of field configurations |
### Code Examples ### Code Examples
@@ -148,32 +148,32 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/create-many" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \ -H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"documentId": 123, "envelopeId": "clu1abc2def3ghi4jkl",
"fields": [ "data": [
{ {
"type": "SIGNATURE", "type": "SIGNATURE",
"recipientId": 456, "recipientId": 456,
"pageNumber": 1, "page": 1,
"pageX": 10, "positionX": 10,
"pageY": 80, "positionY": 80,
"width": 30, "width": 30,
"height": 5 "height": 5
}, },
{ {
"type": "DATE", "type": "DATE",
"recipientId": 456, "recipientId": 456,
"pageNumber": 1, "page": 1,
"pageX": 50, "positionX": 50,
"pageY": 80, "positionY": 80,
"width": 20, "width": 20,
"height": 3 "height": 3
}, },
{ {
"type": "TEXT", "type": "TEXT",
"recipientId": 456, "recipientId": 456,
"pageNumber": 1, "page": 1,
"pageX": 10, "positionX": 10,
"pageY": 70, "positionY": 70,
"width": 40, "width": 40,
"height": 4, "height": 4,
"fieldMeta": { "fieldMeta": {
@@ -199,32 +199,32 @@ const response = await fetch(
'Content-Type': 'application/json', 'Content-Type': 'application/json',
}, },
body: JSON.stringify({ body: JSON.stringify({
documentId: 123, envelopeId: 'clu1abc2def3ghi4jkl',
fields: [ data: [
{ {
type: 'SIGNATURE', type: 'SIGNATURE',
recipientId: 456, recipientId: 456,
pageNumber: 1, page: 1,
pageX: 10, positionX: 10,
pageY: 80, positionY: 80,
width: 30, width: 30,
height: 5, height: 5,
}, },
{ {
type: 'DATE', type: 'DATE',
recipientId: 456, recipientId: 456,
pageNumber: 1, page: 1,
pageX: 50, positionX: 50,
pageY: 80, positionY: 80,
width: 20, width: 20,
height: 3, height: 3,
}, },
{ {
type: 'TEXT', type: 'TEXT',
recipientId: 456, recipientId: 456,
pageNumber: 1, page: 1,
pageX: 10, positionX: 10,
pageY: 70, positionY: 70,
width: 40, width: 40,
height: 4, height: 4,
fieldMeta: { fieldMeta: {
@@ -239,8 +239,8 @@ const response = await fetch(
} }
); );
const { fields } = await response.json(); const { data } = await response.json();
console.log(`Created ${fields.length} fields`); console.log(`Created ${data.length} fields`);
```` ````
</Tab> </Tab>
@@ -250,36 +250,63 @@ console.log(`Created ${fields.length} fields`);
```json ```json
{ {
"fields": [ "data": [
{ {
"id": 101, "id": 101,
"secondaryId": "field_abc123",
"envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz",
"type": "SIGNATURE", "type": "SIGNATURE",
"recipientId": 456, "recipientId": 456,
"page": 1, "page": 1,
"positionX": 10, "positionX": 10,
"positionY": 80, "positionY": 80,
"width": 30, "width": 30,
"height": 5 "height": 5,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "signature"
}
}, },
{ {
"id": 102, "id": 102,
"secondaryId": "field_def456",
"envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz",
"type": "DATE", "type": "DATE",
"recipientId": 456, "recipientId": 456,
"page": 1, "page": 1,
"positionX": 50, "positionX": 50,
"positionY": 80, "positionY": 80,
"width": 20, "width": 20,
"height": 3 "height": 3,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "date"
}
}, },
{ {
"id": 103, "id": 103,
"secondaryId": "field_ghi789",
"envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz",
"type": "TEXT", "type": "TEXT",
"recipientId": 456, "recipientId": 456,
"page": 1, "page": 1,
"positionX": 10, "positionX": 10,
"positionY": 70, "positionY": 70,
"width": 40, "width": 40,
"height": 4 "height": 4,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "text",
"label": "Job Title",
"placeholder": "Enter your job title",
"required": true
}
} }
] ]
} }
@@ -299,8 +326,8 @@ POST /envelope/field/update-many
| Field | Type | Required | Description | | Field | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------- | | ------------ | ------ | -------- | ----------------------------- |
| `documentId` | number | Yes | The document ID | | `envelopeId` | string | Yes | The envelope ID |
| `fields` | array | Yes | Array of field update objects | | `data` | array | Yes | Array of field update objects |
### Code Examples ### Code Examples
@@ -311,17 +338,17 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/update-many" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \ -H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"documentId": 123, "envelopeId": "clu1abc2def3ghi4jkl",
"fields": [ "data": [
{ {
"id": 101, "id": 101,
"type": "SIGNATURE", "type": "SIGNATURE",
"pageY": 85 "positionY": 85
}, },
{ {
"id": 102, "id": 102,
"type": "DATE", "type": "DATE",
"pageY": 85 "positionY": 85
} }
] ]
}' }'
@@ -338,16 +365,16 @@ const response = await fetch(
'Content-Type': 'application/json', 'Content-Type': 'application/json',
}, },
body: JSON.stringify({ body: JSON.stringify({
documentId: 123, envelopeId: 'clu1abc2def3ghi4jkl',
fields: [ data: [
{ id: 101, type: 'SIGNATURE', pageY: 85 }, { id: 101, type: 'SIGNATURE', positionY: 85 },
{ id: 102, type: 'DATE', pageY: 85 }, { id: 102, type: 'DATE', positionY: 85 },
], ],
}), }),
} }
); );
const { fields } = await response.json(); const { data } = await response.json();
```` ````
</Tab> </Tab>
@@ -357,9 +384,43 @@ const { fields } = await response.json();
```json ```json
{ {
"fields": [ "data": [
{ "id": 101, "type": "SIGNATURE", "positionY": 85 }, {
{ "id": 102, "type": "DATE", "positionY": 85 } "id": 101,
"secondaryId": "field_abc123",
"envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz",
"type": "SIGNATURE",
"recipientId": 456,
"page": 1,
"positionX": 10,
"positionY": 85,
"width": 30,
"height": 5,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "signature"
}
},
{
"id": 102,
"secondaryId": "field_def456",
"envelopeId": "clu1abc2def3ghi4jkl",
"envelopeItemId": "envelope_item_xyz",
"type": "DATE",
"recipientId": 456,
"page": 1,
"positionX": 50,
"positionY": 85,
"width": 20,
"height": 3,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "date"
}
}
] ]
} }
```` ````
@@ -443,8 +504,8 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
(0,0) ─────────────────────────── (100,0) (0,0) ─────────────────────────── (100,0)
│ │ │ │
│ ┌─────────┐ │ │ ┌─────────┐ │
│ │ Field │ (pageX: 10, │ │ │ Field │ (positionX: 10, │
│ │ │ pageY: 20, │ │ │ │ positionY: 20, │
│ └─────────┘ width: 30, │ │ └─────────┘ width: 30, │
│ height: 5) │ │ height: 5) │
│ │ │ │
@@ -457,9 +518,9 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
const field = { const field = {
type: 'SIGNATURE', type: 'SIGNATURE',
recipientId: 123, recipientId: 123,
pageNumber: 1, page: 1,
pageX: 60, // 60% from left positionX: 60, // 60% from left
pageY: 85, // 85% from top (near bottom) positionY: 85, // 85% from top (near bottom)
width: 30, // 30% of page width width: 30, // 30% of page width
height: 8, // 8% of page height height: 8, // 8% of page height
}; };
@@ -643,15 +704,15 @@ All field types support these base options:
Create a document with a signature block containing multiple field types: Create a document with a signature block containing multiple field types:
```typescript ```typescript
async function addSignatureBlock(documentId: number, recipientId: number) { async function addSignatureBlock(envelopeId: string, recipientId: number) {
const fields = [ const data = [
// Signature // Signature
{ {
type: 'SIGNATURE', type: 'SIGNATURE',
recipientId, recipientId,
pageNumber: 1, page: 1,
pageX: 10, positionX: 10,
pageY: 80, positionY: 80,
width: 30, width: 30,
height: 8, height: 8,
fieldMeta: { fieldMeta: {
@@ -663,9 +724,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
{ {
type: 'NAME', type: 'NAME',
recipientId, recipientId,
pageNumber: 1, page: 1,
pageX: 10, positionX: 10,
pageY: 90, positionY: 90,
width: 30, width: 30,
height: 4, height: 4,
fieldMeta: { fieldMeta: {
@@ -677,9 +738,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
{ {
type: 'DATE', type: 'DATE',
recipientId, recipientId,
pageNumber: 1, page: 1,
pageX: 50, positionX: 50,
pageY: 80, positionY: 80,
width: 20, width: 20,
height: 4, height: 4,
fieldMeta: { fieldMeta: {
@@ -691,9 +752,9 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
{ {
type: 'TEXT', type: 'TEXT',
recipientId, recipientId,
pageNumber: 1, page: 1,
pageX: 50, positionX: 50,
pageY: 90, positionY: 90,
width: 30, width: 30,
height: 4, height: 4,
fieldMeta: { fieldMeta: {
@@ -710,7 +771,7 @@ async function addSignatureBlock(documentId: number, recipientId: number) {
Authorization: 'api_xxxxxxxxxxxxxxxx', Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json', 'Content-Type': 'application/json',
}, },
body: JSON.stringify({ documentId, fields }), body: JSON.stringify({ envelopeId, data }),
}); });
return response.json(); return response.json();