Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2026-06-22 04:12:06 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
03e2e4f171b3d35f7464294d149724aa19456379
documenso/apps/docs/content/docs/developers/api/fields.mdx
T

743 lines
18 KiB
Plaintext
Raw Blame History

---
title: Fields API
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';
<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>
## Field Object
| Property | Type | Description |
| ---------------- | -------------- | -------------------------------------------- |
| `id` | number | Unique field identifier |
| `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 |
| `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) |
| `customText` | string | Value entered by the recipient |
| `inserted` | boolean | Whether the field has been completed |
| `fieldMeta` | object \| null | Type-specific configuration options |
### Example Field Object
```json
{
"id": 456,
"secondaryId": "field_abc123",
"type": "SIGNATURE",
"recipientId": 123,
"envelopeId": 789,
"envelopeItemId": "envelope_item_xyz",
"page": 1,
"positionX": 10,
"positionY": 80,
"width": 30,
"height": 5,
"customText": "",
"inserted": false,
"fieldMeta": {
"type": "signature",
"required": true
}
}
```
---
## Field Types
| Type | Description | Auto-filled |
| ---------------- | ----------------------------------------- | ----------- |
| `SIGNATURE` | Drawn, typed, or uploaded signature | No |
| `FREE_SIGNATURE` | Unrestricted signature without validation | No |
| `INITIALS` | Recipient's initials | No |
| `NAME` | Recipient's full name | Yes |
| `EMAIL` | Recipient's email address | Yes |
| `DATE` | Date the field was completed | Yes |
| `TEXT` | Free-form text input | No |
| `NUMBER` | Numeric input with optional validation | No |
| `RADIO` | Single selection from options | No |
| `CHECKBOX` | Multiple selections from options | No |
| `DROPDOWN` | Single selection from a dropdown menu | No |
---
## Get Field
Retrieve a single field by ID.
```
GET /envelope/field/{fieldId}
```
### Path Parameters
| Parameter | Type | Description |
| --------- | ------ | ------------ |
| `fieldId` | number | The field ID |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X GET "https://app.documenso.com/api/v2/envelope/field/456" \
-H "Authorization: api_xxxxxxxxxxxxxxxx"
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch(
'https://app.documenso.com/api/v2/envelope/field/456',
{
method: 'GET',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
},
}
);
const field = await response.json();
console.log(field.type, field.page);
```
</Tab>
</Tabs>
### Response
Returns the field object.
---
## Create Fields
Add one or more fields to a document.
```
POST /envelope/field/create-many
````
### Request Body
| Field | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------- |
| `documentId`| number | Yes | The document ID |
| `fields` | array | Yes | Array of field configurations |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
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": [
{
"type": "SIGNATURE",
"recipientId": 456,
"pageNumber": 1,
"pageX": 10,
"pageY": 80,
"width": 30,
"height": 5
},
{
"type": "DATE",
"recipientId": 456,
"pageNumber": 1,
"pageX": 50,
"pageY": 80,
"width": 20,
"height": 3
},
{
"type": "TEXT",
"recipientId": 456,
"pageNumber": 1,
"pageX": 10,
"pageY": 70,
"width": 40,
"height": 4,
"fieldMeta": {
"type": "text",
"label": "Job Title",
"placeholder": "Enter your job title",
"required": true
}
}
]
}'
````
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch(
'https://app.documenso.com/api/v2/envelope/field/create-many',
{
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
documentId: 123,
fields: [
{
type: 'SIGNATURE',
recipientId: 456,
pageNumber: 1,
pageX: 10,
pageY: 80,
width: 30,
height: 5,
},
{
type: 'DATE',
recipientId: 456,
pageNumber: 1,
pageX: 50,
pageY: 80,
width: 20,
height: 3,
},
{
type: 'TEXT',
recipientId: 456,
pageNumber: 1,
pageX: 10,
pageY: 70,
width: 40,
height: 4,
fieldMeta: {
type: 'text',
label: 'Job Title',
placeholder: 'Enter your job title',
required: true,
},
},
],
}),
}
);
const { fields } = await response.json();
console.log(`Created ${fields.length} fields`);
````
</Tab>
</Tabs>
### Response
```json
{
"fields": [
{
"id": 101,
"type": "SIGNATURE",
"recipientId": 456,
"page": 1,
"positionX": 10,
"positionY": 80,
"width": 30,
"height": 5
},
{
"id": 102,
"type": "DATE",
"recipientId": 456,
"page": 1,
"positionX": 50,
"positionY": 80,
"width": 20,
"height": 3
},
{
"id": 103,
"type": "TEXT",
"recipientId": 456,
"page": 1,
"positionX": 10,
"positionY": 70,
"width": 40,
"height": 4
}
]
}
````
---
## Update Fields
Update one or more fields in a single request.
```
POST /envelope/field/update-many
```
### Request Body
| Field | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------- |
| `documentId` | number | Yes | The document ID |
| `fields` | array | Yes | Array of field update objects |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
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": [
{
"id": 101,
"type": "SIGNATURE",
"pageY": 85
},
{
"id": 102,
"type": "DATE",
"pageY": 85
}
]
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch(
'https://app.documenso.com/api/v2/envelope/field/update-many',
{
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
documentId: 123,
fields: [
{ id: 101, type: 'SIGNATURE', pageY: 85 },
{ id: 102, type: 'DATE', pageY: 85 },
],
}),
}
);
const { fields } = await response.json();
````
</Tab>
</Tabs>
### Response
```json
{
"fields": [
{ "id": 101, "type": "SIGNATURE", "positionY": 85 },
{ "id": 102, "type": "DATE", "positionY": 85 }
]
}
````
---
## Delete Field
Remove a field from a document.
```
POST /envelope/field/delete
```
### Request Body
| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------ |
| `fieldId` | number | Yes | The field ID |
### Code Examples
<Tabs items={['curl', 'TypeScript']}>
<Tab value="curl">
```bash
curl -X POST "https://app.documenso.com/api/v2/envelope/field/delete" \
-H "Authorization: api_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"fieldId": 456
}'
```
</Tab>
<Tab value="TypeScript">
```typescript
const response = await fetch(
'https://app.documenso.com/api/v2/envelope/field/delete',
{
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fieldId: 456,
}),
}
);
const { success } = await response.json();
````
</Tab>
</Tabs>
### Response
```json
{
"success": true
}
````
---
## Field Positioning
Fields use percentage-based coordinates relative to the PDF page dimensions.
| Property | Range | Description |
| ----------- | ----- | -------------------------------------------------- |
| `positionX` | 0-100 | Horizontal position from left edge (0 = left edge) |
| `positionY` | 0-100 | Vertical position from top edge (0 = top edge) |
| `width` | 0-100 | Field width as percentage of page width |
| `height` | 0-100 | Field height as percentage of page height |
| `page` | 1+ | Page number (1-indexed) |
### Coordinate System
```
(0,0) ─────────────────────────── (100,0)
│ │
│ ┌─────────┐ │
│ │ Field │ (pageX: 10, │
│ │ │ pageY: 20, │
│ └─────────┘ width: 30, │
│ height: 5) │
│ │
(0,100) ─────────────────────────(100,100)
```
### Example: Position a Signature at Bottom Right
```typescript
const field = {
type: 'SIGNATURE',
recipientId: 123,
pageNumber: 1,
pageX: 60, // 60% from left
pageY: 85, // 85% from top (near bottom)
width: 30, // 30% of page width
height: 8, // 8% of page height
};
```
---
## Placeholder-Based Field Positioning
Instead of specifying exact coordinates, you can position fields using placeholder text embedded in your PDF. Include placeholder markers such as `{{signature, r1}}` in your document, and Documenso will create fields at those locations when the document is uploaded.
This approach is useful when generating PDFs programmatically or using templates with consistent layouts.
<Callout type="info">
Placeholder support is only available in `envelope.*` endpoints. `POST /template/use` does not support placeholder parsing.
</Callout>
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.
---
## Field Meta Options
Each field type supports specific configuration through `fieldMeta`.
### Common Options
All field types support these base options:
| Option | Type | Description |
| ------------- | ------- | --------------------------------------- |
| `label` | string | Display text shown near the field |
| `placeholder` | string | Hint text when field is empty |
| `required` | boolean | Whether field must be completed |
| `readOnly` | boolean | Lock field with a pre-filled value |
| `fontSize` | number | Text size in pixels (8-96, default: 12) |
### Signature Field
```json
{
"type": "SIGNATURE",
"fieldMeta": {
"type": "signature",
"required": true
}
}
```
### Text Field
```json
{
"type": "TEXT",
"fieldMeta": {
"type": "text",
"label": "Company Name",
"placeholder": "Enter company name",
"text": "Default value",
"characterLimit": 100,
"textAlign": "left",
"required": true
}
}
```
| Option | Type | Description |
| ---------------- | ------ | ---------------------------------- |
| `text` | string | Default value |
| `characterLimit` | number | Maximum characters allowed |
| `textAlign` | string | `left`, `center`, or `right` |
| `lineHeight` | number | Spacing between lines (1-10) |
| `letterSpacing` | number | Spacing between characters (0-100) |
### Number Field
```json
{
"type": "NUMBER",
"fieldMeta": {
"type": "number",
"label": "Quantity",
"minValue": 1,
"maxValue": 100,
"value": "10",
"required": true
}
}
```
| Option | Type | Description |
| -------------- | ------ | --------------------- |
| `value` | string | Default value |
| `minValue` | number | Minimum allowed value |
| `maxValue` | number | Maximum allowed value |
| `numberFormat` | string | Display format |
### Date Field
```json
{
"type": "DATE",
"fieldMeta": {
"type": "date",
"textAlign": "left",
"required": true
}
}
```
### Checkbox Field
```json
{
"type": "CHECKBOX",
"fieldMeta": {
"type": "checkbox",
"label": "Agreements",
"values": [
{ "id": 1, "value": "Terms of Service", "checked": false },
{ "id": 2, "value": "Privacy Policy", "checked": false }
],
"validationRule": "min",
"validationLength": 1,
"direction": "vertical",
"required": true
}
}
```
| Option | Type | Description |
| ------------------ | ------ | --------------------------------- |
| `values` | array | List of checkbox options |
| `validationRule` | string | Validation type for selections |
| `validationLength` | number | Number for validation rule |
| `direction` | string | `vertical` or `horizontal` layout |
### Radio Field
```json
{
"type": "RADIO",
"fieldMeta": {
"type": "radio",
"label": "Payment Method",
"values": [
{ "id": 1, "value": "Credit Card", "checked": false },
{ "id": 2, "value": "Bank Transfer", "checked": true },
{ "id": 3, "value": "Check", "checked": false }
],
"direction": "vertical",
"required": true
}
}
```
### Dropdown Field
```json
{
"type": "DROPDOWN",
"fieldMeta": {
"type": "dropdown",
"label": "Country",
"values": [{ "value": "United States" }, { "value": "Canada" }, { "value": "United Kingdom" }],
"defaultValue": "United States",
"required": true
}
}
```
| Option | Type | Description |
| -------------- | ------ | ------------------------ |
| `values` | array | List of dropdown options |
| `defaultValue` | string | Pre-selected option |
---
## Complete Example
Create a document with a signature block containing multiple field types:
```typescript
async function addSignatureBlock(documentId: number, recipientId: number) {
const fields = [
// Signature
{
type: 'SIGNATURE',
recipientId,
pageNumber: 1,
pageX: 10,
pageY: 80,
width: 30,
height: 8,
fieldMeta: {
type: 'signature',
required: true,
},
},
// Printed name
{
type: 'NAME',
recipientId,
pageNumber: 1,
pageX: 10,
pageY: 90,
width: 30,
height: 4,
fieldMeta: {
type: 'name',
label: 'Printed Name',
},
},
// Date
{
type: 'DATE',
recipientId,
pageNumber: 1,
pageX: 50,
pageY: 80,
width: 20,
height: 4,
fieldMeta: {
type: 'date',
label: 'Date',
},
},
// Job title
{
type: 'TEXT',
recipientId,
pageNumber: 1,
pageX: 50,
pageY: 90,
width: 30,
height: 4,
fieldMeta: {
type: 'text',
label: 'Title',
placeholder: 'Enter your job title',
},
},
];
const response = await fetch('https://app.documenso.com/api/v2/envelope/field/create-many', {
method: 'POST',
headers: {
Authorization: 'api_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({ documentId, fields }),
});
return response.json();
}
```
---
## Error Responses
| Status | Description |
| ------ | ---------------------------------------------------- |
| `400` | Invalid field configuration or document already sent |
| `401` | Invalid or missing API key |
| `404` | Document, recipient, or field not found |
| `500` | Server error |
<Callout type="warn">
Fields cannot be modified after a document is sent for signing. Make all field changes while the
document is in `DRAFT` status.
</Callout>
---
## See Also
- [Documents API](/docs/developers/api/documents) - Create and manage documents
- [Recipients API](/docs/developers/api/recipients) - Add signers to documents
- [Field Types](/docs/concepts/field-types) - Detailed field type reference
Reference in New Issue View Git Blame Copy Permalink