# Templates API

> List WPsigner templates and create documents from a template with variable prefill 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/templates/
Markdown: https://docs.wpsigner.com/md/api/templates.md
Source file: api/templates.md

---

The Templates API lets you discover saved PDF templates, inspect their prefillable variable keys, and create a signing document from a template in one request—ideal for Zapier, Calendly, CRM, and custom automations.

> **Template setup**
Assign variable keys in either place:

- **While placing fields** — double-click a field in **New Document** / **Campaign** → **Mapping name** (empty = use the field name). See [Form fields](/core-features/form-fields/#field-name-mapping-name-and-placeholder).
- **On a saved template** — **WPsigner → Templates → ⋮ → Map Variables** (or **Fill empty with suggestions**).

Those keys are what you pass in the `variables` object / Zapier fields. New templates saved from a document get suggested keys automatically.

## List Templates

```http
GET /wp-json/insigner/v1/templates
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `search` | string | — | Filter by template name/description |
| `per_page` | integer | `50` | Max results (1–100) |

### Example Request

```bash
curl -X GET "https://your-site.com/wp-json/insigner/v1/templates?per_page=20" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret"
```

### Response

```json
[
  {
    "id": 12,
    "name": "Property Showing Agreement",
    "description": "",
    "original_filename": "showing-agreement.pdf",
    "total_pages": 2,
    "created_at": "2026-07-01 10:00:00",
    "updated_at": "2026-07-15 14:30:00",
    "variables": [
      { "key": "client_name", "label": "Client Name", "field_type": "name" },
      { "key": "property_address", "label": "Property Address", "field_type": "text" },
      { "key": "appointment_date", "label": "Appointment Date", "field_type": "date" }
    ]
  }
]
```

Non-admin users only see their own templates. Administrators and users with full WPsigner manage access see all templates.

---

## Get Template

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

Returns the same shape as a list item, including the `variables` array.

### Example Request

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

---

## Create Document from Template

Clone a template into a new document, optionally prefill fields, add signers, and email signing invitations.

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

> **Note:** Requires **Full Access**. Prefill only applies to non-signature fields that have a matching variable key.

### Path Parameters

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

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `title` | string | No | Template name + date/time | Document title |
| `signers` | array | No* | — | `[{ "name", "email", "role?", "signing_order?", "require_wp_login?" }]` |
| `signer_name` | string | No* | — | Convenience single signer name (used when `signers` is empty) |
| `signer_email` | string | No* | — | Convenience single signer email |
| `variables` | object | No | `{}` | Map of variable keys to values |
| `client_name` | string | No | — | Merged into `variables.client_name` if not set |
| `property_address` | string | No | — | Merged into `variables.property_address` if not set |
| `appointment_date` | string | No | — | Merged into `variables.appointment_date` if not set |
| `send` | boolean | No | `true` | When `true`, emails signing invitations immediately |

\* At least one signer is required when `send` is `true`.

### Example Request (Calendly-style)

```bash
curl -X POST "https://your-site.com/wp-json/insigner/v1/templates/12/documents" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Showing Agreement - Jane Smith",
    "signer_name": "Jane Smith",
    "signer_email": "jane@example.com",
    "variables": {
      "client_name": "Jane Smith",
      "property_address": "123 Main Street, Austin, TX",
      "appointment_date": "2026-08-10 14:00"
    },
    "send": true
  }'
```

### Response (`201 Created`)

```json
{
  "id": 456,
  "document_id": 456,
  "template_id": 12,
  "title": "Showing Agreement - Jane Smith",
  "status": "sent",
  "prefilled": true,
  "sent": true,
  "message": "Document sent successfully.",
  "signers": [
    {
      "id": 10,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "signer",
      "signing_order": "1",
      "status": "pending",
      "signing_url": "https://your-site.com/?wps_sign=abc123"
    }
  ],
  "send_error": null
}
```

| Field | Description |
|-------|-------------|
| `prefilled` | `true` if at least one template field received a variable value |
| `sent` | `true` if invitations were emailed |
| `signers[].signing_url` | Unique signing link for that signer |

### Notes

- Prefill writes values into WPsigner fields on the PDF (not binary PDF text merge).
- Signature / initials fields are never auto-filled.
- `require_wp_login: true` on a signer is refused unless that email already belongs to a WordPress user.
- Set `send` to `false` if you want to review the draft first, then call [`POST /documents/{id}/send`](/api/documents/#send-document).

## Related

- [Zapier Integration](/integrations/zapier/) — native **Create Document from Template** action
- [Documents API](/api/documents/)
- [Signers API](/api/signers/)