# Fields API

> Manage document signature fields and form elements via the REST API.

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/api/fields/
Markdown: https://docs.wpsigner.com/md/api/fields.md
Source file: api/fields.md

---

The Fields API allows you to retrieve and manage the signature fields and form elements placed on your documents. Fields define where signers need to sign, initial, or fill in information.

## List Fields

Get all fields for a specific document.

```http
GET /wp-json/insigner/v1/documents/{id}/fields
```

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | integer | **Required.** Document ID |

### Example Request

```bash
curl -X GET "https://your-site.com/wp-json/insigner/v1/documents/44/fields" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret"
```

### Response

```json
[
  {
    "id": "74",
    "document_id": "44",
    "signer_id": "38",
    "field_type": "signature",
    "field_name": "",
    "page_number": "5",
    "position_x": "90.0",
    "position_y": "276.9",
    "width": "200",
    "height": "60",
    "value": "",
    "placeholder": "",
    "is_required": "1",
    "font_size": "14",
    "font_family": "DM Sans",
    "options": "",
    "created_at": "2024-01-15 10:30:00",
    "updated_at": "2024-01-15 10:30:00"
  },
  {
    "id": "75",
    "document_id": "44",
    "signer_id": "38",
    "field_type": "name",
    "field_name": "",
    "page_number": "5",
    "position_x": "115.0",
    "position_y": "337.4",
    "width": "150",
    "height": "30",
    "value": "",
    "is_required": "1"
  },
  {
    "id": "76",
    "document_id": "44",
    "signer_id": "38",
    "field_type": "date",
    "field_name": "",
    "page_number": "5",
    "position_x": "300.0",
    "position_y": "337.4",
    "width": "100",
    "height": "30",
    "value": "",
    "is_required": "1"
  }
]
```

---

## Field Types

WPsigner supports various field types for different signing scenarios:

| Type | Description | Filled By |
|------|-------------|-----------|
| `signature` | Signature field (draw, type, or upload) | Signer |
| `initials` | Initials field | Signer |
| `name` | Auto-filled signer name | Auto |
| `email` | Auto-filled signer email | Auto |
| `date` | Signing date | Auto |
| `text` | Free-form text input | Signer |
| `textarea` | Multi-line text | Signer |
| `checkbox` | Checkbox field | Signer |
| `dropdown` | Dropdown selection | Signer |
| `stamp` | Company stamp or seal | Signer |

---

## Field Properties

### Core Properties

| Property | Type | Description |
|----------|------|-------------|
| `id` | string | Unique field identifier |
| `document_id` | string | Parent document ID |
| `signer_id` | string | Assigned signer ID |
| `field_type` | string | Type of field |
| `field_name` | string | Custom field name/label |

### Position Properties

| Property | Type | Description |
|----------|------|-------------|
| `page_number` | string | Page where field appears (1-indexed) |
| `position_x` | string | X coordinate from left edge (in points) |
| `position_y` | string | Y coordinate from top edge (in points) |
| `width` | string | Field width in points |
| `height` | string | Field height in points |

### Appearance Properties

| Property | Type | Description |
|----------|------|-------------|
| `font_size` | string | Font size in points |
| `font_family` | string | Font family name |
| `placeholder` | string | Placeholder text |

### Behavior Properties

| Property | Type | Description |
|----------|------|-------------|
| `is_required` | string | `1` = required, `0` = optional |
| `value` | string | Current field value |
| `options` | string | Options for dropdown fields (JSON array) |

---

## Save Fields

Save or update all fields for a document. This replaces all existing fields.

```http
POST /wp-json/insigner/v1/documents/{id}/fields
```

> **Note:** This endpoint requires **Full Access** permission.

> **Important:** This endpoint replaces ALL existing fields. Include all fields in your request, not just new ones.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | integer | **Required.** Document ID |

### Request Body

