# WPsigner Addons Pack

> Document Builder, Smart Signing Forms, ApproveMe Importer, MainWP, Uncanny Automator, and Account Portal.

Generated for AI assistants from the official WPsigner docs.
HTML guide: https://docs.wpsigner.com/support/use-with-ai/
Pages in this pack: 23

## Suggested prompt

```text
You are helping me configure and use WPsigner, a self-hosted electronic-signature plugin for WordPress.
Use ONLY the documentation below as your source of truth.
Each page header includes edition: lite, pro, or both. Never invent Pro-only features for Lite.
If something is not covered, say so clearly and ask for the missing detail.
Prefer exact admin menu paths, shortcodes, endpoints, and settings names from the docs.
```

## Contents

1. [Account Portal](https://docs.wpsigner.com/md/addons/account-portal.md) — https://docs.wpsigner.com/addons/account-portal/
2. [ApproveMe Importer](https://docs.wpsigner.com/md/addons/approveme-importer.md) — https://docs.wpsigner.com/addons/approveme-importer/
3. [Document Builder](https://docs.wpsigner.com/md/addons/document-builder.md) — https://docs.wpsigner.com/addons/document-builder/
4. [WPSigner for MainWP](https://docs.wpsigner.com/md/addons/mainwp.md) — https://docs.wpsigner.com/addons/mainwp/
5. [MainWP — Clients & Sites](https://docs.wpsigner.com/md/addons/mainwp-clients-sites.md) — https://docs.wpsigner.com/addons/mainwp-clients-sites/
6. [MainWP — Creating Contracts](https://docs.wpsigner.com/md/addons/mainwp-creating-contracts.md) — https://docs.wpsigner.com/addons/mainwp-creating-contracts/
7. [MainWP — Installation & Setup](https://docs.wpsigner.com/md/addons/mainwp-installation.md) — https://docs.wpsigner.com/addons/mainwp-installation/
8. [MainWP — Managing Contracts](https://docs.wpsigner.com/md/addons/mainwp-managing-contracts.md) — https://docs.wpsigner.com/addons/mainwp-managing-contracts/
9. [MainWP — Security & Permissions](https://docs.wpsigner.com/md/addons/mainwp-security.md) — https://docs.wpsigner.com/addons/mainwp-security/
10. [MainWP — Settings Reference](https://docs.wpsigner.com/md/addons/mainwp-settings.md) — https://docs.wpsigner.com/addons/mainwp-settings/
11. [MainWP — Template Variables](https://docs.wpsigner.com/md/addons/mainwp-template-variables.md) — https://docs.wpsigner.com/addons/mainwp-template-variables/
12. [MainWP — Troubleshooting](https://docs.wpsigner.com/md/addons/mainwp-troubleshooting.md) — https://docs.wpsigner.com/addons/mainwp-troubleshooting/
13. [Addons Overview](https://docs.wpsigner.com/md/addons/overview.md) — https://docs.wpsigner.com/addons/overview/
14. [Smart Signing Forms](https://docs.wpsigner.com/md/addons/smart-signing-forms.md) — https://docs.wpsigner.com/addons/smart-signing-forms/
15. [WPsigner for Uncanny Automator](https://docs.wpsigner.com/md/addons/uncanny-automator.md) — https://docs.wpsigner.com/addons/uncanny-automator/
16. [Uncanny Automator — Actions](https://docs.wpsigner.com/md/addons/uncanny-automator-actions.md) — https://docs.wpsigner.com/addons/uncanny-automator-actions/
17. [Uncanny Automator — Installation & Setup](https://docs.wpsigner.com/md/addons/uncanny-automator-installation.md) — https://docs.wpsigner.com/addons/uncanny-automator-installation/
18. [Uncanny Automator — Recipe Examples](https://docs.wpsigner.com/md/addons/uncanny-automator-recipes.md) — https://docs.wpsigner.com/addons/uncanny-automator-recipes/
19. [Uncanny Automator — Security](https://docs.wpsigner.com/md/addons/uncanny-automator-security.md) — https://docs.wpsigner.com/addons/uncanny-automator-security/
20. [Uncanny Automator — Settings](https://docs.wpsigner.com/md/addons/uncanny-automator-settings.md) — https://docs.wpsigner.com/addons/uncanny-automator-settings/
21. [Uncanny Automator — Tokens](https://docs.wpsigner.com/md/addons/uncanny-automator-tokens.md) — https://docs.wpsigner.com/addons/uncanny-automator-tokens/
22. [Uncanny Automator — Triggers](https://docs.wpsigner.com/md/addons/uncanny-automator-triggers.md) — https://docs.wpsigner.com/addons/uncanny-automator-triggers/
23. [Uncanny Automator — Troubleshooting](https://docs.wpsigner.com/md/addons/uncanny-automator-troubleshooting.md) — https://docs.wpsigner.com/addons/uncanny-automator-troubleshooting/

---

# Account Portal

> Use app.wpsigner.com to manage licenses, download WPsigner and addons, access beta builds, billing, and support.

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/addons/account-portal/
Markdown: https://docs.wpsigner.com/md/addons/account-portal.md

The **Account Portal** at [app.wpsigner.com](https://app.wpsigner.com/) is where license holders manage their WPsigner account. It is **not** the same as the [Client Portal](/core-features/client-portal/) you embed on your own WordPress site for signers.

| Portal | URL | Purpose |
|--------|-----|---------|
| **Account Portal** | `app.wpsigner.com` | Licenses, downloads, addons, billing |
| **Client Portal** | Your WordPress site | Signer/admin dashboards for your documents |

---

## Accessing the Portal

1. Go to [https://app.wpsigner.com/](https://app.wpsigner.com/)
2. Log in with the WordPress account linked to your purchase
3. Use the sidebar tabs to navigate

Direct links to common tabs:

| Tab | URL |
|-----|-----|
| Licenses | `https://app.wpsigner.com/account/?portal_tab=licenses` |
| Downloads | `https://app.wpsigner.com/account/?portal_tab=downloads` |
| Addons | `https://app.wpsigner.com/account/?portal_tab=addons` |
| Beta Version | `https://app.wpsigner.com/account/?portal_tab=beta` |
| Billing | `https://app.wpsigner.com/account/?portal_tab=billing` |

---

## Portal Tabs

### Licenses

View your license keys, plan type, expiration, and site activations.

- Copy your license key for **WPsigner → License** on your WordPress site
- See how many activations are in use
- Check license status (active, expired, revoked)

### Downloads

Download the latest **WPsigner core plugin** ZIP.

1. Open the **Downloads** tab
2. Click **Download Plugin**
3. Install via **Plugins → Add New → Upload Plugin**

See [Installation](/getting-started/installation/) for detailed steps.

### Addons

Download official **addon ZIP files** (for example Smart Signing Forms).

Each addon appears as a card with:

- Name, version, and description
- **Download** button (requires active license when enabled for that addon)

After downloading:

1. Upload the ZIP in WordPress (**Plugins → Add New → Upload Plugin**)
2. Activate from **WPsigner → Addons**

Full guide: [Addons Overview](/addons/overview/)

> **note**
Download URLs use a **signed token** that expires after about one hour. Refresh the page and download again if a link expires.

### Beta Version

When a beta release is published, licensed users see a **Beta Version** tab.

> **caution**
Beta builds are for **testing only**. Do not install them on production sites. They may contain bugs or breaking changes.

The tab includes:

- Beta version number and release notes
- **Download Beta** button (active license required)

The Beta tab is hidden when no beta is available.

### Billing

If your account uses WooCommerce, view:

- Saved payment methods
- Billing address
- Order history

### Support

- Submit support requests via the support form
- View **My Tickets** for existing conversations

---

## Download vs Addons Tab

| Tab | What you get |
|-----|--------------|
| **Downloads** | Main WPsigner plugin (`wpsigner.zip`) |
| **Addons** | Official extensions (for example `wpsigner-smart-forms.zip`) |

Always download addons from the **Addons** tab — not mixed with the core plugin download.

---

## Link from WPsigner Admin

On **WPsigner → Addons**, the **Download addon** button on each card opens:

```
https://app.wpsigner.com/account/?portal_tab=addons
```

Use it when the addon is not yet installed on your site.

---

## Next Steps

- [Installation](/getting-started/installation/) — Install WPsigner from Downloads
- [Addons Overview](/addons/overview/) — Install Smart Signing Forms
- [Smart Signing Forms](/addons/smart-signing-forms/) — Build your first signing form

---

# ApproveMe Importer

> Import signed WP E-Signature / ApproveMe documents into WPsigner as completed, hashed PDFs with background WP-Cron migration.

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/addons/approveme-importer/
Markdown: https://docs.wpsigner.com/md/addons/approveme-importer.md

**ApproveMe Importer** is an official WPsigner addon that archives **signed** WP E-Signature / ApproveMe documents into WPsigner. Each import becomes a completed WPsigner document with a secure PDF, file hash, signers, audit trail, and the tag **Imported from ApproveMe**.

> **note**
Addon version **1.2.1**. Requires **WPsigner** active, ApproveMe / WP E-Signature tables on the **same** WordPress site, and the ApproveMe **Save as PDF** add-on enabled during import.

---

## What this addon does

| Capability | Detail |
|------------|--------|
| Detection | Finds ApproveMe database tables and counts signed / awaiting / draft documents |
| Signed-only import | Imports documents with ApproveMe status `signed` (archive mode) |
| Native PDF | Uses ApproveMe **Save as PDF** (mPDF) so archived files match the original download |
| Secure storage | Stores each PDF once in WPsigner SecureStorage with a SHA-256 file hash |
| Completed docs | Creates WPsigner documents marked **completed** with signed signers |
| Tagging | Attaches the tag **Imported from ApproveMe** |
| Background jobs | WP-Cron queue with pause, resume, retry failed, and live ETA |

This is a **migration / archive** tool — not a live sync of pending workflows.

---

## Installation

1. Install and activate **WPsigner**
2. Keep **WP E-Signature / ApproveMe** and **Save as PDF** enabled on the same site
3. Download the addon ZIP from the [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons) tab (or your distribution channel)
4. **Plugins → Add New → Upload Plugin** → install the ZIP
5. **WPsigner → Addons → Activate** (or activate via **Plugins**)
6. Open **WPsigner → ApproveMe Import** (button: **Open Importer**)

See [Addons Overview](/addons/overview/) for the general install flow.

### Requirements

| Component | Minimum / notes |
|-----------|-----------------|
| WPsigner | Active (`WPS_VERSION` present) |
| WordPress | 5.8+ |
| PHP | 7.4+ |
| ApproveMe / WP E-Signature | Installed on the same site (tables detectable) |
| Save as PDF | ApproveMe add-on with `ESIG_PDF_Admin` available |
| Capability | `manage_options` or WPsigner `Permissions::can_use_signatures()` |

---

## Before you start

1. **Backup** the WordPress database and files
2. Confirm signed documents appear under ApproveMe
3. Enable **E-Signature → Add-ons → Save as PDF**, then refresh the importer page
4. Plan for large volumes: ~800 documents may take roughly **30–90 minutes** depending on server load
5. Keep ApproveMe + Save as PDF **active until the job finishes**

> **important**
Import is **blocked** until Save as PDF is available. Without it, the Start button stays disabled.

---

## Detection screen

Open **WPsigner → ApproveMe Import**.

When ApproveMe tables are found, the **Detection** card shows:

| Counter | Meaning |
|---------|---------|
| **Signed** | Documents eligible for import |
| **Awaiting** | Not imported (re-send from WPsigner if still needed) |
| **Drafts** | Not imported |
| **Already imported** | Previously migrated (skipped automatically) |
| **Remaining** | Signed minus already imported |

Only **signed** documents are imported. Pending or draft documents should be completed or re-sent from WPsigner.

---

## Background import

### Batch size

| Documents per batch | When to use |
|---------------------|-------------|
| 3 | Safer on shared / limited hosts |
| **5** | Recommended default |
| 8–10 | Faster hosts with more resources |

### Controls

| Action | Behavior |
|--------|----------|
| **Start background import** | Builds a pending-only queue and runs via WP-Cron |
| **Pause** | Stops scheduling new batches |
| **Resume** | Continues the remaining queue |
| **Retry failed** | Re-queues documents that failed |
| **Refresh** | Reloads detection and job status |

### While the job runs

- Progress bar, imported / skipped / failed counters, and ETA update live
- **Safe to close the tab** — WP-Cron continues in the background
- Keeping the tab open **accelerates** processing (browser-assisted ticks)

Each document is:

1. Rendered to PDF once (ApproveMe Save as PDF)
2. Stored in SecureStorage
3. Hashed (WPsigner file hash)
4. Marked **completed** in WPsigner
5. Tagged **Imported from ApproveMe**

---

## What gets imported vs what does not

### Imported

- ApproveMe documents with status **signed**
- PDF archive (native Save as PDF when available)
- Signers with a valid email (status **signed** in WPsigner)
- Signature metadata and a migration audit entry
- Tag **Imported from ApproveMe**

### Not imported

| Item | Notes |
|------|-------|
| Awaiting / draft documents | Not part of archive mode |
| Templates | ApproveMe templates are not migrated |
| Workflows & settings | Not copied |
| Trash | Not imported |
| Cross-site data | Same WordPress install only |
| Signers without email | Omitted (cannot create a WPsigner signer) |

There is **no dry-run** and **no global rollback**. Already imported IDs are skipped, so re-running is safe for remaining documents.

---

## PDF design

| Mode | When | Result |
|------|------|--------|
| **Native (preferred)** | Save as PDF / `ESIG_PDF_Admin` available | Same PDF ApproveMe would download (mPDF) |
| **Fallback** | Native render fails for a document | TCPDF-based archive PDF (layout may differ) |

> **tip**
For the best visual match, leave WP E-Signature and Save as PDF active for the entire migration.

---

## Finding imported documents

After import:

1. Open **WPsigner → Documents**
2. Filter or search by the tag **Imported from ApproveMe**
3. Open a document to review the PDF, signers, and audit trail

---

## Permissions and security

- Admin UI and AJAX actions require a logged-in user with **`manage_options`** or WPsigner signature capability
- The importer **reads** ApproveMe data; it does not modify ApproveMe documents
- PDFs are written through WPsigner **SecureStorage** with integrity hashing
- ApproveMe remains the source of truth until you decommission it after verifying the archive

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Detection error / not installed | ApproveMe tables missing | Install ApproveMe on the same site, or confirm table prefix |
| Start button disabled | Save as PDF unavailable | **E-Signature → Add-ons → Save as PDF** → refresh importer |
| Job very slow | Low traffic / WP-Cron delayed | Leave the importer tab open; ensure a real cron hit if you disabled WP-Cron |
| Some documents failed | PDF render or storage error | Use **Retry failed**; check `wp-content/debug.log` |
| Signer missing | No email on ApproveMe signer | Add email in ApproveMe or accept omission |
| Duplicate worry | Re-run after partial success | Already imported IDs are skipped automatically |

Enable WordPress debug logging if needed:

```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
```

Then review `wp-content/debug.log` for ApproveMe Importer / WPsigner entries.

---

## Next Steps

- [Addons Overview](/addons/overview/) — Install and manage official addons
- [Account Portal](/addons/account-portal/) — Download addon ZIPs
- [Creating Documents](/core-features/creating-documents/) — Work with documents after import
- [Audit Trails](/digital-identity/audit-trails/) — Understand WPsigner audit records
- [Troubleshooting](/support/troubleshooting/) — General WPsigner diagnostics

---

# Document Builder

> Create signing documents from scratch, assign fields in a rich-text editor, generate a secure PDF, and continue directly to review.

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/addons/document-builder/
Markdown: https://docs.wpsigner.com/md/addons/document-builder.md

**WPsigner Document Builder** adds a rich-text editor for creating a document without uploading an existing PDF. Add signers first, write the content, insert assigned signing fields, preview the PDF, and continue directly to WPsigner's Review step.

## Requirements

| Component | Minimum |
|-----------|---------|
| WPsigner | **3.0.2** |
| WordPress | **5.8** |
| PHP | **7.4** |
| Document Builder | This guide covers **1.5.17** |

The addon uses WPsigner's bundled PDF engine and secure storage. It does not require a separate PDF service.

## Install the addon

1. Install and activate WPsigner 3.0.2 or newer.
2. Go to **Plugins → Add New → Upload Plugin**.
3. Upload the official Document Builder ZIP.
4. Activate **WPsigner Document Builder**.
5. Open **WPsigner → Document Builder**, or choose **Document Builder** from **WPsigner → New Document**.

If the addon does not load, confirm the main WPsigner plugin is active and meets the minimum version.

## Build a document

### 1. Add signers

Add at least one signer with a valid email address, then choose a signing workflow:

- **Parallel Signing** — all signers receive the request at once.
- **Sequential Signing** — signers receive it one at a time in the listed order.

Click **Continue to Document**.

### 2. Write and format

Enter a **Document Title**, then create the body with the TipTap editor. Available tools include headings, font size, emphasis, alignment, lists, links, images, tables, page breaks, find/replace, and shared headers and footers.

Headers and footers can use:

| Variable | Output |
|----------|--------|
| `{{page}}` | Current page number |
| `{{pages}}` | Total page count |

> **tip**
Upload large images through the image button instead of pasting data-URI images. This keeps the request below server and PDF-generation limits.

### 3. Insert signing fields

Choose the active signer in **Assign fields to**, then drag or click fields from **Signing fields**. The builder supports Signature, Initials, Text, Number, Date, Name, Email, Phone, Company, VAT, Title, Checkbox, Checkbox Group, Radio, Dropdown, Text Area, and Attachment.

Open **Field settings** to configure:

- **Display label**
- **Mapping name** for Zapier, API, and form feeds
- **Required** or **Optional**
- Choice options and validation
- PDF layout for grouped choices

Signature fields are always required.

Use stable mapping names made from letters, numbers, and underscores. Changing a mapping name can break an existing integration.

### 4. Preview and continue

1. Click **Preview PDF** and review all pages, headers, footers, fields, and page breaks.
2. Click **Continue to review**.
3. WPsigner generates and stores the PDF as a draft.
4. Complete security, expiration, reminders, and delivery settings in WPsigner's Review step.

To revise a Document Builder draft, open it and click **Edit content**. Only drafts originally created by Document Builder can be reopened in the editor.

## Templates

Click **Save as template** in the builder to preserve:

- Body, header, and footer content
- Signers and signing order
- Field assignments and mapping names

Saved items also appear in the WPsigner template catalog. Choose a template to create another document, or delete it from the builder's template panel.

You must save at least one Document Builder template before creating a Document Builder feed for a form integration.

## Form integrations

Document Builder 1.5+ can create a document from:

- Fluent Forms
- WPForms
- Gravity Forms

Open **WPsigner → More → Integrations**, configure the form plugin, then choose **Manage Doc Builder feeds**.

Each feed selects:

1. A form and a Document Builder template.
2. The form fields containing the signer's name and email.
3. Optional form-to-document field mappings.
4. One delivery mode:
   - **Open signing page immediately** — redirect the submitter; no invitation email.
   - **Send signing request by email** — send the link; no browser redirect.

> **caution**
Use only one enabled feed type per form. Enabling both a PDF-template feed and a Document Builder feed creates duplicate documents and can break the post-submit redirect. WPsigner blocks known conflicts when the feed is saved.

Signature and initials fields are never prefilled. Other mapped fields use the stable mapping name configured in the template.

## PDF and storage behavior

Document Builder sanitizes the editor HTML, creates an A4 PDF with WPsigner's TCPDF/FPDI engine, and writes it through WPsigner secure storage.

Current generation limits include:

- 500,000 bytes of document HTML
- 15 embedded data images
- 350,000 characters per embedded image
- Server-level `post_max_size` and upload limits

Preview links are temporary, bound to the current administrator, and expire after approximately 10 minutes.

## Permissions and security

- Creating documents requires the WPsigner create-document capability.
- Editing checks access to the specific draft.
- Builder and feed requests use dedicated WordPress nonces.
- Editor HTML is filtered through an allowlist before PDF generation.
- Generated PDFs are hashed and stored with WPsigner's secure-storage controls.
- Uploaded images use the WordPress Media Library and its upload limits.

See [Team Roles & Permissions](/core-features/team-roles/) and [System Status, Storage & Retention](/getting-started/system-status-and-storage/).

## Troubleshooting

### The editor did not load

Reload with `Ctrl+Shift+R`, disable script optimization for the WPsigner admin, and check the browser console for a blocked builder asset.

### Add some content before continuing

The body is empty. Add document content before creating the PDF.

### Add at least one signer with a valid email

Return to **Signers** and correct missing or invalid addresses.

### The document is too large

Remove or compress pasted images, use Media Library uploads, simplify the header/footer, and check the server's `post_max_size`.

### Preview expired

Click **Preview PDF** again. Preview tokens are intentionally short-lived.

### The form feed reports a conflict

Disable the enabled PDF-template feed or Document Builder feed for that form. Keep only one feed type.

### A draft cannot be re-edited

Only a draft created with Document Builder and still linked to its builder source can open in the editor. Sent or completed documents are immutable through this workflow.

## Related guides

- [Creating Documents](/core-features/creating-documents/)
- [Form Fields](/core-features/form-fields/)
- [Templates API](/api/templates/)
- [Fluent Forms](/integrations/fluent-forms/)
- [WPForms](/integrations/wpforms/)
- [Gravity Forms](/integrations/gravity-forms/)

---

# WPSigner for MainWP

> Manage agency contracts from your MainWP Dashboard — link documents to Clients and Sites, create from templates, send, remind, and track signing without installing WPSigner on child sites.

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/addons/mainwp/
Markdown: https://docs.wpsigner.com/md/addons/mainwp.md

**WPSigner for MainWP** is an official addon that brings WPSigner contract workflows into the [MainWP Dashboard](https://mainwp.com/). Agencies manage e-signature documents on the **same WordPress site** that runs MainWP and WPSigner — associated with MainWP Clients and Sites — without installing WPSigner on child sites.

> **note**
Current addon version documented here: **1.5.8**. Requires **MainWP Dashboard** and **WPSigner** active on the Dashboard site.

---

## What This Addon Does

| Capability | Description |
|------------|-------------|
| **Agency-owned contracts** | Documents live in WPSigner on the Dashboard; child sites are never signing hosts |
| **Client & Site linking** | Each contract can be associated with a MainWP Client, Site, or both |
| **Create from templates** | Multi-signer create with variable prefill from Client/Site data |
| **Send & remind** | Trigger WPSigner emails from MainWP (single or bulk) |
| **Quick create** | One-click create & send from Client/Site cards when a default template is set |
| **Access modal** | View PDF and (when allowed) signing links without leaving MainWP |
| **History** | Audit who created, sent, reminded, or linked from the Dashboard |
| **Alerts & columns** | Pending-signature banners and Manage Sites / Clients columns |

---

## Architecture

```
┌─────────────────────────────────────────────┐
│  WordPress (MainWP Dashboard site)          │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  MainWP  │──│ WPSigner │──│ MainWP    │  │
│  │Dashboard │  │  (core)  │  │ addon     │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│         │              ▲                     │
│         │              │ documents & emails  │
└─────────┼──────────────┼─────────────────────┘
          │              │
          ▼              │ (no WPSigner on children)
   Child Site A    Child Site B
```

**Important:** The addon does **not** push WPSigner to child sites. Contracts, PDFs, signers, OTP/KYC, and email all run on the Dashboard.

Link metadata is stored in `{prefix}wps_mainwp_links`. Dashboard actions are logged in `{prefix}wps_mainwp_activity`.

---

## Documentation Map

| Guide | Contents |
|-------|----------|
| [Installation & Setup](/addons/mainwp-installation/) | Requirements, ZIP install, enable extension, first settings |
| [Settings Reference](/addons/mainwp-settings/) | Default template, agency signer, workflow, OTP/KYC defaults, tagging |
| [Creating Contracts](/addons/mainwp-creating-contracts/) | Multi-signer create, parallel/sequential, OTP/KYC gates, Quick create |
| [Managing Contracts](/addons/mainwp-managing-contracts/) | List, filters, send, remind, unlink, link existing, History, access modal |
| [Clients & Sites](/addons/mainwp-clients-sites/) | Widgets, Site tab, columns, pending alerts |
| [Template Variables](/addons/mainwp-template-variables/) | Prefill keys from Client/Site and the `imwp_template_variables` filter |
| [Security & Permissions](/addons/mainwp-security/) | Caps, signing-link visibility, rate limits (v1.5.8+) |
| [Troubleshooting](/addons/mainwp-troubleshooting/) | Common errors and fixes |

---

## Quick Start (5 Minutes)

1. On your **MainWP Dashboard** site, install and activate **MainWP Dashboard**, **WPSigner**, and **WPSigner for MainWP**.
2. Enable the extension under **MainWP → Extensions**.
3. Open **MainWP → Extensions → WPSigner**.
4. Go to **Settings**: choose a **Default template** and optionally set a **Default agency signer**.
5. Open **Create**, pick a Client/Site, confirm Signer rows, and send.

For OTP or KYC on individual contracts, set WPSigner **Security & Compliance** policies to **Choose per document** first — see [Creating Contracts → Identity checks](/addons/mainwp-creating-contracts/#identity-checks-otp--kyc).

---

## Where to Find It in WordPress

| Surface | Path |
|---------|------|
| Extension home | **MainWP → Extensions → WPSigner** |
| Site contracts | **Sites → [site] → WPSigner** |
| Dashboard widget | MainWP Dashboard → **Contracts** |
| Client card | Client Overview → **Contract** |
| WPSigner Addons card | **WPSigner → Addons** → WPSigner for MainWP |

Direct URL pattern:

```text
admin.php?page=Extensions-Insigner-Mainwp
```

Tabs: `documents` (default), `create`, `link`, `history`, `settings`.

---

## Who Should Use This

- Agencies running **MainWP** that already (or will) host **WPSigner** on the Dashboard
- Teams that sign MSAs, SOWs, NDAs, or maintenance agreements tied to Clients/Sites
- Operators who want create/send/remind without switching to the full WPSigner Documents UI for every action

---

## Related Docs

- [Addons Overview](/addons/overview/) — how official addons are installed
- [Account Portal](/addons/account-portal/) — download ZIPs from `app.wpsigner.com`
- [Creating Documents](/core-features/creating-documents/) — WPSigner core document flow
- [Signer Workflows](/core-features/signer-workflows/) — parallel vs sequential in core
- [Didit.me (KYC)](/integrations/didit/) — identity verification setup
- [Security & Compliance](/support/security/) — reporting security issues

---

# MainWP — Clients & Sites

> Use WPSigner Contract cards, the Site tab, Manage Sites/Clients columns, dashboard widgets, Quick create, and pending-signature alerts inside MainWP.

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/addons/mainwp-clients-sites/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-clients-sites.md

WPSigner for MainWP surfaces contracts wherever agencies already work in MainWP — Dashboard, Clients, and Sites.

---

## Dashboard — Contracts Widget

On the MainWP Dashboard overview, the **Contracts** metabox (`imwp-contracts-widget`) shows:

- Alert when contracts are awaiting signature
- Stats: **Total** / **Awaiting** / **Completed**
- Recent contracts (up to 6)
- Buttons: **New contract**, **View all**

**View all** opens the extension Contracts tab. **New contract** opens Create.

---

## Contract Card (Client & Site)

A compact **Contract** card appears on:

- Client Overview
- Site overview / dashboard contexts (when a site id is present)

### Card contents

| Element | Description |
|---------|-------------|
| Latest contract | Title + status |
| Counts | Total linked · Awaiting signature |
| **New contract** | Opens Create with `client_id` / `site_id` prefilled |
| **Quick create & send** | Uses default template (hidden/disabled messaging if none set) |
| **View all** | Filtered Contracts list for that Client or Site |

### Summary storage

The card syncs a short summary for the site via MainWP website option key `imwp_contract`, plus local mirrors:

- `imwp_client_contract_{client_id}`
- `imwp_site_contract_{site_id}`

These are convenience caches for the UI — source of truth remains `wps_mainwp_links` + WPSigner documents.

---

## Site Tab — WPSigner

Path: **Sites → [site] → WPSigner** (MainWP site subpage slug `WpsignerIndividual` / Manage Sites WPSigner).

### Features

- Site name and URL context
- **Create contract** (prefilled site + linked client when available)
- **Quick create & send** when Settings has a default template
- Compact contracts table for that site (20 rows)

If the site id is missing from the request, the tab shows a site-not-found style message — open the tab from a valid site screen.

---

## Manage Sites Column

On **Sites → Manage Sites**, column **WPSigner** shows:

| Value | Meaning | Typical click-through |
|-------|---------|------------------------|
| **pending** | One or more awaiting signature | Filtered documents (`awaiting`) for that site |
| **OK** | Has linked contracts, none awaiting | Site contracts |
| **None** | No linked contracts | Create with site prefilled |

If WPSigner is not ready, the column may show a dash.

---

## Manage Clients Column

On the MainWP **Clients** table, column **WPSigner** uses the same **pending / OK / None** pattern scoped to `client_id`.

Client widgets can show an onboarding CTA when the client has zero contracts.

---

## Pending Signature Alerts

When at least one linked contract is awaiting signature (`sent` or `viewed`), users may see:

1. A WordPress **admin notice**
2. A MainWP-style **orange banner** on MainWP-related screens

Both point to the Contracts list filtered to awaiting signatures for quick review.

---

## Quick Create From Surfaces

| Surface | Action |
|---------|--------|
| Contract card (Client) | Quick create & send for that client |
| Contract card (Site) | Quick create & send for that site (+ client if linked) |
| Site WPSigner tab | Same |

Requirements and failure modes: [Creating Contracts → Quick create](/addons/mainwp-creating-contracts/#quick-create--send).

---

## Recommended Agency Workflow

1. Connect Sites and Clients in MainWP as usual.
2. Set Default template + agency signer in [Settings](/addons/mainwp-settings/).
3. From a Client or Site card, use **Quick create & send** for standard agreements.
4. Use **Create** for custom titles, extra signers, or one-off OTP/KYC.
5. Watch the Dashboard **Contracts** widget and pending banners for follow-ups.
6. Use **Remind** / bulk remind from the Contracts list.
7. When fully signed, **Open** → Download PDF (completed only).

---

## Related

- [Managing Contracts](/addons/mainwp-managing-contracts/)
- [Creating Contracts](/addons/mainwp-creating-contracts/)
- [WPSigner for MainWP overview](/addons/mainwp/)

---

# MainWP — Creating Contracts

> Create multi-signer WPSigner contracts from MainWP — templates, Signer rows, parallel vs sequential sending, OTP/KYC, Quick create, and variable prefill.

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/addons/mainwp-creating-contracts/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-creating-contracts.md

Create contracts from **MainWP → Extensions → WPSigner → Create** (`tab=create`). You can also deep-link with `client_id` and/or `site_id` query args so Client and Site are preselected (used by widgets and columns).

---

## Before You Create

1. Have an **active WPSigner template** with signature fields mapped to Signer slots.
2. Optionally configure [Settings](/addons/mainwp-settings/) (agency signer, workflow, OTP/KYC defaults).
3. For OTP/KYC toggles on Create, set WPSigner **Security & Compliance** to **Choose per document** (and configure Didit for KYC).

---

## Create Form Fields

| Field | Description |
|-------|-------------|
| **Template** | Active WPSigner templates. The UI shows required signer count when greater than one. |
| **Document title** | Optional. Empty → `{template name} - {Y-m-d H:i}`. |
| **MainWP Client** | Associates the contract; prefills Signer 1 when the client has an email. |
| **MainWP Site** | Associates the contract; selecting a site can auto-select its linked client. |
| **Signer 1…N** | Name + email rows. Count matches template signer slots by default. |
| **Sending order** | Parallel or sequential (shown when more than one signer). |
| **Identity checks** | OTP / KYC when gates allow (see below). |
| **Send immediately** | If checked, emails go out after create (subject to rate limits). |

---

## Multi-Signer Rules

### Template slots

WPSigner templates define **signer orders** on signature fields (Signer 1, Signer 2, …). The Create form builds one row per required order.

| Rule | Detail |
|------|--------|
| Row order | First row = Signer 1, second = Signer 2, and so on |
| Mapping | Signing order and field mapping follow the list order |
| Minimum rows | You cannot remove rows below the template’s required count |
| Extra rows | **Add signer** can add more; a warning explains that the template must have matching slots |

If the submitted signers do not cover every required `signer_order`, create fails with a missing-signers error.

### Prefill behavior

| Signer | Typical source |
|--------|----------------|
| Signer 1 | MainWP Client name/email (AJAX `imwp_client_signer`), or manual entry |
| Signer 2+ | Settings → Default agency signer, else current user |

> **caution**
If you add more signers than the template has slots, signature fields will not exist for the extra people. Update the template in WPSigner first.

---

## Sending Order (Parallel vs Sequential)

Available when signer count > 1. Default comes from Settings.

| Mode | What happens on Send |
|------|----------------------|
| **Parallel** | All signer-role recipients receive the signing request email. |
| **Sequential** | Only the next signer in order is emailed; subsequent signers are notified after earlier ones complete. |

Stored on the document as `signing_workflow`. See also [Signer Workflows](/core-features/signer-workflows/) in core docs.

---

## Identity Checks (OTP / KYC)

MainWP reads WPSigner `SigningGates` and renders the Create UI accordingly.

### OTP

| Gate mode | Create UI |
|-----------|-----------|
| Always | Info message — OTP required for all documents |
| Choose per document | Checkbox (prefills from Settings `default_require_otp`) |
| Off | Message — set WPSigner Security → OTP to **Choose per document** |

### KYC (Didit)

| Condition | Create UI |
|-----------|-----------|
| Always + Didit ready | Info — KYC required globally |
| Choose per document + Didit ready | Checkbox (prefills from Settings) |
| Didit not configured | Warning — configure Didit in WPSigner first |
| Off | Message — set Security → KYC to **Choose per document** |

### What gets saved on the document

When a gate is **configurable** and the checkbox (or Quick create default) is on, the addon writes per-document `security_settings` via WPSigner’s sanitizer.

> **v1.5.8 behavior**
MainWP **never changes** global WPSigner options (`otp_mode` / `kyc_mode`). Enabling OTP/KYC from Create does **not** promote Off → per-document. Configure the policy in WPSigner first.

Related: [Didit.me integration](/integrations/didit/), [Security & Permissions](/addons/mainwp-security/).

---

## Create Pipeline (What Happens Server-Side)

1. Verify WPSigner ready + user can manage.
2. Load template; non-admins may only use their own templates (admins can use any).
3. Sanitize signers; assert all required signer orders are covered.
4. If sending: soft **rate-limit** (`create_send`, ~30 seconds).
5. Create document from template in WPSigner.
6. Prefill template variables from Client/Site ([Template Variables](/addons/mainwp-template-variables/)).
7. Save `signing_workflow` and optional `security_settings`.
8. Upsert MainWP link — **if link fails, the draft document is deleted** (no orphan).
9. Apply tags (`MainWP` + optional Client/Site labels).
10. Log activity `created`.
11. Optionally `send_document` (separate send rate-limit also applies).

If send fails after a successful create+link, the API returns the document ID with `sent: false` and a `send_error` message so you can retry Send from the list.

---

## Quick Create & Send

Available from Client/Site **Contract** cards and the Site **WPSigner** tab when a **Default template** is set.

### What it does

1. Uses Settings → Default template.
2. Builds title: `Contract — {site or client name} — {Y-m-d}`.
3. Signer 1 from client email (fails if client has no email).
4. Signers 2…N from Default agency signer / current user.
5. Applies default OTP/KYC settings when gates allow.
6. Sends according to Settings `auto_send` (or explicit POST `send`).

### When to use Create instead

- Need a different template
- Need to edit signer names/emails carefully
- Need a custom title or different OTP/KYC choice than defaults
- Client has no email contact (enter Signer 1 manually on Create)

---

## Variable Prefill

On create, Client/Site fields map into template variables (for example `client_name`, `site_url`, `date`). History records whether variables were prefilled.

Full key list and developer filter: [Template Variables](/addons/mainwp-template-variables/).

---

## Next Steps

- [Managing Contracts](/addons/mainwp-managing-contracts/) — send, remind, Open modal
- [Clients & Sites](/addons/mainwp-clients-sites/)
- [Troubleshooting](/addons/mainwp-troubleshooting/)

---

# MainWP — Installation & Setup

> Install WPSigner for MainWP on your Dashboard site, enable the MainWP extension, and complete first-time configuration.

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/addons/mainwp-installation/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-installation.md

This guide covers installing **WPSigner for MainWP** (plugin slug `insigner-mainwp`) on the WordPress site that runs your MainWP Dashboard.

> **important**
Install this addon **only on the MainWP Dashboard**. Do not install WPSigner or this addon on child sites for this workflow. Contracts stay on the agency Dashboard.

---

## Requirements

| Component | Minimum | Notes |
|-----------|---------|-------|
| WordPress | 5.8+ | Tested up to 7.1 |
| PHP | 7.4+ | Same as WPSigner |
| [MainWP Dashboard](https://mainwp.com/) | Active | Detected via MainWP activation checks |
| [WPSigner](/getting-started/installation/) | Active | Needs Document & Template models (`WPS_VERSION`) |
| Capability | See below | Team users need MainWP extension access **and** WPSigner signature rights |

### Capability checklist (v1.5.8+)

To use the extension UI and AJAX actions, the logged-in user must:

1. Pass MainWP extension ACL for `insigner-mainwp`, **or** have `manage_options`
2. **And**, when WPSigner RBAC is present, pass `\InSigner\Security\Permissions::can_use_signatures()`

WordPress Administrators with full WPSigner access normally satisfy both. Team members who only have MainWP extension access but **no** WPSigner signing role will be denied — by design. See [Security & Permissions](/addons/mainwp-security/).

---

## Step 1 — Install Dependencies

On the Dashboard WordPress site:

1. Install and activate **MainWP Dashboard**.
2. Install and activate **WPSigner** (licensed). Complete the WPSigner setup wizard if needed.
3. Create at least one **active template** in WPSigner (recommended before Quick create).

---

## Step 2 — Download the Addon

1. Log in to the [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons).
2. Download **WPSigner for MainWP** (`wpsigner-mainwp-X.Y.Z.zip` or portal name `WPsigner-MainWP.zip`).
3. Keep the ZIP handy — portal download links expire after about one hour.

See [Account Portal](/addons/account-portal/) and [Addons Overview](/addons/overview/) for the general download flow.

---

## Step 3 — Upload and Activate

1. In WordPress: **Plugins → Add New → Upload Plugin**.
2. Select the ZIP → **Install Now** → **Activate**.
3. On activation the addon:
   - Creates tables `{prefix}wps_mainwp_links` and `{prefix}wps_mainwp_activity`
   - Seeds default option `imwp_settings`
   - Registers with MainWP (`mainwp_activate_extention`)

If MainWP or WPSigner is missing, users with `manage_options` see an **admin error notice**. Fix dependencies before using the extension.

---

## Step 4 — Enable in MainWP

1. Go to **MainWP → Extensions**.
2. Find **WPSigner** and enable it (MainWP Team Control / extension ACL as needed).
3. Open **MainWP → Extensions → WPSigner**.

You should land on the **Contracts** tab (`admin.php?page=Extensions-Insigner-Mainwp`).

---

## Step 5 — First Settings

Open the **Settings** tab and configure at least:

| Setting | Recommendation |
|---------|----------------|
| **Default template** | Required for **Quick create & send** |
| **Default agency signer** | Name + email for Signer 2+ on multi-signer templates |
| **Default sending order** | Parallel (all at once) or Sequential |
| **Auto-send checkbox default** | On if you usually send immediately from Create |

Full option list: [Settings Reference](/addons/mainwp-settings/).

---

## Step 6 — Confirm Surfaces

After enabling, you should also see:

| Surface | Where |
|---------|-------|
| **Contracts** widget | MainWP Dashboard overview |
| **Contract** card | Client Overview / Site overview contexts |
| **WPSigner** site tab | **Sites → [site] → WPSigner** |
| **WPSigner** column | Manage Sites / Manage Clients |
| Addon card | **WPSigner → Addons** (deep-link to the extension) |

If widgets are missing, confirm the extension is enabled and that MainWP metaboxes are not hidden for your user.

---

## WPSigner → Addons Card

The addon registers on **WPSigner → Addons**. From there you can open the MainWP extension page directly. Activation of the PHP plugin is still done under **Plugins** (or the Addons Activate control when applicable).

---

## Updating

1. Download the new ZIP from the Account Portal (or your release channel).
2. Replace the plugin via upload or your usual update process.
3. Reload **MainWP → Extensions → WPSigner** and check **Settings** dependency indicators.

Database version is tracked as `imwp_db_version` (currently `1.1.0`). Activation upgrades schema when needed.

---

## Uninstall

Deleting the plugin via WordPress runs `uninstall.php`, which:

- Drops `wps_mainwp_links` and `wps_mainwp_activity`
- Deletes `imwp_settings` and `imwp_db_version`

**WPSigner documents are not deleted.** Only MainWP link/activity metadata is removed. Local mirror options such as `imwp_client_contract_{id}` may remain; remove manually if desired.

---

## Next Steps

- [Settings Reference](/addons/mainwp-settings/)
- [Creating Contracts](/addons/mainwp-creating-contracts/)
- [Clients & Sites](/addons/mainwp-clients-sites/)
- [Security & Permissions](/addons/mainwp-security/)

---

# MainWP — Managing Contracts

> List, filter, send, remind, unlink, link existing documents, view History, and open the Contract access modal from MainWP.

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/addons/mainwp-managing-contracts/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-managing-contracts.md

Day-to-day contract operations live under **MainWP → Extensions → WPSigner**.

---

## Contracts Tab

Path: **Contracts** (`tab=documents`). Optional status shortcut: `&status=awaiting`.

### Filters

| Filter | Behavior |
|--------|----------|
| Search | Matches document title |
| Client | MainWP client |
| Site | MainWP site |
| Status | `awaiting` = `sent` + `viewed`; also draft, sent, viewed, completed, declined, expired |

Pagination: **20** contracts per page.

### Table columns

Checkbox · Title · Status · Client · Site · Updated · Actions

### Row actions

| Action | When it appears | Effect |
|--------|-----------------|--------|
| **Open** | Always (linked docs) | Opens Contract access modal |
| **Send** | Draft | Sends signing emails (rate-limited) |
| **Remind** | Sent / viewed | Reminds pending / viewed signers |
| **Unlink** | Always | Removes MainWP link only — **does not delete** the WPSigner document |

### Bulk remind

1. Select one or more contracts (max **50** per request).
2. Click **Remind selected**.
3. Confirm in the styled dialog.

Each document still goes through the normal remind gate (must be linked, allowed, correct status, rate-limit).

---

## Send

Sending from MainWP calls WPSigner’s send path for the linked document.

### Requirements

- Document is linked in MainWP
- User can manage the extension **and** modify the document in WPSigner
- Soft rate-limit (~30s) per user/document for `send`

### Parallel vs sequential

Respects the document’s `signing_workflow` set at create time. See [Creating Contracts](/addons/mainwp-creating-contracts/#sending-order-parallel-vs-sequential).

Activity log entry: `sent`.

---

## Remind

### Requirements

- Status typically **sent** or **viewed**
- There are signers who still need a reminder (pending / viewed)
- Soft rate-limit for `remind`

Activity log entry: `reminded` (meta may include counts).

---

## Unlink

**Unlink** deletes the row in `wps_mainwp_links` and logs `unlinked`. The WPSigner document, PDF, and signers remain intact. You can [link again](#link-existing) later.

---

## Link Existing

Tab: **Link** (`tab=link`).

Use this when a document already exists in WPSigner and you want to associate it with a Client and/or Site.

| Field | Description |
|-------|-------------|
| Document ID | WPSigner document ID |
| Client | Optional MainWP client |
| Site | Optional MainWP site |

On success:

- Link upserted
- Tags applied (`MainWP` + optional Client/Site labels)
- Activity `linked`

This does **not** recreate the document or re-send emails.

---

## History

Tab: **History** (`tab=history`).

Dashboard-originated actions are stored in `{prefix}wps_mainwp_activity`.

### Filter by action

Created · Sent · Reminded · Linked · Unlinked · Quick create

### Columns

| Column | Content |
|--------|---------|
| When | Timestamp |
| User | Who performed the action |
| Action | Action type |
| Document | Document ID / title context |
| Details | Meta: client/site IDs, source (`create` / `quick_create`), prefill result, reminder counts |

Pagination: **25** per page.

> **note**
History is an **addon activity log**, not a replacement for WPSigner’s full audit trail / Certificate of Completion. Use WPSigner audit features for legal evidence packages.

---

## Contract Access Modal (Open)

Click **Open** on a contract to load access data via `imwp_document_access` (POST + nonce).

### Document section

| Control | Behavior |
|---------|----------|
| **Download PDF** | Shown only when status is **completed** |

In-progress contracts (draft / sent / viewed) do not show a PDF button — use signing links instead.

### Signing links section

| Viewer role | What they see |
|-------------|----------------|
| WordPress admin (`manage_options`) or WPSigner `can_manage_all()` | Per-signer name, email, status, **Copy link** / **Open** |
| Other users who can manage the extension | Signer list metadata may be limited; signing URLs are **hidden** with a clear message (v1.5.8+) |

> **caution**
Signing URLs contain bearer-style access tokens. Treat them like passwords. Only share with the intended signer.

Details: [Security & Permissions](/addons/mainwp-security/).

---

## Opening in WPSigner

For full editor / audit tools, open the document in core WPSigner:

```text
admin.php?page=insigner&document={id}
```

Use MainWP for agency association and fast send/remind; use WPSigner when you need field editing, certificate review, or advanced security settings.

---

## Related

- [Creating Contracts](/addons/mainwp-creating-contracts/)
- [Clients & Sites](/addons/mainwp-clients-sites/)
- [Troubleshooting](/addons/mainwp-troubleshooting/)

---

# MainWP — Security & Permissions

> Capability model, OTP/KYC boundaries, signing-link visibility, rate limits, and hardening notes for WPSigner for MainWP 1.5.8+.

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/addons/mainwp-security/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-security.md

WPSigner for MainWP is a **Dashboard admin extension**. It has no public/`nopriv` AJAX endpoints. All actions require a logged-in user, a valid nonce (`imwp_admin`), and capability checks.

Documented behavior reflects **addon v1.5.8** security hardening.

---

## Capability Model

### `can_manage()` — use the extension

The user must:

1. Be logged in
2. Pass **MainWP** extension access for slug `insigner-mainwp`, **or** have `manage_options`
3. **And** (when WPSigner RBAC exists) pass `Permissions::can_use_signatures()`

If WPSigner Permissions is unavailable, fallback is `manage_options` only after MainWP/admin gate.

### Document mutations

Send, remind, unlink, and access also require the document to be **linked** in MainWP and typically `Permissions::can_modify_document` (via bridge guards).

### Templates

Users without `manage_options` may only create from templates they own (`template->user_id`).

---

## Signing Link Visibility

Contract access (`get_document_access`) returns signing URLs only when `can_view_signing_links()` is true:

| Allowed | Condition |
|---------|-----------|
| Yes | `manage_options`, **or** WPSigner `Permissions::can_manage_all()` |
| No | Other users who can still manage the extension — they see PDF actions when available, but **signing links are hidden** |

UI flag: `signing_links_hidden`. The modal shows a restricted message instead of Copy/Open.

> **caution**
Signing links are bearer tokens. Restrict who can view them. Prefer email delivery from WPSigner over copying links in shared admin sessions.

---

## OTP / KYC Trust Boundary

| Rule | Detail |
|------|--------|
| Global policy lives in WPSigner | Security & Compliance (`otp_mode` / `kyc_mode`) |
| MainWP does not mutate `wps_options` | v1.5.8 removed Off → per-document promotion |
| Per-document flags | Written only when gate mode is **Choose per document** and the Create/Quick create flag is on |
| KYC | Requires Didit ready in WPSigner |

Operators who need per-contract OTP/KYC from MainWP must set WPSigner policies to **Choose per document** first.

---

## Rate Limits

Soft limits use per-user transients (~**30 seconds**):

| Action key | Scope |
|------------|--------|
| `create_send` | Create-and-send / Quick create with send |
| `send` | Send on an existing document |
| `remind` | Remind (per document) |

Exceeded limit returns a friendly “wait a few seconds” error — not a hard lockout.

---

## Orphan Protection

If document create succeeds but MainWP **link upsert fails**, the addon **deletes the draft document** and returns an error. This prevents unlinked drafts accumulating in WPSigner.

---

## AJAX Surface

All handlers: `wp_ajax_imwp_*` (authenticated only).

| Action | Purpose |
|--------|---------|
| `imwp_create_document` | Create from template |
| `imwp_quick_create` | Quick create & send |
| `imwp_send_document` | Send |
| `imwp_remind_document` | Remind |
| `imwp_bulk_remind` | Bulk remind (≤50) |
| `imwp_unlink_document` | Unlink |
| `imwp_link_document` | Link existing |
| `imwp_save_settings` | Settings |
| `imwp_client_signer` | Resolve client → signer (POST) |
| `imwp_document_access` | Access modal payload (POST) |

Sensitive handlers read parameters from **`$_POST`** (not GET). Shared nonce action: `imwp_admin`.

---

## SQL & XSS Posture

- Link/list queries use `$wpdb->prepare` with whitelisted status/column fragments
- Admin partials use `esc_html` / `esc_attr` / `esc_url`
- `admin.js` uses `escapeHtml` / jQuery `.text()` for dynamic strings

---

## What MainWP Does Not Do

- No signing UI on child sites
- No anonymous signing endpoints
- No change to WPSigner global security options
- No deletion of WPSigner documents on Unlink or uninstall (uninstall drops link/activity tables only)

---

## Reporting Issues

If you discover a vulnerability in the addon or core, follow [Report a Security Issue](/support/security/).

---

## Related

- [Installation & Setup](/addons/mainwp-installation/)
- [Creating Contracts — Identity checks](/addons/mainwp-creating-contracts/#identity-checks-otp--kyc)
- [Managing Contracts — Access modal](/addons/mainwp-managing-contracts/#contract-access-modal-open)
- [Didit.me](/integrations/didit/)

---

# MainWP — Settings Reference

> Complete reference for WPSigner for MainWP settings — default template, agency signer, workflow, OTP/KYC defaults, and document tagging.

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/addons/mainwp-settings/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-settings.md

Configure the addon under **MainWP → Extensions → WPSigner → Settings** (`tab=settings`). Settings are stored in the WordPress option `imwp_settings` and saved via authenticated AJAX (`imwp_save_settings`).

The Settings screen also shows a **dependency checklist**: MainWP Dashboard and WPSigner (ready / missing).

---

## Settings Table

| Option key | UI label | Default | Purpose |
|------------|----------|---------|---------|
| `default_template_id` | Default template | `0` (None) | Template used by **Quick create & send**. Create still lets you pick any allowed template. |
| `auto_send` | Default “send immediately” | Off (`0`) | Prefills the Create form checkbox. Quick create uses this unless the request overrides `send`. |
| `tag_client_site` | Also tag with Client / Site labels | On (`1`) | Adds Client/Site name tags in addition to the always-applied `MainWP` tag. |
| `default_agency_name` | Default agency signer — Name | empty | Used for Signer **2+** on Create and Quick create when the template has multiple slots. |
| `default_agency_email` | Default agency signer — Email | empty | Must be a valid email with the name; otherwise the logged-in user is used as fallback. |
| `default_signing_workflow` | Default sending order | `parallel` | `parallel` (email all) or `sequential` (one by one). Prefills Create when multiple signers. |
| `default_require_otp` | Require OTP by default | Off | Prefills Create / Quick create **only when** WPSigner OTP policy is **Choose per document**. |
| `default_require_kyc` | Require KYC (Didit) by default | Off | Same rule for KYC — and Didit must be configured in WPSigner. |

---

## Default Template

1. Create and publish an active template in **WPSigner → Templates**.
2. Ensure signature fields are assigned to the correct **Signer 1, Signer 2, …** slots.
3. Select that template under **Default template** in Settings.
4. Save.

Without a default template:

- **Quick create & send** is blocked with a clear message.
- Manual **Create** still works if you choose a template each time.

> **tip**
For multi-signer agency workflows, design the template with the same number of signer slots you expect in MainWP (for example Client = Signer 1, Agency = Signer 2).

---

## Default Agency Signer

When a template requires two or more signers:

- **Signer 1** is typically filled from the MainWP Client (name/email).
- **Signer 2+** use **Default agency signer** name and email from Settings.
- If agency defaults are empty or invalid, the addon falls back to the **current logged-in user**.

Quick create builds the full signer list automatically using this rule.

---

## Default Sending Order

Shown on Create when there is more than one signer:

| Value | Behavior |
|-------|----------|
| **Parallel** | All signer-role recipients receive the signing email when the document is sent. |
| **Sequential** | Only the next pending signer is emailed (Signer 1 first, then the next after they finish). |

Stored on the document as `signing_workflow`. Aligns with WPSigner core [signer workflows](/core-features/signer-workflows/).

---

## OTP / KYC Defaults

These checkboxes on Settings only **prefill** Create / Quick create. They do **not**:

- Change global WPSigner security policy
- Force OTP/KYC when WPSigner is set to **Off** or **Always**

| WPSigner Security policy | Effect in MainWP |
|--------------------------|------------------|
| **Always** | OTP/KYC required globally; MainWP shows an info message (no per-doc toggle). |
| **Choose per document** | MainWP shows checkboxes; Settings defaults apply. |
| **Off** | MainWP shows how to enable per-document in WPSigner — no silent policy change (v1.5.8+). |

KYC also requires [Didit.me](/integrations/didit/) credentials in **WPSigner → Integrations**.

Deep dive: [Creating Contracts → Identity checks](/addons/mainwp-creating-contracts/#identity-checks-otp--kyc) and [Security & Permissions](/addons/mainwp-security/).

---

## Tagging

Every document created or linked through MainWP receives the tag **`MainWP`**.

When **Also tag with Client / Site labels** is enabled, the addon also tags with Client and/or Site display names when available. This makes documents easy to filter inside WPSigner Documents.

---

## Saving

Click **Save settings** on the Settings tab. Success/error feedback uses the extension’s styled dialogs (not browser alerts).

---

## Related

- [Installation & Setup](/addons/mainwp-installation/)
- [Creating Contracts](/addons/mainwp-creating-contracts/)
- [Template Variables](/addons/mainwp-template-variables/)

---

# MainWP — Template Variables

> Prefill WPSigner template fields from MainWP Client and Site data when creating contracts from the Dashboard.

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/addons/mainwp-template-variables/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-template-variables.md

When you create a contract from MainWP, the addon builds a variable map from the selected **Client** and **Site**, then applies it through WPSigner’s form/template prefill helper (`FormFeedFieldPrefill::apply_variables`).

Empty values are stripped before apply. History meta records whether prefill matched (`variables prefilled` / `no prefill match`).

---

## How Matching Works

1. Name template fields (or mapping names) using the keys below — same idea as form feeds / Zapier mapping in WPSigner.
2. Create from MainWP with a Client and/or Site selected.
3. Matching keys receive values automatically on the new document.

If only a Site is selected and that Site has a linked MainWP `client_id`, the addon **infers** the Client for variable building.

---

## Built-in Keys

| Key | Source |
|-----|--------|
| `client_name` | MainWP client name |
| `client_email` | MainWP client email |
| `site_name` | Site name |
| `website_name` | Alias of `site_name` |
| `site_url` | Site URL |
| `website_url` | Alias of `site_url` |
| `property_address` | Currently filled with the site URL (convenient alias for address-style fields) |
| `date` | Today as `Y-m-d` (site timezone via `wp_date`) |
| `today` | Same as `date` |
| `appointment_date` | Same as `date` |
| `current_date` | Human-readable date using WordPress `date_format` |
| `mainwp_client_id` | Client ID as string (empty if none) |
| `mainwp_site_id` | Site ID as string (empty if none) |

> **tip**
Use consistent mapping names on templates you plan to drive from MainWP (for example always `client_name` / `site_url`) so Quick create and Create prefill reliably.

---

## Developer Filter

Extend or override the map:

```php
/**
 * @param array<string,string> $vars
 * @param int                  $client_id
 * @param int                  $site_id
 */
add_filter('imwp_template_variables', function ($vars, $client_id, $site_id) {
    // Example: add a custom CRM ID stored on the client.
    if ($client_id) {
        $vars['crm_id'] = (string) get_option('my_crm_id_' . $client_id, '');
    }
    return $vars;
}, 10, 3);
```

Return only string values. Empty strings are removed before apply.

---

## Troubleshooting Prefill

| Symptom | Fix |
|---------|-----|
| History says no prefill match | Field mapping names do not match keys; or Client/Site had no usable values |
| Client fields empty | Select a Client, or ensure the Site has a linked client |
| Site URL missing | Select a Site with a valid URL in MainWP |
| Custom key ignored | Add it via `imwp_template_variables` **and** map the template field to that name |

More help: [Troubleshooting](/addons/mainwp-troubleshooting/).

---

## Related

- [Creating Contracts](/addons/mainwp-creating-contracts/)
- [Form Fields](/core-features/form-fields/) — field name / mapping name in the PDF editor
- [WPSigner for MainWP overview](/addons/mainwp/)

---

# MainWP — Troubleshooting

> Fix common WPSigner for MainWP issues — permissions, templates, Quick create, OTP/KYC, signing links, rate limits, and prefill.

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/addons/mainwp-troubleshooting/
Markdown: https://docs.wpsigner.com/md/addons/mainwp-troubleshooting.md

Use this page when something fails in **MainWP → Extensions → WPSigner**. For core WPSigner problems (email delivery, PDF generation), see [Support → Troubleshooting](/support/troubleshooting/).

---

## Dependencies & Access

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Admin notice that MainWP or WPSigner is missing | Dependency inactive | Activate both on the **Dashboard** site |
| Extension page empty / Permission denied | Failed `can_manage()` | Grant MainWP extension access **and** WPSigner signature capability (v1.5.8+) |
| Extension not listed | Not enabled | **MainWP → Extensions** → enable WPSigner |
| Columns show “—” | WPSigner not ready | Activate/license WPSigner |

---

## Templates & Create

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No templates in Create | None active / wrong owner | Create active templates; non-admins only see their own |
| Missing signers error | Rows don’t cover template `signer_order`s | Match Signer 1…N to template slots |
| Warning when adding a signer | Extra row beyond template slots | Add signature fields for that signer in WPSigner |
| Create fails after send rate limit | Soft limit ~30s | Wait and retry |

---

## Quick Create

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| “Set a default template…” | `default_template_id` = 0 | [Settings](/addons/mainwp-settings/) → Default template |
| Client has no email contact | Client missing email | Add email in MainWP or use Create manually |
| Multi-signer Quick create odd agency signer | Empty agency defaults | Set Default agency signer name + email |
| Sent false + send_error | Email/send path failed after create | Fix mail config; use **Send** on the Contracts row |

---

## OTP / KYC

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No OTP checkbox | Policy Off or Always | Set WPSigner Security → OTP to **Choose per document** for per-contract control |
| No KYC checkbox | Off/Always, or Didit missing | Configure [Didit](/integrations/didit/); set KYC to **Choose per document** |
| Checkbox ignored / nothing stored | Gate not configurable | v1.5.8 only writes per-doc settings when mode is per-document |
| Expected auto-enable from Off (old 1.5.7) | Behavior removed | Set policy manually in WPSigner |

---

## Send, Remind, Links

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| “Please wait a few seconds…” | Rate limit | Wait ~30 seconds |
| Remind does nothing useful | Wrong status / no pending signers | Status should be sent/viewed with pending signers |
| “Document created but MainWP link failed…” | Link upsert failed | Draft was removed; retry create; check DB permissions |
| Unlink removed association only | Expected | Document still in WPSigner |

---

## Access Modal

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Signing links hidden | User lacks `manage_options` / `can_manage_all` | Use an admin account, or send via email instead of copying links |
| Download PDF missing | Not completed | Wait until all required signers finish |
| View PDF only | Expected for drafts/in-progress | Download reserved for completed |

---

## Prefill

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Fields blank after create | Mapping names ≠ keys | Align with [Template Variables](/addons/mainwp-template-variables/) |
| Client vars empty with only Site | Site has no linked client | Select Client or link client on the Site in MainWP |

---

## Site Tab / Widgets

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Site not found on tab | Missing site id in URL | Open from Sites → site → WPSigner |
| Widget missing | Extension disabled / metabox hidden | Enable extension; reset MainWP metabox layout |
| Pending banner always on | Awaiting contracts exist | Remind or complete; filter Contracts → awaiting |

---

## Changelog Pointers (Behavior Changes)

| Version | Change that affects support tickets |
|---------|-------------------------------------|
| **1.5.8** | No global security mutation; stricter caps; hidden signing URLs; create-send rate limit; orphan cleanup |
| **1.5.7** | (Superseded) Could promote Off → per-document when enabling OTP/KYC from MainWP |
| **1.5.5** | Parallel vs sequential workflow on Create |
| **1.5.0** | Multi-signer rows + agency signer defaults |
| **1.4.0** | Variable prefill, History, access modal |

Full product changelog: [Changelog](/changelog/). Addon release notes also ship in the plugin `readme.txt`.

---

## Still Stuck?

1. Confirm versions: MainWP, WPSigner, WPSigner for MainWP (**1.5.8+** recommended).
2. Reproduce with a WordPress Administrator who has full WPSigner access.
3. Check WPSigner System Status / email logs for send failures.
4. Contact support via [wpsigner.com/contact](https://wpsigner.com/contact/) with steps, versions, and whether Create vs Quick create fails.

---

## Related

- [Security & Permissions](/addons/mainwp-security/)
- [Installation & Setup](/addons/mainwp-installation/)
- [Support FAQ](/support/faq/)

---

# Addons Overview

> Install and manage official WPsigner addons such as Smart Signing Forms from your account portal and WordPress admin.

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/addons/overview/
Markdown: https://docs.wpsigner.com/md/addons/overview.md

**Addons** extend WPsigner with official features built by the WPsigner team. Install them on your WordPress site like any other plugin, then manage them from **WPsigner → Addons**.

> **Requires WPsigner Pro**
Addons are not available in **Lite**. [Upgrade to Pro](https://wpsigner.com/pricing/?utm_source=docs&utm_medium=upgrade&utm_campaign=addons) · [Lite vs Pro](/getting-started/lite-vs-pro/)

> **note**
Addons are separate ZIP files from the main WPsigner plugin. You need an active license to download most addons from the Account Portal.

---

## Available Addons

| Addon | Status | Description |
|-------|--------|-------------|
| [Smart Signing Forms](/addons/smart-signing-forms/) | Available | Drag-and-drop signing forms with inline signature, OTP, payments, and signed PDF output |
| [Document Builder](/addons/document-builder/) | Available | Write documents from scratch, insert assigned signing fields, generate a secure PDF, and continue to Review |
| [ApproveMe Importer](/addons/approveme-importer/) | Available | Import signed WP E-Signature / ApproveMe documents into WPsigner as completed PDFs |
| [WPSigner for MainWP](/addons/mainwp/) | Available | Manage agency contracts from the MainWP Dashboard (Clients & Sites) |
| [WPsigner for Uncanny Automator](/addons/uncanny-automator/) | Available | Triggers, actions, field tokens, signer loops, and messaging for Uncanny Automator recipes |
| Flow Builder | Coming soon | Visual automation canvas for signing workflows |

---

## Two Places to Manage Addons

| Location | Who uses it | Purpose |
|----------|-------------|---------|
| **[Account Portal](/addons/account-portal/)** (`app.wpsigner.com`) | License holders | Download official ZIP files (plugin + addons) |
| **WPsigner → Addons** (WordPress admin) | Site administrators | Install, activate, and open installed addons |

These work together: download from the portal, upload to WordPress, activate in WPsigner.

---

## Installation Flow

Follow this end-to-end process for an official addon:

| Step | Where | Action |
|------|-------|--------|
| 1 | [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons) | Log in → open **Addons** tab → click **Download** on the addon card |
| 2 | WordPress admin | **Plugins → Add New → Upload Plugin** → select the ZIP → **Install Now** |
| 3 | WPsigner | **WPsigner → Addons** → click **Activate** on the addon card |
| 4 | WPsigner | Click the addon's **Open** or **Configure** action |

> **important**
Download links from the Account Portal are **time-limited** (about one hour). If a link expires, return to the Addons tab and download again.

---

## Requirements

- A compatible, licensed **WPsigner** installation (check each addon guide; Document Builder requires 3.0.2+)
- WordPress user with **`activate_plugins`** capability (to activate addons)
- Active license on your account (when the addon requires it — default for official addons)

---

## Addon Card States

On **WPsigner → Addons**, each card shows one of these states:

| State | Meaning |
|-------|---------|
| **Coming Soon** | Not released yet (for example Flow Builder) |
| **Not installed** | Download from Account Portal, then upload the ZIP |
| **Installed** | ZIP uploaded but not active — click **Activate** |
| **Active** | Addon running — use **Open Smart Signing Forms** (or equivalent) |

The **Download addon** button opens the Account Portal Addons tab in a new tab.

---

## After Installation

### Smart Signing Forms

Once Smart Signing Forms is active:

1. Go to **WPsigner → Smart Signing Forms → Add New Form**
2. Complete the 4-step wizard (configuration, fields, design, compliance)
3. Copy the shortcode: `[insigner_smart_form id="123"]`
4. Paste it into any page or post

Full guide: [Smart Signing Forms](/addons/smart-signing-forms/)

### Document Builder

Once Document Builder is active:

1. Go to **WPsigner → Document Builder**
2. Add signers and choose parallel or sequential signing
3. Write the document and insert assigned signing fields
4. Preview the PDF and continue to WPsigner's Review step

Full guide: [Document Builder](/addons/document-builder/)

### WPsigner for Uncanny Automator

Once the addon is active:

1. Confirm **Uncanny Automator** is also active
2. Open **Automator → Recipes → Add Recipe**
3. Add a **WPsigner** trigger (for example *A document is completed*) or action (*Create a document from a template*)

Full guide: [WPsigner for Uncanny Automator](/addons/uncanny-automator/) · [Installation](/addons/uncanny-automator-installation/) · [Recipe examples](/addons/uncanny-automator-recipes/)

### ApproveMe Importer

Once ApproveMe Importer is active:

1. Keep ApproveMe + **Save as PDF** enabled on the same site
2. Open **WPsigner → ApproveMe Import**
3. Review detection counts, then start the background import

Full guide: [ApproveMe Importer](/addons/approveme-importer/)

---

## Next Steps

- [Smart Signing Forms](/addons/smart-signing-forms/) — Complete addon documentation
- [Document Builder](/addons/document-builder/) — Create signing-ready PDFs from a rich-text editor
- [ApproveMe Importer](/addons/approveme-importer/) — Migrate signed ApproveMe documents
- [WPSigner for MainWP](/addons/mainwp/) — Contracts from the MainWP Dashboard
- [WPsigner for Uncanny Automator](/addons/uncanny-automator/) — Recipes for signing events and document actions
- [Account Portal](/addons/account-portal/) — Licenses, downloads, billing, and support
- [Installation](/getting-started/installation/) — Install the main WPsigner plugin
- [Stripe Payments](/integrations/stripe/) — Required for Smart Forms payment fields

---

# Smart Signing Forms

> Build drag-and-drop signing forms with inline signature, OTP, Stripe payments, and automatic signed PDF generation.

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/addons/smart-signing-forms/
Markdown: https://docs.wpsigner.com/md/addons/smart-signing-forms.md

**Smart Signing Forms** is an official WPsigner addon that lets you build signing forms without the document wizard. Each submission creates a signed PDF with audit trail and Certificate of Completion.

> **note**
Requires **WPsigner v3.0.0+** and the [Smart Signing Forms addon](/addons/overview/) installed and activated.

---

## Installation

1. Download the addon from the [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons) tab
2. **Plugins → Add New → Upload Plugin** → install the ZIP
3. **WPsigner → Addons → Activate**
4. Open **WPsigner → Smart Signing Forms**

See [Addons Overview](/addons/overview/) for the full flow.

### Requirements

| Component | Minimum |
|-----------|---------|
| WPsigner | 3.0.0 |
| WordPress | 5.8 |
| PHP | 7.4 |
| OpenSSL | Recommended |

---

## Create a Form

1. Go to **WPsigner → Smart Signing Forms → Add New Form**
2. Complete the **4-step wizard**
3. Click **Publish** (or **Update** for existing forms)
4. Copy the shortcode from the form list or editor

### Shortcode

```text
[insigner_smart_form id="123"]
```

Replace `123` with your form ID. Paste the shortcode into any page, post, or block that supports shortcodes.

---

## Wizard Step 1 — Configuration

| Setting | Description |
|---------|-------------|
| **Form title** | Internal name shown in the admin list |
| **PDF title** | Title on the generated signed PDF |
| **Success message** | Shown after successful submission |
| **Submit button label** | Default: "Submit & Sign" |
| **reCAPTCHA v2** | Optional bot protection (site key + secret) |

### After Signing Options

| Option | Description |
|--------|-------------|
| **Email PDF to signer** | Sends the signed document by email |
| **Show download button** | Download link on the thank-you view |
| **Redirect URL** | Send user to a custom page after signing |
| **Show PDF preview** | Inline preview before download |
| **Show verification link** | Link to online document verification |

---

## Wizard Step 2 — Form Builder

Drag fields from the palette onto the canvas. Click a field to edit settings in the right panel.

### Field Categories

**General:** name, email, text, textarea, number, url, phone, company, job_title

**Choice:** select, multiselect, radio, checkbox, GDPR

**Date & Time:** date, time

**Advanced:** columns (1–3), section_break, html, hidden, address, file upload

**Signing:** signature, initials, legal_consent, **payment**

### Required Rules

- At least one **Signature** field is required before publishing
- Only **one Payment field** per form
- **Signature**, **payment**, **legal_consent**, and **columns** cannot be placed **inside** column layouts

### Conditional Logic

Use **Field settings → Conditions** to show, hide, or require fields based on other answers (same pattern as Fluent Forms-style rules).

---

## Wizard Step 3 — Design

Customize how the form looks on the frontend without custom CSS.

### Presets

| Preset | Style |
|--------|-------|
| Professional | Clean business default |
| Modern | Bold accent, rounded cards |
| Minimal | Light borders, lots of whitespace |
| Editorial | Typography-focused layout |

### Controls

| Control | Options |
|---------|---------|
| **Density** | Comfortable, compact, spacious |
| **Labels** | Top, inline, hidden |
| **Field style** | Boxed, soft, underline |
| **Button style** | Solid, soft, outline |
| **Branding** | Accent color, background, card color, border radius, max width |
| **Hide form title** | Hide the title on the public form |

The **live preview** updates as you change settings.

---

## Wizard Step 4 — Compliance

| Setting | Description |
|---------|-------------|
| **OTP verification** | Require a one-time code before signing |
| **OTP channel** | Email, SMS (Twilio), or WhatsApp |
| **Capture geolocation** | Optional GPS consent for audit trail |
| **CC emails** | Additional recipients for the signed PDF |
| **Timestamp** | Uses your site TSA settings (**WPsigner → Security & Compliance**) |

### OTP Requirements

| Channel | Requirements |
|---------|--------------|
| **Email** | Email field on the form |
| **SMS** | Phone field + [Twilio](/integrations/twilio/) configured |
| **WhatsApp** | Phone field + [WhatsApp](/integrations/whatsapp/) configured |

If OTP is enabled with SMS or WhatsApp, the form must include a **phone** field before you can publish.

---

## Payment Field (Stripe)

Collect a fixed amount before the signer submits the form.

### Prerequisites

1. [Stripe configured](/integrations/stripe/) in **WPsigner → Integrations → Stripe**
2. Stripe module **enabled**
3. Valid test or live API keys and webhooks

### Configure the Field

1. In the builder, add a **Payment** field
2. Set **amount** (minimum **0.50**, maximum **10,000**)
3. Choose **currency** (or use Stripe default)
4. Optional **description** shown to the payer

### Signer Flow

1. Signer fills the form (including email if required)
2. Stripe **Payment Element** loads automatically when email is valid
3. Signer clicks **Pay now** and completes payment
4. Signer draws signature, accepts consent, clicks **Submit & Sign**
5. WPsigner verifies payment server-side before generating the PDF

> **tip**
In **Test Mode**, a yellow **Test mode** badge appears on the payment section. Use Stripe test cards only.

### Troubleshooting Payments

| Message | Solution |
|---------|----------|
| Stripe not configured | Complete [Stripe setup](/integrations/stripe/) |
| Enter email before paying | Add/fill email field before payment |
| Complete payment before submitting | Click **Pay now** and wait for success |
| Payment failed | Check Stripe keys, amount, and test card |

Payment is verified on the server before the signed PDF is created. Each successful payment can only be used once per submission.

---

## View Entries

1. Go to **WPsigner → Smart Signing Forms**
2. Click **View entries** on a form
3. Open an entry to see:
   - Submitted field data
   - **Download signed PDF**
   - Link to **audit trail** in WPsigner
   - **Verify online** link

---

## End-to-End Example

1. Install addon → create form with name, email, signature, payment ($10)
2. Configure [Stripe](/integrations/stripe/) in test mode
3. Enable OTP by email in Compliance step
4. Publish → add shortcode to a page
5. Submit as a test user: pay → verify OTP → sign → download PDF

---

## Next Steps

- [Stripe Payments](/integrations/stripe/) — API keys and webhooks
- [Addons Overview](/addons/overview/) — Install and activate the addon
- [Account Portal](/addons/account-portal/) — Download the latest ZIP
- [Twilio SMS](/integrations/twilio/) — OTP via SMS
- [Audit Trails](/digital-identity/audit-trails/) — What is recorded when someone signs

---

# WPsigner for Uncanny Automator

> Official addon that registers a native WPsigner integration in Uncanny Automator — triggers, actions, tokens, loops, and messaging on the same WordPress site.

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/addons/uncanny-automator/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator.md

**WPsigner for Uncanny Automator** is an official addon that registers a **WPsigner** integration inside [Uncanny Automator](https://automatorplugin.com/). Recipes start when a document is sent, signed, completed, paid, backed up, or deleted — and they can create or send WPsigner documents without leaving WordPress.

> **note**
Current addon version documented here: **1.2.0**. Requires **Uncanny Automator** and **WPsigner** (Lite or Pro) on the **same** WordPress site.

---

## What This Addon Does

| Capability | Description |
|------------|-------------|
| **Triggers** | Document lifecycle, Stripe payments, completed PDFs, and cloud backups |
| **Actions** | Create from a template (with prefill), send, remind, tag, expire, or message |
| **Tokens** | Document, signer, field, payment, and cloud values for later steps |
| **Loops** | Automator Pro token loops over all signers or pending signers |
| **Conditions** | Automator Pro checks for status, template, tag, or WordPress user |
| **Settings** | Hide signing URLs or field values from tokens and logs |
| **Everyone recipes** | Signing triggers are anonymous because signers are often guests |

```
┌──────────────────────────────────────────────┐
│  WordPress site                              │
│  ┌────────────┐   hooks    ┌──────────────┐  │
│  │  WPsigner  │───────────▶│ Uncanny      │  │
│  │  (core)    │◀───────────│ Automator    │  │
│  └────────────┘  actions   │ + this addon │  │
│                            └──────────────┘  │
│         No remote Automator app / API key    │
└──────────────────────────────────────────────┘
```

**Important:** This is not Zapier. Nothing is sent to Uncanny Owl or to WPsigner’s cloud. Templates, PDFs, emails, and signing URLs stay on your site.

---

## Documentation Map

| Guide | Contents |
|-------|----------|
| [Installation & Setup](/addons/uncanny-automator-installation/) | Requirements, ZIP install, first recipe |
| [Triggers](/addons/uncanny-automator-triggers/) | Every trigger, WordPress hook, and template filter |
| [Actions](/addons/uncanny-automator-actions/) | Create, send, remind, messaging, tags, expiration |
| [Tokens](/addons/uncanny-automator-tokens/) | Document, signer, field, loopable, and payment tokens |
| [Recipe Examples](/addons/uncanny-automator-recipes/) | WooCommerce, Slack, WhatsApp, Drive, refunds |
| [Settings](/addons/uncanny-automator-settings/) | Signing-URL privacy, field tokens, rate caps |
| [Security](/addons/uncanny-automator-security/) | Recipe trust, sanitization, rate limits, uninstall |
| [Troubleshooting](/addons/uncanny-automator-troubleshooting/) | Missing integration, empty tokens, messaging errors |

---

## Quick Start (5 Minutes)

1. Install and activate **Uncanny Automator** and **WPsigner** on the same site.
2. Install **WPsigner for Uncanny Automator** from the [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons).
3. Open **Automator → Recipes → Add Recipe** and choose **Everyone** (for guest signers) or **Logged-in users**.
4. Add a **WPsigner** trigger, for example *A WPsigner document is completed*.
5. Add any Automator action (email, CRM, LearnDash) or a WPsigner action (*Create a document from a template*).

Full steps: [Installation & Setup](/addons/uncanny-automator-installation/).

---

## Where to Find It in WordPress

| Screen | Path |
|--------|------|
| Recipes | **Automator → Recipes** |
| Addon settings | **Automator → WPsigner** (fallback: **Settings → WPsigner Automator**) |
| Marketplace card | **WPsigner → Addons** |
| WPsigner templates | **WPsigner → Templates** (needed for create/prefill) |

---

## Free Automator vs Pro

| Feature | Uncanny Automator (free) | Automator Pro |
|---------|--------------------------|---------------|
| WPsigner triggers | Yes | Yes |
| WPsigner actions | Yes | Yes |
| Tokens | Yes | Yes |
| Conditions (status, template, tag, WP user) | No | Yes |
| Token loops over signers | No | Yes |

---

## Trademark

WPsigner for Uncanny Automator is an independent addon by WPsigner. It is not affiliated with, endorsed by, or sponsored by Uncanny Owl. “Uncanny Automator” is a trademark of its respective owner and is used only to describe compatibility.

## Next Steps

- [Installation & Setup](/addons/uncanny-automator-installation/)
- [Recipe Examples](/addons/uncanny-automator-recipes/)
- [Zapier](/integrations/zapier/) — cloud alternative when you need SaaS apps outside WordPress
- [Addons Overview](/addons/overview/)

---

# Uncanny Automator — Actions

> Create, send, remind, tag, expire, and message WPsigner documents from Uncanny Automator recipes.

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/addons/uncanny-automator-actions/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-actions.md

WPsigner actions run only when the recipe is a **published** Automator recipe (`uo-recipe` or `uw_recipe`). Draft recipes fail with a clear log error.

All actions set `requires_user` to false so Everyone recipes can create and send documents.

---

## Document actions

| Action | Code | What it does |
|--------|------|----------------|
| Create a WPsigner document from a template | `WPS_CREATE_SEND_DOCUMENT` | Builds a document, maps signers, optional prefill, optional send |
| Send a document | `WPS_SEND_DOCUMENT` | Sends signing invitations for an existing document ID |
| Send a reminder | `WPS_SEND_REMINDER` | Email reminders for pending/viewed signers (optional email filter) |
| Cancel a document | `WPS_CANCEL_DOCUMENT` | Sets status to `cancelled` if the document is still open |
| Add a tag | `WPS_ADD_TAG` | Attaches a tag without removing existing ones (max 5) |
| Add a signer | `WPS_ADD_SIGNER` | Adds a signer; optionally sends if the document is already sent/viewed |
| Set expiration | `WPS_SET_EXPIRATION` | Sets `expires_at`, or clears it when the field is empty (max 5 years ahead) |
| Get signers | `WPS_GET_SIGNERS` | Exposes emails, JSON lists, and pending count as action tokens |

---

## Create from a template

Recipe fields:

| Field | Required | Notes |
|-------|----------|-------|
| Template | Yes | No “Any” option — pick a real template |
| Required signers for this template | No | AJAX hint after you pick a template |
| Document title | No | Empty → template name + current date/time |
| Send for signing immediately | Yes | Yes / create as draft |
| Signing workflow | Yes | Parallel or sequential |
| Use the recipe user as signer 1 | Yes | Fills signer 1 from the recipe user when that email is empty |
| Signer 1–5 name/email | Signer emails as required by the template | Extra empty slots are ignored |
| Prefill template variables | No | JSON object or `key=value` lines |

The AJAX hint uses Automator’s recipe-builder auth check (`wpsua_get_template_meta`). If it fails, you can still fill slots 1–5 manually.

Template slots must cover every `signer_order` used on the template. Missing slot → *This template requires a signer for slot N.*

### Prefill

Keys must match the template **Mapping name** (or field key). Same keys as [form feeds / Zapier](/core-features/form-fields/#mapping-name-rules-important).

JSON:

```json
{"client_name":"{{BILLING_FIRST_NAME}}","company":"Acme"}
```

Or lines:

```
client_name={{BILLING_FIRST_NAME}}
company=Acme
```

Rules:

- Automator tokens in values are parsed **before** WPsigner fills fields
- Maximum 40 keys; key ≤ 80 characters; value ≤ 500 characters
- Signature, initials, label, attachment, image, and stamp fields are never prefilled
- Prefill runs **after** create and **before** send, so the emailed PDF can include values

Action tokens after create include document ID, title, status, admin URL, sent yes/no, signer 1–3 emails/URLs (when allowed), field JSON, and `FIELD_*` values.

---

## Messaging actions

These call WPsigner’s existing messaging classes. They do **not** store API keys in Automator.

| Action | Code | Channel |
|--------|------|---------|
| Send a reminder via channel | `WPS_SEND_CHANNEL_REMINDER` | WhatsApp, SMS (Twilio), Slack, Telegram, or Teams |
| Send a Slack message via WPsigner | `WPS_SEND_SLACK_MESSAGE` | Custom text through the Slack webhook already configured in WPsigner |

Channel reminders require:

1. The matching integration **enabled and configured** in WPsigner
2. Document status `sent` or `viewed`
3. Pending/viewed signers (optional email filter)

WhatsApp and SMS also need a valid phone number on the signer. Telegram needs a chat ID WPsigner can resolve for that signer. If the channel cannot send, the action fails with an explicit error — it does not silently skip.

Configure channels: [WhatsApp](/integrations/whatsapp/), [Twilio](/integrations/twilio/), [Slack](/integrations/slack/), [Telegram](/integrations/telegram/), [Teams](/integrations/teams/).

Slack custom messages are stripped of HTML, capped at 2,000 characters, and rate-limited. Do not paste secrets. Signing URLs appear only if you insert that token.

---

## Rate limits

| Limit | Default | Override |
|-------|---------|----------|
| Send / remind / channel cooldown | 20 seconds per document (or channel) | Transient `wpsua_rl_*` |
| Slack custom message cooldown | 20 seconds global | Same |
| Automated creates | 60 per hour | [Settings](/addons/uncanny-automator-settings/) or `wpsua_max_creates_per_hour` |
| Signers on create | 5 (max 10) | Settings or `wpsua_max_signers` |

Exceeded limits return a log error, not a partial send.

---

## Next Steps

- [Tokens](/addons/uncanny-automator-tokens/)
- [Recipe Examples](/addons/uncanny-automator-recipes/)
- [Settings](/addons/uncanny-automator-settings/)
- [Security](/addons/uncanny-automator-security/)

---

# Uncanny Automator — Installation & Setup

> Install WPsigner for Uncanny Automator, confirm both plugins are active, and create the first recipe.

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/addons/uncanny-automator-installation/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-installation.md

Install this addon on the **same WordPress site** that already runs Uncanny Automator and WPsigner. There is no child-site install, no Automator app key, and no webhook to WPsigner Cloud.

---

## Requirements

| Component | Minimum | Notes |
|-----------|---------|-------|
| WordPress | 5.8+ | Tested up to 7.1 |
| PHP | 7.4+ | Same as WPsigner |
| [Uncanny Automator](https://wordpress.org/plugins/uncanny-automator/) | Active | Free edition is enough for triggers and actions |
| [WPsigner](/getting-started/installation/) | Active | Needs Document, Template, and Signer models |
| Uncanny Automator Pro | Optional | Conditions and signer token loops only |
| Capability | `activate_plugins` | To install the ZIP |

> **Requires WPsigner Pro for templates**
Create-from-template actions need **WPsigner templates**, which are a Pro feature. Triggers on documents you already send from Lite still work if WPsigner is active, but most Automator recipes assume Pro templates.

---

## Install

1. Log in to the [Account Portal → Addons](https://app.wpsigner.com/account/?portal_tab=addons).
2. Download **WPsigner for Uncanny Automator**. Portal links expire in about one hour.
3. In WordPress: **Plugins → Add New → Upload Plugin** → install the ZIP → **Activate**.
4. Confirm **Uncanny Automator** and **WPsigner** are also active.

See [Account Portal](/addons/account-portal/) and [Addons Overview](/addons/overview/) for the general download flow.

---

## After Activation

The addon:

- Registers the **WPsigner** integration in Automator (code `WPSIGNER`)
- Listens to `wps_document_created_from_template` so later triggers can filter by template
- Adds a card on **WPsigner → Addons**
- Adds **Automator → WPsigner** for privacy settings

If Automator or WPsigner is missing, administrators see an error notice. The integration does not appear in the recipe builder until **both** dependencies and this addon are active.

---

## First Recipe

1. Open **Automator → Recipes → Add Recipe**.
2. Choose **Everyone** if signers may be guests (recommended for *signed* / *completed*). Use **Logged-in users** only for *A WordPress user signs a document*.
3. Add trigger **WPsigner → A WPsigner document is completed**. Leave the template on **Any template**.
4. Add an action — for a smoke test, **Send an email** to yourself with the Document title token.
5. **Publish** the recipe. Draft recipes do not run WPsigner actions.

Then complete a test document in WPsigner. Automator → Logs should show the recipe run.

---

## Settings After Install

Open **Automator → WPsigner** and decide whether signing URLs belong in tokens. Default is on. Details: [Settings](/addons/uncanny-automator-settings/).

---

## Updates

Update the addon ZIP from the Account Portal like other official addons. Keep Uncanny Automator current so the Integration Framework (`\Uncanny_Automator\Integration`) is present.

---

## Next Steps

- [Triggers](/addons/uncanny-automator-triggers/)
- [Actions](/addons/uncanny-automator-actions/)
- [Recipe Examples](/addons/uncanny-automator-recipes/)
- [Troubleshooting](/addons/uncanny-automator-troubleshooting/)

---

# Uncanny Automator — Recipe Examples

> Ready-to-build Uncanny Automator recipes for WPsigner — WooCommerce contracts, Slack, WhatsApp loops, Drive, and refunds.

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/addons/uncanny-automator-recipes/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-recipes.md

Build these on **Automator → Recipes**. Publish the recipe or WPsigner actions will refuse to run.

Use **Everyone** unless the example says logged-in.

---

## WooCommerce order → contract

**Goal:** After payment, create and send a WPsigner agreement prefilled with billing data.

| Step | Integration | Item |
|------|-------------|------|
| Trigger | WooCommerce | A user’s order status changes to completed (or paid) |
| Action | WPsigner | Create a document from a template |

Create action:

- Template: your contract template
- Send immediately: **Yes**
- Workflow: Parallel (or Sequential if countersigners must wait)
- Use recipe user as signer 1: **Yes** if the buyer is a WP user; otherwise map **Signer 1 email** to the billing email token
- Prefill:

```
client_name={{BILLING_FIRST_NAME}} {{BILLING_LAST_NAME}}
client_email={{BILLING_EMAIL}}
company={{BILLING_COMPANY}}
order_id={{ORDER_ID}}
```

Mapping names on the template must match those keys. See [Form Fields → Mapping name](/core-features/form-fields/#mapping-name-rules-important).

Native WooCommerce feeds in WPsigner can do the same without Automator: [WooCommerce](/integrations/woocommerce/). Use Automator when you also need LearnDash, CRM, or delays.

---

## Document completed → LMS or CRM

| Step | Item |
|------|------|
| Trigger | A WPsigner document is completed (specific template) |
| Condition (Pro) | Signer is a WordPress user — use Signer email token if present, or Owner email |
| Action | LearnDash enroll / FluentCRM tag / add user role |

Everyone recipes may have no signer token on *completed*. Use **Owner email**, or switch the trigger to *A document is signed* plus a condition that document status becomes completed, or store the buyer as document owner when creating.

---

## Declined → Slack

| Step | Item |
|------|------|
| Trigger | A WPsigner document is declined |
| Action | Send a Slack message via WPsigner |

Message example:

```
Declined: {{DOCUMENT_TITLE}} (ID {{DOCUMENT_ID}})
Signer: {{SIGNER_NAME}} <{{SIGNER_EMAIL}}>
Reason: {{DECLINE_REASON}}
Admin: {{DOCUMENT_ADMIN_URL}}
```

Requires [Slack](/integrations/slack/) configured in WPsigner. Do not include `{{SIGNING_URL}}` on a declined document (it is empty).

---

## Sent → WhatsApp reminder per pending signer (Pro)

| Step | Item |
|------|------|
| Trigger | A document is sent |
| Loop | Token loop → **WPsigner pending signers** |
| Delay (optional) | Wait 2 days |
| Action inside loop | Send a WPsigner reminder via channel → WhatsApp |

Leave signer email empty on the action to use the current loop signer only if the action has an email field — for channel reminder, set **Signer email** to the loop’s **Signer email** child token so you do not blast every remaining signer on each iteration.

Requires WhatsApp Business configured and a phone on each signer: [WhatsApp](/integrations/whatsapp/).

Without Pro loops: one **Send a reminder** (email) action for all pending signers, or **Get signers** → webhook.

---

## Cloud backup → notify

| Step | Item |
|------|------|
| Trigger | A completed PDF is uploaded to cloud storage → Google Drive |
| Action | Send Slack / Teams / email with `{{CLOUD_URL}}` and `{{DOCUMENT_TITLE}}` |

If `CLOUD_URL` is empty, WPsigner did not store a public `https` link. Open the file from WPsigner’s backup metadata instead of inventing a path.

---

## Payment refunded → cancel

| Step | Item |
|------|------|
| Trigger | A WPsigner Stripe payment is refunded |
| Action | Cancel a WPsigner document → Document ID token |

Only works while the document is still open (not completed/declined/expired). Completed contracts should not be cancelled this way — tag them or notify finance instead.

---

## Form plugin → create (when you need extra Automator steps)

Form feeds in WPsigner already create documents. Use Automator when the path is **form → wait / branch / other plugin → WPsigner**.

| Step | Item |
|------|------|
| Trigger | Fluent Forms / WPForms / Gravity Forms entry |
| Action | Create a WPsigner document from a template |

Prefill mapping names from the form tokens. Same keys as [Fluent Forms](/integrations/fluent-forms/) feeds.

---

## Logged-in user signed → grant access

| Step | Item |
|------|------|
| Recipe type | Logged-in users |
| Trigger | A WordPress user signs a document from {{membership template}} |
| Action | Change user role / add membership / LearnDash course |

Guest signers will not fire this trigger. Pair with an Everyone *completed* recipe if you also sell to guests.

---

## Next Steps

- [Triggers](/addons/uncanny-automator-triggers/)
- [Actions](/addons/uncanny-automator-actions/)
- [Tokens](/addons/uncanny-automator-tokens/)
- [Troubleshooting](/addons/uncanny-automator-troubleshooting/)

---

# Uncanny Automator — Security

> Recipe trust, sanitization, signing-URL handling, rate limits, and uninstall behavior for WPsigner for Uncanny Automator 1.2.0.

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/addons/uncanny-automator-security/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-security.md

The addon is a **local WordPress integration**. It does not phone home, does not register a public REST route, and does not store Uncanny or Stripe API keys.

Documented behavior reflects **addon v1.2.0**.

---

## Trust boundary

| Control | Implementation |
|---------|----------------|
| Direct file access | `ABSPATH` (or `WP_UNINSTALL_PLUGIN`) on every PHP file |
| Recipe trust | Actions require a published Automator recipe (`uo-recipe` / `uw_recipe`) |
| Capabilities | Settings page: `manage_options`. AJAX template meta: Automator `ajax_auth_check()` |
| Input | Emails, titles, IDs, statuses, channels, and prefill maps are sanitized before WPsigner APIs run |
| Prefill | Max 40 keys; values `sanitize_text_field`, 500 characters; signature-like types skipped |

Draft recipes cannot create or send documents.

---

## URLs and secrets

| Data | How it is exposed |
|------|-------------------|
| Signing URL | WPsigner `Signer::get_signing_url` only. Optional via settings / `wpsua_include_signing_url` |
| Download URL | `Document::get_secure_download_url` after sign/complete. Never a homemade token |
| Cloud URL | Existing `https` share/view URL or backup option. No local `file_path` |
| Slack / WhatsApp | Uses credentials already stored by WPsigner messaging integrations |
| Payment intent ID | Stripe ID string only |

> **caution**
If a recipe uses the Signing URL token, Automator may store it in **Automator → Logs**. Treat those logs like password storage. Disable the token in [Settings](/addons/uncanny-automator-settings/) when the next step does not need the link.

---

## Rate limits

| Action | Window |
|--------|--------|
| Send, remind, channel remind | 20 seconds per document (and channel) |
| Slack custom message | 20 seconds global |
| Create from template | Hourly cap (default 60) |

Limits are transients, not a permanent lockout. They exist so a looping recipe cannot mail-bomb signers.

---

## Template source map

Option `wpsua_document_sources` maps document ID → template ID so triggers can filter by template. The map is capped (`wpsua_source_map_max`, default 2000, oldest entries dropped). It does not contain PDFs or signing tokens.

---

## AJAX

`admin-ajax.php` action `wpsua_get_template_meta` (and `automator_wpsua_get_template_meta`) returns required signer slots and fillable field labels for the recipe builder. It does not return signing URLs or field values. Auth is Automator’s recipe-builder check, with a `manage_options` / `edit_posts` fallback if Automator is unavailable.

---

## Uninstall

`uninstall.php` runs only when this plugin is the one being removed. It deletes:

- `wpsua_document_sources`
- `wpsua_settings`
- Transients whose names start with `wpsua_`

It does **not** delete WPsigner documents, signers, Automator recipes, or logs.

---

## Trademark and data sharing

WPsigner for Uncanny Automator is not affiliated with Uncanny Owl. Installing it does not send site data to Uncanny or to WPsigner.

---

## Next Steps

- [Settings](/addons/uncanny-automator-settings/)
- [Troubleshooting](/addons/uncanny-automator-troubleshooting/)
- [Report a Security Issue](/support/security/)

---

# Uncanny Automator — Settings

> Privacy and rate-limit settings for WPsigner for Uncanny Automator — signing URLs, field tokens, and create caps.

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/addons/uncanny-automator-settings/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-settings.md

Open **Automator → WPsigner**. If the Automator menu is missing, use **Settings → WPsigner Automator**. The same page is linked from the plugin row (**Settings**).

Capability required: `manage_options`.

---

## Options

| Option | Default | What it controls |
|--------|---------|------------------|
| Include signing URLs in tokens | On | `SIGNING_URL` and per-signer URLs on create/add-signer |
| Include field values in tokens | On | `DOCUMENT_FIELDS` JSON and `FIELD_*` tokens |
| Max documents created per hour | 60 | Automated create action (1–500) |
| Max signers per create action | 5 | Signer slots processed on create (1–10) |

Uncheck signing URLs when recipes only need names, emails, and document IDs. Automator logs often persist token values.

Uncheck field values if templates collect personal data you do not want in Automator logs.

---

## Filters

Settings feed these filters (priority 5). Your code can still force a stricter value:

```php
add_filter('wpsua_include_signing_url', '__return_false');

add_filter('wpsua_max_creates_per_hour', function ($max) {
    return 20;
});
```

| Filter | Notes |
|--------|--------|
| `wpsua_include_signing_url` | Receives current include flag |
| `wpsua_include_field_values` | Same for field tokens |
| `wpsua_max_creates_per_hour` | Settings value unless another filter runs later |
| `wpsua_max_signers` | Clamped 1–10 in the create bridge |
| `wpsua_source_map_max` | Template origin map size (default 2000) |

---

## Storage

| Option / transient | Purpose |
|--------------------|---------|
| `wpsua_settings` | This screen |
| `wpsua_document_sources` | Document ID → template ID map |
| `wpsua_rl_*` | Short send/remind cooldowns |
| `wpsua_creates_YYYYMMDDHH` | Hourly create counter |

[Uninstall](/addons/uncanny-automator-security/#uninstall) deletes the settings option, the source map, and `wpsua_*` transients. It does not delete WPsigner documents or Automator recipes.

---

## Next Steps

- [Tokens](/addons/uncanny-automator-tokens/)
- [Security](/addons/uncanny-automator-security/)
- [Installation](/addons/uncanny-automator-installation/)

---

# Uncanny Automator — Tokens

> Document, signer, field, payment, cloud, and loopable tokens exposed by WPsigner for Uncanny Automator.

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/addons/uncanny-automator-tokens/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-tokens.md

Tokens pass WPsigner data into later Automator actions (email body, CRM fields, webhooks). Signing URLs and field values can be turned off under [Settings](/addons/uncanny-automator-settings/).

---

## Document tokens (all document triggers)

| Token ID | Name | Notes |
|----------|------|-------|
| `DOCUMENT_ID` | Document ID | Integer |
| `DOCUMENT_TITLE` | Document title | |
| `DOCUMENT_STATUS` | Document status | `draft`, `sent`, `viewed`, `completed`, `declined`, `expired`, `cancelled` |
| `DOCUMENT_CREATED_AT` | Created at | |
| `DOCUMENT_COMPLETED_AT` | Completed at | |
| `DOCUMENT_EXPIRES_AT` | Expires at | |
| `DOCUMENT_ADMIN_URL` | Admin edit URL | `admin.php?page=insigner-edit&id=` |
| `DOCUMENT_DOWNLOAD_URL` | Secure download URL | Only after that signer signed, or when the document is completed. Time-limited WPsigner link — never a invented public token |
| `DOCUMENT_AUDIT_URL` | Audit screen URL | Admin |
| `DOCUMENT_CERTIFICATE_ID` | Certificate ID | |
| `DOCUMENT_OWNER_ID` | Owner user ID | |
| `DOCUMENT_OWNER_EMAIL` | Owner email | |
| `DOCUMENT_TAGS` | Tags | Comma-separated |
| `DOCUMENT_FIELDS` | Field values JSON | Non-signature fields; values truncated at 500 characters |
| `SIGNERS_EMAILS` | All signer emails | Comma-separated |
| `SIGNERS_JSON` | All signers JSON | Array of signer objects |
| `SIGNERS_PENDING_JSON` | Pending signers JSON | `pending` and `viewed` |
| `TEMPLATE` | Template name | When the source map knows the template |
| `TEMPLATE_ID` | Template ID | |

---

## Signer tokens

Registered on viewed, signed, declined, reminder, payment, and “user signs” triggers.

| Token ID | Name | Notes |
|----------|------|-------|
| `SIGNER_ID` | Signer ID | |
| `SIGNER_NAME` | Signer name | |
| `SIGNER_EMAIL` | Signer email | |
| `SIGNER_STATUS` | Signer status | |
| `SIGNING_URL` | Signing URL | Empty if signed/declined, or if settings hide URLs |
| `SIGNER_WP_USER_ID` | WordPress user ID | Empty when the email is not a WP account |
| `DECLINE_REASON` | Decline reason | Declined trigger only |

> **Signing URLs are secrets**
A signing URL is a bearer link (`/insigner/{access_token}`). Automator logs may store token values. Turn **Include signing URLs in tokens** off if the next action does not need the link. Prefer WPsigner’s own email/SMS over copying URLs into third-party CRMs.

---

## Field tokens (`FIELD_*`)

When a trigger is limited to a **specific template**, the recipe builder lists one token per fillable field (up to 40). The ID is `FIELD_` plus the mapping name or field key in uppercase (`client_name` → `FIELD_CLIENT_NAME`).

Skipped types: signature, initials, label, attachment, image, stamp.

On **Any template**, individual `FIELD_*` tokens are not listed (too many templates). Use `DOCUMENT_FIELDS` JSON instead. Runtime still hydrates `FIELD_*` keys when values exist.

Create-action tokens also include `DOCUMENT_FIELDS` and hydrated `FIELD_*` values after prefill.

---

## Payment tokens

| Token ID | Name | Triggers |
|----------|------|----------|
| `PAYMENT_AMOUNT` | Amount (major units) | Succeeded, failed, refunded |
| `PAYMENT_CURRENCY` | Currency | Same |
| `PAYMENT_INTENT` | Stripe PaymentIntent ID | Same |
| `PAYMENT_ERROR` | Last error message | Failed only |

---

## Cloud tokens

| Token ID | Name |
|----------|------|
| `CLOUD_PROVIDER` | `google_drive`, `dropbox`, `onedrive`, or `s3` |
| `CLOUD_REFERENCE` | File ID, remote path, or object key — not a local disk path |
| `CLOUD_URL` | `https` URL only when WPsigner already has one |

---

## Update token

| Token ID | Name |
|----------|------|
| `UPDATED_KEYS` | Comma-separated keys that changed on the document row (no values) |

---

## Loopable tokens (Automator Pro)

Document triggers register two loopable tokens when Uncanny Automator 5.10+ / Pro token loops are available:

| Loopable token | Iterates |
|----------------|----------|
| **WPsigner signers** (`WPS_SIGNERS`) | Every signer on the document |
| **WPsigner pending signers** (`WPS_PENDING_SIGNERS`) | Status `pending` or `viewed` |

Child tokens per iteration: `SIGNER_ID`, `SIGNER_NAME`, `SIGNER_EMAIL`, `SIGNER_STATUS`, `SIGNER_WP_USER_ID`, `SIGNING_URL`.

How to use:

1. Add a WPsigner trigger (for example *A document is sent*).
2. In Actions, click **Add → Token loop**.
3. Choose **WPsigner pending signers**.
4. Inside the loop, send email / WhatsApp / a webhook using the loop’s signer tokens.

Uncanny’s guide: [Token Loops](https://automatorplugin.com/knowledge-base/token-loops/).

The **Get signers** action is the non-loop alternative: it outputs JSON you can post to a webhook.

---

## Conditions (Automator Pro)

| Condition | Code | Fields |
|-----------|------|--------|
| Document status is | `WPS_DOC_STATUS` | Document ID + status |
| Document is from template | `WPS_DOC_TEMPLATE` | Document ID + template |
| Document has tag | `WPS_DOC_HAS_TAG` | Document ID + tag name |
| Signer email is a WordPress user | `WPS_SIGNER_IS_WP_USER` | Signer email |

Use a Document ID token from the trigger. Conditions do not run on Automator free.

---

## Filters (developers)

| Filter | Default | Effect |
|--------|---------|--------|
| `wpsua_include_signing_url` | Settings checkbox (on) | Hide signing URLs |
| `wpsua_include_field_values` | Settings checkbox (on) | Hide field JSON / `FIELD_*` |
| `wpsua_max_creates_per_hour` | 60 | Cap automated creates |
| `wpsua_max_signers` | 5 | Cap create-action signers (1–10) |
| `wpsua_source_map_max` | 2000 | Max document→template map entries |

---

## Next Steps

- [Actions](/addons/uncanny-automator-actions/)
- [Recipe Examples](/addons/uncanny-automator-recipes/)
- [Settings](/addons/uncanny-automator-settings/)
- [Security](/addons/uncanny-automator-security/)

---

# Uncanny Automator — Triggers

> All WPsigner triggers for Uncanny Automator — document events, Stripe payments, cloud backups, and template filters.

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/addons/uncanny-automator-triggers/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-triggers.md

Every WPsigner trigger can be limited to **Any template** or a specific WPsigner template. Matching uses the `wps_document_created_from_template` hook (WPsigner 3.x+) plus a local option map (`wpsua_document_sources`) maintained by the addon. Documents not created from a template still fire when the trigger is set to **Any**.

Most triggers are **Everyone** (anonymous) recipes. Only **A WordPress user signs a document** is a logged-in recipe.

---

## Document lifecycle

| Trigger (recipe sentence) | Code | WordPress hook | Signer tokens |
|---------------------------|------|----------------|---------------|
| A document is created from a template | `WPS_DOCUMENT_CREATED` | `wps_document_created` | No |
| A document from a template is sent | `WPS_DOCUMENT_SENT` | `wps_document_sent` | No |
| A document from a template is viewed | `WPS_DOCUMENT_VIEWED` | `wps_document_viewed` | Yes |
| A document from a template is signed | `WPS_DOCUMENT_SIGNED` | `wps_after_document_signed` | Yes |
| A document from a template is completed | `WPS_DOCUMENT_COMPLETED` | `wps_document_completed` | No |
| A document from a template is declined | `WPS_DOCUMENT_DECLINED` | `wps_document_declined` | Yes + decline reason |
| A document from a template expires | `WPS_DOCUMENT_EXPIRED` | `wps_document_expired` | No |
| A document from a template is cancelled | `WPS_DOCUMENT_CANCELLED` | `wps_document_status_changed` (`cancelled`) | No |
| A document from a template is updated | `WPS_DOCUMENT_UPDATED` | `wps_document_updated` | No |
| A document from a template is moved to trash | `WPS_DOCUMENT_SOFT_DELETED` | `wps_document_soft_deleted` | No |
| A document from a template is permanently deleted | `WPS_DOCUMENT_DELETED` | `wps_document_deleted` | No |
| A reminder is sent for a document from a template | `WPS_REMINDER_SENT` | `wps_reminder_sent` | Yes |
| The completed PDF is generated | `WPS_PDF_COMPLETED` | `wps_pdf_completed` | No |

> **Update trigger is noisy**
`wps_document_updated` fires on many row changes (title, status, expiration, workflow). Pair it with [conditions](/addons/uncanny-automator-tokens/#conditions-automator-pro) if you only want one kind of change. The **Updated field keys** token lists keys only — not values or file paths.

Deleted triggers still receive a document snapshot from the hook when the row is already gone. Template matching uses the stored source map.

---

## Payments (Stripe)

Requires the [Stripe](/integrations/stripe/) integration in WPsigner so PaymentIntents include `document_id` metadata.

| Trigger | Code | Hook | Extra tokens |
|---------|------|------|----------------|
| A payment succeeds | `WPS_PAYMENT_SUCCEEDED` | `wps_stripe_payment_succeeded` | Amount, currency, PaymentIntent ID |
| A payment fails | `WPS_PAYMENT_FAILED` | `wps_stripe_payment_failed` | Amount, currency, intent, error message |
| A payment is refunded | `WPS_PAYMENT_REFUNDED` | `wps_stripe_payment_refunded` | Refunded amount, currency, intent |

Amount tokens are major units (cents ÷ 100). Refunded events resolve the document from charge metadata or WPsigner’s payment row.

---

## Cloud backups

| Trigger | Code | Hooks |
|---------|------|-------|
| A completed PDF is uploaded to cloud storage | `WPS_CLOUD_UPLOADED` | `wps_google_drive_uploaded`, `wps_dropbox_uploaded`, `wps_onedrive_uploaded`, `wps_s3_uploaded` |

Filter by **Any connected provider**, Google Drive, Dropbox, OneDrive, or S3-compatible storage.

Tokens: **Cloud provider**, **Cloud file reference**, **Cloud file URL**. The URL is included only when it is already a public `https` link (Drive viewer, Dropbox/OneDrive share, or WPsigner backup metadata). The addon never exposes a local filesystem path.

Configure storage first: [Google Drive](/integrations/google-drive/), [Dropbox](/integrations/dropbox/), [OneDrive](/integrations/onedrive/), [Amazon S3](/integrations/amazon-s3/).

---

## Logged-in user

| Trigger | Code | Hook |
|---------|------|------|
| A WordPress user signs a document from a template | `WPS_USER_SIGNED` | `wps_after_document_signed` |

This trigger **does not** fire for guest signers. The signer email must match a WordPress user. Use it for membership, LMS, or role recipes. For mixed guest + user traffic, use *A document is signed* (Everyone) instead.

---

## Template filter

| Recipe option | Behavior |
|---------------|----------|
| **Any template** (`-1`) | All documents |
| Specific template ID | Only documents created from that template (source map) |

Documents created in the WPsigner UI from a template are recorded automatically. Documents created by this addon’s create action are recorded the same way.

---

## User binding

When a trigger runs, the addon sets Automator’s user ID if:

1. The signer email matches a WordPress account, or
2. The document owner (`user_id`) is a WordPress user

Everyone recipes can still run without a user. Logged-in recipes require a bound user (the user-signed trigger enforces the email match).

---

## Next Steps

- [Tokens](/addons/uncanny-automator-tokens/)
- [Actions](/addons/uncanny-automator-actions/)
- [Recipe Examples](/addons/uncanny-automator-recipes/)

---

# Uncanny Automator — Troubleshooting

> Fix missing WPsigner integration, empty tokens, prefill misses, messaging errors, and rate limits in Uncanny Automator.

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/addons/uncanny-automator-troubleshooting/
Markdown: https://docs.wpsigner.com/md/addons/uncanny-automator-troubleshooting.md

Use this page when a WPsigner recipe does not appear, does not fire, or fails in **Automator → Logs**. For core WPsigner mail/PDF issues, see [Support → Troubleshooting](/support/troubleshooting/).

---

## Missing integration

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No WPsigner card in the recipe builder | Addon, Automator, or WPsigner inactive | Activate all three on the **same** site |
| Admin error notice | Dependency missing | Install [Uncanny Automator](https://wordpress.org/plugins/uncanny-automator/) and [WPsigner](/getting-started/installation/) |
| Integration vanished after Automator update | Framework class missing | Update Automator so `\Uncanny_Automator\Integration` exists |
| Conditions missing | Automator Pro not active | Conditions need Pro; triggers/actions work on free |

---

## Recipe does not fire

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Nothing in logs | Recipe still draft | **Publish** the recipe |
| Nothing in logs | Wrong recipe type | Use **Everyone** for guest signers; logged-in only for *A WordPress user signs* |
| Fires for other templates only | Template filter | Set **Any template**, or create the document from the selected template |
| User-signed never fires | Guest email | Signer email must match a WP user |
| Cloud trigger silent | Storage not connected | Configure Drive / Dropbox / OneDrive / S3 in WPsigner first |
| Payment trigger silent | No Stripe metadata | PaymentIntent must include `document_id` from WPsigner Stripe |

Template matching needs `wps_document_created_from_template` (WPsigner 3.x+) or a create action from this addon. Older documents may only match **Any template**.

---

## Actions fail

| Log / error | Fix |
|-------------|-----|
| The Automator recipe is not published | Publish the recipe |
| WPsigner is not available | Activate WPsigner |
| Template not found | Pick a template that still exists |
| This template requires a signer for slot N | Fill that signer email; check the AJAX hint |
| Provide at least one valid signer email | Signer 1 empty and “use recipe user” is No, or user has no email |
| Hourly document-creation limit reached | Wait, or raise the cap in [Settings](/addons/uncanny-automator-settings/) |
| Please wait a few seconds before sending again | 20s cooldown on send/remind |
| This document can no longer be sent / cancelled | Terminal status (completed, declined, expired, cancelled, trash) |
| Could not attach the tag | Document already has five tags |
| Expiration cannot be more than five years | Use a nearer date; empty field clears expiration |

---

## Prefill

| Symptom | Fix |
|---------|-----|
| Fields blank after create | Mapping names ≠ prefill keys. Align with [Form Fields](/core-features/form-fields/#mapping-name-rules-important) |
| JSON ignored | Invalid JSON — use `key=value` lines instead |
| Tokens not replaced | Put Automator tokens in the prefill field; they parse before WPsigner |
| Signature field empty | Expected — signature types are never prefilled |

---

## Tokens empty

| Token | Why it is empty | Fix |
|-------|-----------------|-----|
| Signing URL | Settings off, or signer already signed/declined | Enable URLs; use a viewed/sent trigger |
| Secure download URL | Not signed/completed yet | Wait for complete, or use a signed trigger |
| `FIELD_*` | Trigger set to Any template, or field values disabled | Select the template; enable field tokens |
| Template ID | Document not created from a known template | Create from a template (UI or action) |
| Cloud URL | No public `https` link stored | Use provider’s share settings; never a disk path |
| Signer WP user ID | Email is not a WP account | Expected for guests |

---

## Messaging

| Symptom | Fix |
|---------|-----|
| Channel not enabled or configured | Open WPsigner → Integrations for WhatsApp / Twilio / Slack / Telegram / Teams |
| Reminder not sent (WhatsApp/SMS) | Add a valid phone on the signer |
| Telegram silent | Signer has no chat ID WPsigner can resolve |
| Slack message empty | Provide text; HTML is stripped |
| Channel reminder on draft | Send the document first (`sent` / `viewed`) |

---

## Loops

| Symptom | Fix |
|---------|-----|
| No Token loop / no WPsigner signers token | Automator Pro + Automator 5.10+ loopable tokens |
| Loop runs zero times | No signers, or pending filter with everyone already signed |
| Same signer repeated | Inside the loop, bind channel reminder to the **loop** signer email token |

---

## AJAX signer hint

If **Required signers for this template** stays on the placeholder, the recipe still works: fill slots 1–5 manually. Confirm you are logged in as a user who can edit Automator recipes. Endpoint: `wpsua_get_template_meta`.

---

## Next Steps

- [Installation](/addons/uncanny-automator-installation/)
- [Security](/addons/uncanny-automator-security/)
- [Support Troubleshooting](/support/troubleshooting/)
- [Contact](https://wpsigner.com/contact/)