# REST API Overview

> Complete guide to the WPsigner REST API for developers.

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/
Markdown: https://docs.wpsigner.com/md/api.md
Source file: api/index.md

---

The WPsigner REST API allows you to interact with your documents, signers, and signing workflows programmatically. Built on top of the WordPress REST API, it provides secure endpoints for managing electronic signatures.

> **Requires WPsigner Pro**
The public REST API and API keys are **Pro** features. [Upgrade to Pro](https://wpsigner.com/pricing/?utm_source=docs&utm_medium=upgrade&utm_campaign=api) · [Lite vs Pro](/getting-started/lite-vs-pro/)

> **Self-hosted: one API per WordPress site**
There is no global API on `wpsigner.com`. After you install the plugin on **your** WordPress site, the API is available at `https://your-site.com/wp-json/insigner/v1/`. Credentials are created in that site's admin panel.

## Base URL

All API endpoints are available at:

```
https://your-site.com/wp-json/insigner/v1/
```

Replace `your-site.com` with the domain where WPsigner is installed and licensed.

## Authentication

WPsigner uses API Key + Secret authentication. You'll need to generate credentials from the WordPress admin panel.

### Generating API Credentials

1. Go to **inSigner → API** in your WordPress admin
2. Click **Create New Key**
3. Enter a name and description for your key
4. Select the permission level:
   - **Full Access**: Read and write operations
   - **Read Only**: Only GET requests allowed
5. Click **Create Key**
6. **Important**: Copy and save the API Secret immediately. It will only be shown once!

### Using API Credentials

Include the following headers in all API requests:

```bash
X-WPS-API-Key: wps_your_api_key_here
X-WPS-API-Secret: your_api_secret_here
```

### Example Request

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

## Response Format

All responses are returned in JSON format. Successful responses typically include the requested data:

```json
{
  "id": "44",
  "title": "Contract Agreement",
  "status": "sent",
  "created_at": "2024-01-15 10:30:00"
}
```

### Error Responses

Errors follow the WordPress REST API error format:

```json
{
  "code": "rest_forbidden",
  "message": "Invalid API key or secret.",
  "data": {
    "status": 401
  }
}
```

### HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `201` | Created (for POST requests) |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing credentials |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Resource doesn't exist |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error |

## Rate Limiting

To protect your server and ensure fair usage, the API implements rate limiting:

- **Per API Key**: 1,000 requests per hour (configurable per key)
- **Per IP Address**: 100 requests per minute (applies to all REST requests)

When you exceed the rate limit, you'll receive a `429` response (not `401`) with a `Retry-After` header:

```json
{
  "code": "rate_limit_exceeded",
  "message": "API key rate limit exceeded (1000 requests/hour). Please wait 45 seconds.",
  "data": {
    "status": 429,
    "retry_after": 45
  }
}
```

## Permissions

API key permissions determine which operations are allowed:

| Permission | GET | POST | PUT | DELETE |
|------------|-----|------|-----|--------|
| **Full Access** | ✅ | ✅ | ✅ | ✅ |
| **Read Only** | ✅ | ❌ | ❌ | ❌ |

If you attempt a write operation with a Read Only key, you'll receive:

```json
{
  "code": "rest_forbidden",
  "message": "This API key has read-only permissions.",
  "data": {
    "status": 403
  }
}
```

## Available Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/documents` | List all documents |
| `POST` | `/documents/upload` | Upload PDF/PNG/JPG and create a document |
| `POST` | `/documents` | Create from existing secure `file_path` (advanced) |
| `GET` | `/documents/{id}` | Get document details |
| `PUT` | `/documents/{id}` | Update a document |
| `DELETE` | `/documents/{id}` | Delete a document |
| `GET` | `/documents/{id}/signers` | List signers |
| `POST` | `/documents/{id}/signers` | Add a signer |
| `GET` | `/documents/{id}/fields` | List document fields |
| `POST` | `/documents/{id}/fields` | Save document fields |
| `POST` | `/documents/{id}/send` | Send for signing |
| `POST` | `/documents/{id}/remind` | Remind pending/viewed signers |
| `POST` | `/documents/{id}/expire` | Apply an expiration that is already due |
| `GET` | `/documents/{id}/file` | Download PDF as base64 JSON |
| `GET` | `/documents/{id}/audit` | Get audit trail |
| `GET` | `/templates` | List templates (with variable keys) |
| `GET` | `/templates/{id}` | Get template details |
| `POST` | `/templates/{id}/documents` | Create document from template (prefill + optional send) |
| `GET` | `/stats` | Get statistics |

## Next Steps

- [Documents API](/api/documents/) - Work with documents
- [Templates API](/api/templates/) - Create documents from templates with variables
- [Signers API](/api/signers/) - Manage signers
- [Webhooks](/api/webhooks/) - Receive real-time notifications