```json
{
  "fields": [
    {
      "signer_id": "38",
      "field_type": "signature",
      "page_number": 5,
      "position_x": 90,
      "position_y": 276.9,
      "width": 200,
      "height": 60,
      "is_required": true
    },
    {
      "signer_id": "38",
      "field_type": "name",
      "page_number": 5,
      "position_x": 115,
      "position_y": 337,
      "width": 150,
      "height": 30,
      "is_required": true
    },
    {
      "signer_id": "38",
      "field_type": "date",
      "page_number": 5,
      "position_x": 300,
      "position_y": 337,
      "width": 100,
      "height": 30,
      "is_required": true
    }
  ]
}
```

### Field Object Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `signer_id` | integer | Yes | ID of assigned signer |
| `field_type` | string | Yes | Type of field |
| `page_number` | integer | Yes | Page number (1-indexed) |
| `position_x` | number | Yes | X position in points |
| `position_y` | number | Yes | Y position in points |
| `width` | number | No | Width (default varies by type) |
| `height` | number | No | Height (default varies by type) |
| `is_required` | boolean | No | Required field (default: true) |
| `font_size` | integer | No | Font size (default: 14) |
| `font_family` | string | No | Font family (default: "DM Sans") |
| `placeholder` | string | No | Placeholder text |
| `options` | array | No | Options for dropdown |

### Example Request

```bash
curl -X POST "https://your-site.com/wp-json/insigner/v1/documents/44/fields" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "signer_id": 38,
        "field_type": "signature",
        "page_number": 5,
        "position_x": 90,
        "position_y": 276.9,
        "width": 200,
        "height": 60,
        "is_required": true
      }
    ]
  }'
```

### Response

Returns the saved fields array:

```json
[
  {
    "id": "80",
    "document_id": "44",
    "signer_id": "38",
    "field_type": "signature",
    "page_number": "5",
    "position_x": "90",
    "position_y": "276.9",
    "width": "200",
    "height": "60",
    "is_required": "1"
  }
]
```

---

## Dropdown Field Options

For dropdown fields, pass options as an array:

```json
{
  "signer_id": 38,
  "field_type": "dropdown",
  "page_number": 1,
  "position_x": 100,
  "position_y": 200,
  "width": 150,
  "height": 30,
  "options": ["Option 1", "Option 2", "Option 3"],
  "placeholder": "Select an option"
}
```

---

## Default Field Sizes

If you don't specify width/height, these defaults are used:

| Field Type | Default Width | Default Height |
|------------|---------------|----------------|
| `signature` | 200 | 60 |
| `initials` | 100 | 50 |
| `name` | 150 | 30 |
| `email` | 200 | 30 |
| `date` | 100 | 30 |
| `text` | 200 | 30 |
| `textarea` | 200 | 80 |
| `checkbox` | 20 | 20 |
| `dropdown` | 150 | 30 |
| `stamp` | 150 | 100 |

---

## Validation Errors

### Invalid Fields Data

```json
{
  "code": "invalid_data",
  "message": "Invalid fields data.",
  "data": {
    "status": 400
  }
}
```

### Field Validation Failed

```json
{
  "code": "validation_failed",
  "message": "Field validation failed.",
  "data": {
    "status": 400,
    "errors": [
      "Field 1: Invalid signer_id",
      "Field 3: page_number is required"
    ]
  }
}
```

---

## Best Practices

### 1. Match Fields to Signers

Ensure every field's `signer_id` corresponds to a valid signer on the document:

```javascript
// Get signers first
const signers = await fetch(`/documents/${id}/signers`);
const validSignerIds = signers.map(s => s.id);

// Validate before saving
fields.forEach(field => {
  if (!validSignerIds.includes(field.signer_id)) {
    throw new Error(`Invalid signer_id: ${field.signer_id}`);
  }
});
```

### 2. Calculate PDF Coordinates

PDF coordinates start from the bottom-left. WPsigner uses top-left origin:

```javascript
// Convert from PDF coordinates to WPsigner coordinates
const wpsY = pageHeight - pdfY - fieldHeight;
```

### 3. Include All Fields When Updating

The fields endpoint replaces all fields. Always include existing fields:

```javascript
// Get existing fields
const existing = await fetch(`/documents/${id}/fields`);

// Add new field to existing
const allFields = [...existing, newField];

// Save all fields
await fetch(`/documents/${id}/fields`, {
  method: 'POST',
  body: JSON.stringify({ fields: allFields })
});
```