Signers API

The Signers API allows you to manage signers associated with your documents. Each document can have multiple signers who will receive signing invitations.

List Signers

Get all signers for a specific document.

GET /wp-json/insigner/v1/documents/{id}/signers

Path Parameters

Parameter	Type	Description
id	integer	Required. Document ID

Example Request

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

Response

[
  {
    "id": "38",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "signer",
    "signing_order": "1",
    "status": "signed",
    "viewed_at": "2024-01-20 14:00:00",
    "signed_at": "2024-01-20 15:30:45",
    "signing_url": "https://your-site.com/?wps_sign=abc123-def456"
  },
  {
    "id": "39",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "signer",
    "signing_order": "2",
    "status": "pending",
    "viewed_at": null,
    "signed_at": null,
    "signing_url": "https://your-site.com/?wps_sign=ghi789-jkl012"
  }
]

Response Fields

Field	Type	Description
id	string	Signer ID
name	string	Signer’s full name
email	string	Signer’s email address
role	string	Role: signer, viewer, approver
signing_order	string	Order in signing sequence
status	string	Current status
viewed_at	string/null	Timestamp when document was viewed
signed_at	string/null	Timestamp when document was signed
signing_url	string	Unique URL for this signer

Signer Status Values

Status	Description
pending	Awaiting action from signer
viewed	Signer has viewed the document
signed	Signer has signed the document
declined	Signer declined to sign

---

Add Signer

Add a new signer to a document.

POST /wp-json/insigner/v1/documents/{id}/signers

Note: This endpoint requires Full Access permission.

Path Parameters

Parameter	Type	Description
id	integer	Required. Document ID

Request Body

Parameter	Type	Required	Default	Description
name	string	Yes	-	Signer’s full name
email	string	Yes	-	Signer’s email address
role	string	No	signer	Role type
signing_order	integer	No	1	Order in signing sequence
require_wp_login	boolean	No	false	When true, the signer must be logged in with the WordPress account that uses this email. The email must already belong to a WordPress user. Refused if the document has an active public campaign

Signer Roles

Role	Description
signer	Must sign the document
viewer	Can only view, no signature required
approver	Must approve before others can sign (3.2.20+). Receives a Review & Approve email. Signers are invited only after every approver accepts.

Example Request

curl -X POST "https://your-site.com/wp-json/insigner/v1/documents/44/signers" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "signer",
    "signing_order": 3
  }'

Response

{
  "id": "40",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "signer",
  "signing_order": "3",
  "status": "pending",
  "signing_url": "https://your-site.com/?wps_sign=mno345-pqr678"
}

---

Sequential vs Parallel Signing

WPsigner supports both sequential and parallel signing workflows.

Sequential Signing

When signers have different signing_order values, they will receive invitations in order:

{
  "signers": [
    { "name": "Manager", "signing_order": 1 },
    { "name": "Director", "signing_order": 2 },
    { "name": "CEO", "signing_order": 3 }
  ]
}

In this example:

1. Manager receives invitation first
2. After Manager signs, Director receives invitation
3. After Director signs, CEO receives invitation

Parallel Signing

When signers have the same signing_order value, they can sign simultaneously:

{
  "signers": [
    { "name": "Employee A", "signing_order": 1 },
    { "name": "Employee B", "signing_order": 1 },
    { "name": "Supervisor", "signing_order": 2 }
  ]
}

In this example:

1. Employee A and Employee B receive invitations at the same time
2. After both employees sign, Supervisor receives invitation

---

Signer Information in Document Details

When you retrieve a document via GET /documents/{id}, the signers array includes additional details:

{
  "signers": [
    {
      "id": "38",
      "document_id": "44",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "signer",
      "signing_order": "1",
      "status": "signed",
      "viewed_at": "2024-01-20 14:00:00",
      "signed_at": "2024-01-20 15:30:45",
      "declined_at": null,
      "decline_reason": null,
      "created_at": "2024-01-15 10:05:00",
      "updated_at": "2024-01-20 15:30:45"
    }
  ]
}

Additional Fields in Document Details

Field	Type	Description
document_id	string	Parent document ID
declined_at	string/null	When signer declined
decline_reason	string/null	Reason for declining
created_at	string	When signer was added
updated_at	string	Last update timestamp

---

Security Note

For security reasons, the following sensitive fields are never exposed via the API:

• access_token - The unique signing token
• pin_code - OTP verification code
• signature_ip - Signer’s IP address
• signature_user_agent - Signer’s browser info

These fields are only stored internally for audit and security purposes.

---

Best Practices

1. Validate Email Addresses

Always validate email addresses before adding signers:

const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
  throw new Error('Invalid email address');
}

2. Check Document Status Before Adding

You cannot add signers to completed or expired documents:

// First check document status
const doc = await fetch(`/documents/${id}`);
if (['completed', 'expired', 'declined'].includes(doc.status)) {
  throw new Error('Cannot modify signers on this document');
}

3. Use Meaningful Signing Order

Plan your signing workflow before adding signers:

const signers = [
  { name: 'Manager', role: 'approver', signing_order: 1 },
  { name: 'Employee', role: 'signer', signing_order: 2 },
  { name: 'Witness', role: 'signer', signing_order: 3 }
];

---

Error Responses

Failed to Add Signer

{
  "code": "create_failed",
  "message": "Failed to add signer.",
  "data": {
    "status": 500
  }
}

Document Not Found

{
  "code": "not_found",
  "message": "Document not found.",
  "data": {
    "status": 404
  }
}