Automating Perfex CRM with a REST API: webhooks, OpenAPI and MCP for AI agents

#api #php #automation #ai

Full disclosure up front: we build the module discussed here. This is Themesic Interactive's own writeup of the REST API module for Perfex CRM. Every number below is verifiable - the OpenAPI spec, the Postman collection and copy-paste examples all live in a public GitHub repo linked at the end, and you can regenerate the spec from any installation yourself.

The gap

Perfex CRM is a popular self-hosted PHP CRM. Out of the box it has no REST API: no endpoint to create a lead from your website form, no way for n8n or Zapier to react to a new invoice, nothing an AI agent can call.

The REST API for Perfex CRM module adds that layer: 72 paths and 139 operations over the CRM's entities (customers, contacts, leads, invoices, estimates, proposals, credit notes, payments, projects, tasks, milestones, tickets, contracts, expenses, items, staff, subscriptions, timesheets, calendar, knowledge base, notes), plus webhooks, a batch endpoint and an MCP server. On CodeCanyon it is rated 4.91/5 from 44 verified reviews across 2,941 sales, and v3.0.3 is the release this article uses.

60 seconds to your first request

Install the module, then create a token under Setup > API > API Management in the Perfex admin. Every request authenticates with the authtoken header:

curl -H "authtoken: YOUR_API_TOKEN" \
  "https://your-perfex-url/api/customers?page=1&per_page=25"

Creating a lead from anywhere (a landing page handler, a cron job, a chatbot):

curl -X POST "https://your-perfex-url/api/leads" \
  -H "authtoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "source": "2", "status": "1", "email": "jane@example.com"}'

List endpoints take opt-in modifiers, so you only pull what you need:

GET /api/invoices?fields=id,total,status&sort=-date
GET /api/customers?created_after=2026-01-01&created_before=2026-06-30
GET /api/leads/search/acme

Writes support an Idempotency-Key header for safe retries, and responses carry X-RateLimit-* headers so your integration can back off politely.

Webhooks instead of polling

Since v3.0 the module ships 124 webhook events across 22 event groups, managed entirely over REST:

POST /api/webhooks              # subscribe a URL to events
GET  /api/webhooks/events       # list all 124 available events
POST /api/webhooks/{id}/toggle  # pause and resume
GET  /api/webhooks/{id}/logs    # delivery history for debugging

Deliveries are asynchronous with retries, requests are HMAC-signed so your receiver can authenticate the payload, and outbound URLs go through SSRF protection. For polling-based tools (Zapier, Make, n8n's trigger nodes) there are ready-made polling endpoints as well, and a POST /api/batch endpoint runs up to 50 operations in one request.

The whole API as one file: OpenAPI

The module describes its entire surface as an OpenAPI 3.0 document, generated live by the installation itself so it always matches the installed version:

curl -H "authtoken: YOUR_API_TOKEN" \
  https://your-perfex-url/api/openapi -o perfex-rest-api.openapi.json

Import that file into Postman, Insomnia or Stoplight and every endpoint, parameter and response shape appears ready to call. Feed it to openapi-generator for typed clients in PHP, Python or TypeScript. A reference copy exported from v3.0.3 is committed in the examples repo if you want to inspect it before installing anything.

MCP: letting AI agents work the CRM

The part we get the most questions about. v3.0 added a native Model Context Protocol (MCP) server at POST /api/mcp (JSON-RPC 2.0). It exposes 148 CRM tools - create invoice, update lead, search customers, log a payment - to Claude Desktop, Cursor, n8n AI Agent nodes and any other MCP client.

The important design decision: tools are permission-filtered. The MCP server only exposes the operations the API token is allowed to perform, so an agent connected with a read-only token physically cannot write to the CRM. Setup for specific clients is documented in the repo's MCP guide.

If you use n8n, there is also a dedicated community node package: n8n-nodes-perfex-crm.

The numbers, in one place

What	Figure
REST surface	72 paths, 139 operations (OpenAPI 3.0)
Webhooks	124 events, HMAC-signed, async with retries
MCP tools for AI agents	148, permission-filtered
Batch	up to 50 operations per request
Automation	native n8n, Zapier, Make polling endpoints
Track record	4.91/5 from 44 verified CodeCanyon reviews, 2,941 sales