Fields API

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.

GET /wp-json/wpsigner/v1/documents/{id}/fields

Path Parameters

Parameter	Type	Description
id	integer	Required. Document ID

Example Request

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

Response

[
  {
    "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.

POST /wp-json/wpsigner/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

{
  "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

curl -X POST "https://your-site.com/wp-json/wpsigner/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:

[
  {
    "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:

{
  "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

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

Field Validation Failed

{
  "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:

// 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:

// 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:

// 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 })
});