Perfex CRM

Perfex CRM REST API — Examples, Postman Collection & Code Snippets

🌐 English · 简体中文 · Español · Português (BR) · Italiano · Français · Deutsch · Türkçe · Tiếng Việt · ไทย · العربية

Ready-to-use Postman collection, code snippets (cURL, PHP, Python, JavaScript) and a resource

catalogue for the REST API module for Perfex CRM —

the fastest way to connect Perfex CRM with AI agents and third-party applications.

The Perfex CRM REST API lets you read and write customers, leads, invoices, estimates, projects, tasks and more over a clean HTTP/JSON interface — perfect for CRM integration, automation and custom apps. v3.0 adds an MCP server for AI agents, production-grade webhooks, ready-made Zapier / Make / n8n polling, batch operations and smarter list endpoints. This repository is the practical companion to the [REST API for Perfex CRM](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/) module by Themesic Interactive: copy-paste examples, an importable Postman collection, and a full endpoint catalogue.

• 🧩 Get the module: https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/

• 📖 API guide / live docs: https://perfexcrm.themesic.com/apiguide/
• 🧾 OpenAPI 3.0 spec: GET https://yourdomain.com/api/openapi (reference copy)

---

🚀 What's new in v3.0

Everything is opt-in and backwards-compatible: requests without the new parameters return the exact

same response as before.

---

Contents

Each snippet language has examples for customers, invoices, leads plus the v3 features webhooks, mcp, batch, automation, knowledge_base and notes, and a list_features file showing pagination, field selection and sorting.

---

Quick start

Every request to the Perfex CRM REST API is authenticated with the `Authtoken` header. Create a token in your Perfex admin under API → API Management (after activating the REST API module), then call the API at https://yourdomain.com/api/...:

curl -H "authtoken: YOUR_API_TOKEN" https://yourdomain.com/api/customers

That returns the list of customers as JSON. See docs/authentication.md for header vs. query-parameter auth, and snippets/ for the same call in PHP, Python and JavaScript.

Use the Postman collection

1. Open Postman → Import → drop in postman/perfex-rest-api.postman_collection.json.
2. Import the environment postman/perfex-rest-api.postman_environment.json.
3. Set base_url to https://yourdomain.com/api and authtoken to your token.
4. Pick any request and hit Send.

Connect an AI agent (MCP)

Point any MCP client (Claude Desktop, Cursor, ChatGPT, n8n AI Agent) at POST https://yourdomain.com/api/mcp and send your authtoken header. The server advertises permission-filtered tools for your CRM. See docs/mcp.md and snippets/curl/mcp.sh.

Use with Claude, ChatGPT and other AI assistants

Connect any assistant with one URL, https://perfex-mcp.themesic.com/mcp. Step-by-step setup for Claude, ChatGPT, Cursor and VS Code: docs/connect-ai-assistants.md.

A Claude plugin (connector + skills) for claude.ai, Cowork and Claude Code lives in claude-plugin/. It requires the REST API module with a valid license and the MCP server enabled. See claude-plugin/README.md for setup, permissions and the privacy policy.

---

Endpoint catalogue

All CRUD endpoints follow a RESTful convention: GET list, GET /:id single, POST create, PUT /:id update, DELETE /:id delete — under the base path https://yourdomain.com/api.

Core CRM resources

v3 platform & extra resources

The exact request fields per resource are documented in the official

[API guide](https://perfexcrm.themesic.com/apiguide/). The snippets here cover the most common flows.

---

Smarter list endpoints (v3)

Every list endpoint accepts optional query parameters. Add them and you get a { data, meta } envelope; omit them and you get the exact legacy array.

# Page 2, 20 per page, only id + company, newest first, created this year

curl -H "authtoken: YOUR_API_TOKEN" \ "https://yourdomain.com/api/customers?page=2&per_page=20&fields=id,company&sort=-datecreated&created_after=2026-01-01"

per_page is the parameter that sizes a page (1-100, default 25). limit is accepted as an

alias only when page is sent too, so a bare ?limit=5 does not paginate - use

?page=1&per_page=5.

See docs/pagination-filtering.md and snippets/curl/list_features.sh.

---

Upgrading from 2.x

There are no breaking changes. Every v3 list feature is opt-in:

• Send none of the parameters above and you get the same plain array 2.x returned. The { data, meta } envelope appears only when you send page or per_page.
• No endpoint was renamed. Customers have always been at /api/customers.
• Unknown fields on PUT are ignored instead of returning an error.
• POST requests accept an optional Idempotency-Key header; identical retries replay the stored response rather than creating duplicates.

Two things worth knowing when adopting v3:

• Custom tables moved behind an allowlist in 3.0.2 - see docs/custom-tables.md.
• New permission rows (Webhooks, Notes, Knowledge Base) must be ticked on existing tokens before those endpoints answer, and before their MCP tools appear in tools/list.

---

Popular integrations & use cases

The Perfex CRM REST API is commonly used to connect Perfex CRM with AI agents and third-party applications:

• AI assistants (MCP) — let Claude, ChatGPT or Cursor read and update your CRM through /api/mcp.
• Zapier / Make / n8n — no-code automation via ready-made polling triggers (/api/zapier/*).
• Webhooks — push Perfex events (new invoice, new lead, 124 events) to Slack, Discord or your own backend, signed with