Documents API

The Documents API allows you to manage documents in your WPsigner installation. You can create new documents, retrieve their details, update metadata, and delete them.

List Documents

Retrieve a paginated list of all documents.

GET /wp-json/wpsigner/v1/documents

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number for pagination
`per_page`	integer	20	Number of documents per page (max: 100)
`status`	string	-	Filter by status: `draft`, `sent`, `viewed`, `completed`, `declined`, `expired`
`search`	string	-	Search documents by title

Example Request

curl -X GET "https://your-site.com/wp-json/wpsigner/v1/documents?per_page=10&status=completed" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret"

Response

[
  {
    "id": "44",
    "title": "Employment Contract",
    "status": "completed",
    "original_filename": "contract.pdf",
    "total_pages": "5",
    "expires_at": "2024-03-15 12:00:00",
    "completed_at": "2024-01-20 15:30:45",
    "created_at": "2024-01-15 10:00:00",
    "updated_at": "2024-01-20 15:30:45"
  },
  {
    "id": "43",
    "title": "NDA Agreement",
    "status": "sent",
    "original_filename": "nda.pdf",
    "total_pages": "3",
    "expires_at": "2024-02-28 23:59:59",
    "completed_at": null,
    "created_at": "2024-01-14 09:00:00",
    "updated_at": "2024-01-14 09:15:00"
  }
]

Response Headers

Header	Description
`X-WP-Total`	Total number of documents
`X-WP-TotalPages`	Total number of pages

Get Document

Retrieve a single document with full details, including signers and fields.

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

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" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret"

Response

{
  "id": "44",
  "title": "Employment Contract",
  "status": "completed",
  "original_filename": "contract.pdf",
  "total_pages": "5",
  "expires_at": "2024-03-15 12:00:00",
  "completed_at": "2024-01-20 15:30:45",
  "created_at": "2024-01-15 10:00:00",
  "updated_at": "2024-01-20 15:30:45",
  "file_url": "https://your-site.com/wp-content/wpsigner-secure/documents/abc123.enc",
  "file_hash": "8228aa40168a599d2296e1274eb9dc9d7982d93e40135b8ed9131f1b4e2de5f8",
  "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"
    }
  ],
  "fields": [
    {
      "id": "74",
      "document_id": "44",
      "signer_id": "38",
      "field_type": "signature",
      "page_number": "5",
      "position_x": "90.0",
      "position_y": "276.9",
      "width": "200",
      "height": "60",
      "is_required": "1"
    }
  ]
}

Document Status Values

Status	Description
`draft`	Document created but not sent
`sent`	Sent to signers, awaiting action
`viewed`	At least one signer has viewed
`completed`	All signers have signed
`declined`	A signer declined to sign
`expired`	Document has expired

Create Document

Create a new document. The file must already be uploaded to WordPress media library.

POST /wp-json/wpsigner/v1/documents

Note: This endpoint requires Full Access permission.

Request Body

Parameter	Type	Required	Description
`title`	string	Yes	Document title
`file_path`	string	Yes	Full path to the PDF file
`original_filename`	string	Yes	Original filename

Example Request

curl -X POST "https://your-site.com/wp-json/wpsigner/v1/documents" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Contract",
    "file_path": "/var/www/html/wp-content/uploads/2024/01/contract.pdf",
    "original_filename": "contract.pdf"
  }'

Response

{
  "id": "45",
  "title": "New Contract",
  "status": "draft",
  "original_filename": "contract.pdf",
  "total_pages": null,
  "expires_at": null,
  "completed_at": null,
  "created_at": "2024-01-25 10:00:00",
  "updated_at": "2024-01-25 10:00:00"
}

Update Document

Update a document’s title or status.

PUT /wp-json/wpsigner/v1/documents/{id}

Note: This endpoint requires Full Access permission.

Path Parameters

Parameter	Type	Description
`id`	integer	Required. Document ID

Request Body

Parameter	Type	Description
`title`	string	New document title
`status`	string	New status

Example Request

curl -X PUT "https://your-site.com/wp-json/wpsigner/v1/documents/45" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Contract Title"
  }'

Response

Returns the updated document object.

Delete Document

Permanently delete a document and all associated data.

DELETE /wp-json/wpsigner/v1/documents/{id}

Note: This endpoint requires Full Access permission.

Warning: This action cannot be undone. All signers, fields, and audit records will be deleted.

Path Parameters

Parameter	Type	Description
`id`	integer	Required. Document ID

Example Request

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

Response

{
  "deleted": true
}

Send Document

Send a document to all signers for signing. This will email signing invitations.

POST /wp-json/wpsigner/v1/documents/{id}/send

Note: This endpoint requires Full Access permission.

Prerequisites

Before sending, ensure:

At least one signer is added to the document
All required fields are placed on the document

Path Parameters

Parameter	Type	Description
`id`	integer	Required. Document ID

Example Request

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

Response

{
  "sent": true,
  "message": "Document sent successfully."
}

Error Response

{
  "code": "no_signers",
  "message": "Please add at least one signer.",
  "data": {
    "status": 400
  }
}

Get Document File

Get the document file URL for download.

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

Response

{
  "url": "https://your-site.com/wp-content/wpsigner-secure/documents/abc123.enc",
  "filename": "contract.pdf",
  "type": "application/pdf"
}

Get Audit Trail

Retrieve the complete audit trail for a document.

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

Response

{
  "document": {
    "id": "44",
    "title": "Employment Contract",
    "file_hash": "8228aa40168a599d..."
  },
  "events": [
    {
      "action": "document_created",
      "timestamp": "2024-01-15 10:00:00",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0..."
    },
    {
      "action": "document_viewed",
      "timestamp": "2024-01-20 14:00:00",
      "signer": "John Doe",
      "ip_address": "203.0.113.50"
    },
    {
      "action": "document_signed",
      "timestamp": "2024-01-20 15:30:45",
      "signer": "John Doe",
      "ip_address": "203.0.113.50"
    }
  ]
}

Common Errors

Document Not Found

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

Permission Denied

When trying to access a document you don’t own (non-admin users):

{
  "code": "forbidden",
  "message": "Permission denied.",
  "data": {
    "status": 403
  }
}