{
  "markdown": "<p>\n  <a href=\"https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/\">\n    <img src=\"assets/perfex-crm-rest-api.jpg\" alt=\"REST API for Perfex CRM — connect Perfex CRM with AI agents, Zapier, WooCommerce, n8n and third-party apps\">\n  </a>\n</p>\n\n# Perfex CRM REST API — Examples, Postman Collection & Code Snippets\n\n🌐 **English** · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [Português (BR)](README.pt-BR.md) · [Italiano](README.it.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Türkçe](README.tr.md) · [Tiếng Việt](README.vi.md) · [ไทย](README.th.md) · [العربية](README.ar.md)\n\n> Ready-to-use **Postman collection**, **code snippets** (cURL, PHP, Python, JavaScript) and a resource\n> **catalogue** for the [REST API module for Perfex CRM](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/) —\n> the fastest way to **connect Perfex CRM with AI agents and third-party applications**.\n\n[![Postman](https://img.shields.io/badge/Postman-Collection-orange?logo=postman&logoColor=white)](postman/perfex-rest-api.postman_collection.json)\n[![OpenAPI 3.0](https://img.shields.io/badge/OpenAPI-3.0-6ba539?logo=openapiinitiative&logoColor=white)](openapi/perfex-rest-api.openapi.json)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Perfex CRM](https://img.shields.io/badge/Perfex%20CRM-REST%20API-2c7be5)](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/)\n\nThe **Perfex CRM REST API** lets you read and write customers, leads, invoices, estimates, projects,\ntasks and more over a clean HTTP/JSON interface — perfect for **CRM integration**, automation and custom\napps. **v3.0** adds an **MCP server for AI agents**, production-grade **webhooks**, ready-made **Zapier /\nMake / n8n** polling, **batch** operations and smarter list endpoints. This repository is the practical\ncompanion to the\n**[REST API for Perfex CRM](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/)**\nmodule by **Themesic Interactive**: copy-paste examples, an importable Postman collection, and a full\nendpoint catalogue.\n\n- 🧩 **Get the module:** https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/\n\n- 📖 **API guide / live docs:** https://perfexcrm.themesic.com/apiguide/\n- 🧾 **OpenAPI 3.0 spec:** `GET https://yourdomain.com/api/openapi` ([reference copy](openapi/perfex-rest-api.openapi.json))\n\n---\n\n## 🚀 What's new in v3.0\n\n| Feature | Endpoint | What it does |\n| --- | --- | --- |\n| 🤖 **MCP server** | `POST /api/mcp` | Model Context Protocol (JSON-RPC 2.0) — exposes **148 permission-filtered CRM tools** to Claude Desktop, ChatGPT, Cursor, n8n AI Agent and any MCP client |\n| 🪝 **Webhooks 2.0** | `/api/webhooks` | **124 events**, REST management, async delivery with retries, SSRF protection, **HMAC-signed** requests |\n| 🔌 **Automation (polling)** | `/api/zapier/*` | Ready-made polling triggers for **Zapier, Make.com, n8n** and any polling-based tool |\n| ⚡ **Batch** | `POST /api/batch` | Up to **50 operations** in one request (same tool names as MCP) |\n| 📚 **Knowledge Base** | `/api/knowledge_base` | Articles + groups CRUD |\n| 🗒️ **Notes** | `/api/notes` | Polymorphic notes across 12 entity types |\n| 📄 **Smarter lists** | any list endpoint | Opt-in `?page=&per_page=`, `?fields=`, `?sort=`, `?created_after=&created_before=` |\n| 🛡️ **Safe writes** | any `POST` | `Idempotency-Key` replay, ignored-unknown-fields on `PUT`, `X-RateLimit-*` headers |\n| 📐 **OpenAPI 3.0 spec** | `GET /api/openapi` | The whole surface as one machine-readable document - **74 paths, 144 operations** - import into Postman, Insomnia or Stoplight in seconds ([reference copy in `openapi/`](openapi/)) |\n\n> Everything is **opt-in** and backwards-compatible: requests without the new parameters return the exact\n> same response as before.\n\n---\n\n## Contents\n\n| Folder | What's inside |\n| --- | --- |\n| [`postman/`](postman/) | Importable Postman **collection** + **environment** (`{{base_url}}`, `{{authtoken}}`) — now with MCP, Webhooks, Batch, Automation, Knowledge Base & Notes |\n| [`snippets/curl/`](snippets/curl/) | Copy-paste `curl` commands for the most common calls |\n| [`snippets/php/`](snippets/php/) | PHP (cURL) examples |\n| [`snippets/python/`](snippets/python/) | Python (`requests`) examples |\n| [`snippets/javascript/`](snippets/javascript/) | JavaScript / Node (`fetch`) examples |\n| [`docs/`](docs/) | Authentication, pagination & filtering, webhooks, MCP, automation, custom tables, errors & status codes |\n\nEach snippet language has examples for **customers, invoices, leads** plus the v3 features\n**webhooks, mcp, batch, automation, knowledge_base and notes**, and a **list_features** file showing\npagination, field selection and sorting.\n\n---\n\n## Quick start\n\nEvery request to the Perfex CRM REST API is authenticated with the **`Authtoken`** header. Create a token\nin your Perfex admin under **API → API Management** (after activating the\n[REST API module](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/)),\nthen call the API at `https://yourdomain.com/api/...`:\n\n```bash\ncurl -H \"authtoken: YOUR_API_TOKEN\" https://yourdomain.com/api/customers\n```\n\nThat returns the list of customers as JSON. See [`docs/authentication.md`](docs/authentication.md) for\nheader vs. query-parameter auth, and [`snippets/`](snippets/) for the same call in PHP, Python and JavaScript.\n\n### Use the Postman collection\n\n1. Open Postman → **Import** → drop in [`postman/perfex-rest-api.postman_collection.json`](postman/perfex-rest-api.postman_collection.json).\n2. Import the environment [`postman/perfex-rest-api.postman_environment.json`](postman/perfex-rest-api.postman_environment.json).\n3. Set `base_url` to `https://yourdomain.com/api` and `authtoken` to your token.\n4. Pick any request and hit **Send**.\n\n### Connect an AI agent (MCP)\n\nPoint any MCP client (Claude Desktop, Cursor, ChatGPT, n8n AI Agent) at `POST https://yourdomain.com/api/mcp`\nand send your `authtoken` header. The server advertises permission-filtered tools for your CRM. See\n[`docs/mcp.md`](docs/mcp.md) and [`snippets/curl/mcp.sh`](snippets/curl/mcp.sh).\n\n---\n\n## Endpoint catalogue\n\nAll CRUD endpoints follow a RESTful convention: `GET` list, `GET /:id` single, `POST` create,\n`PUT /:id` update, `DELETE /:id` delete — under the base path `https://yourdomain.com/api`.\n\n### Core CRM resources\n\n| Resource | Base path | Typical operations |\n| --- | --- | --- |\n| Customers | `/api/customers` | list, get, create, update, delete |\n| Contacts | `/api/contacts` | list, get, create, update, delete |\n| Leads | `/api/leads` | list, get, create, update, delete |\n| Invoices | `/api/invoices` | list, get, create, update, delete |\n| Estimates | `/api/estimates` | list, get, create, update, delete |\n| Credit Notes | `/api/credit_notes` | list, get, create, update |\n| Payments | `/api/payments` | list, get, create |\n| Proposals | `/api/proposals` | list, get, create, update, delete |\n| Contracts | `/api/contracts` | list, get, create, update, delete |\n| Projects | `/api/projects` | list, get, create, update, delete |\n| Tasks | `/api/tasks` | list, get, create, update, delete |\n| Milestones | `/api/milestones` | list, get, create, update, delete |\n| Timesheets | `/api/timesheets` | list, get, create, update, delete |\n| Subscriptions | `/api/subscriptions` | list, get, create, update |\n| Items | `/api/items` | list, get, create, update, delete |\n| Expenses | `/api/expenses` | list, get, create, update, delete |\n| Staff | `/api/staffs` | list, get, create, update, delete |\n| Calendar | `/api/calendar` | list, get, create, update, delete |\n| Custom Fields | `/api/custom_fields` | list per related type |\n| Common (lookups) | `/api/common` | countries, taxes, currencies, statuses … |\n\n### v3 platform & extra resources\n\n| Resource | Base path | Typical operations |\n| --- | --- | --- |\n| **MCP server** | `/api/mcp` | `POST` JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call` |\n| **Batch** | `/api/batch` | `POST` up to 50 operations in one request |\n| **Webhooks** | `/api/webhooks` | list, get, create, update, delete, `POST /:id/toggle`, `GET /events`, `GET /:id/logs` |\n| **Automation (polling)** | `/api/zapier` | `GET /resources`, `GET /poll/:resource`, `GET /test/:resource` |\n| **Knowledge Base** | `/api/knowledge_base` | list, get, create, update, delete; `/groups` |\n| **Notes** | `/api/notes` | list by `:rel_type/:rel_id`, get, create, update, delete |\n\n> The exact request fields per resource are documented in the official\n> **[API guide](https://perfexcrm.themesic.com/apiguide/)**. The snippets here cover the most common flows.\n\n---\n\n## Smarter list endpoints (v3)\n\nEvery list endpoint accepts optional query parameters. Add them and you get a `{ data, meta }` envelope;\nomit them and you get the exact legacy array.\n\n```bash\n# Page 2, 20 per page, only id + company, newest first, created this year\ncurl -H \"authtoken: YOUR_API_TOKEN\" \\\n  \"https://yourdomain.com/api/customers?page=2&per_page=20&fields=id,company&sort=-datecreated&created_after=2026-01-01\"\n```\n\n| Parameter | Example | Effect |\n| --- | --- | --- |\n| `page`, `per_page` | `?page=2&per_page=20` | Pagination → `{ data, meta }` |\n| `fields` | `?fields=id,company` | Return only these columns |\n| `sort` | `?sort=-datecreated,company` | Sort (`-` = descending) |\n| `created_after`, `created_before` | `?created_after=2026-01-01` | Date-range filter |\n\n> `per_page` is the parameter that sizes a page (1-100, default 25). `limit` is accepted as an\n> alias **only** when `page` is sent too, so a bare `?limit=5` does not paginate - use\n> `?page=1&per_page=5`.\n\nSee [`docs/pagination-filtering.md`](docs/pagination-filtering.md) and\n[`snippets/curl/list_features.sh`](snippets/curl/list_features.sh).\n\n---\n\n## Upgrading from 2.x\n\n**There are no breaking changes.** Every v3 list feature is opt-in:\n\n- Send none of the parameters above and you get the same plain array 2.x returned. The\n  `{ data, meta }` envelope appears **only** when you send `page` or `per_page`.\n- **No endpoint was renamed.** Customers have always been at `/api/customers`.\n- Unknown fields on `PUT` are ignored instead of returning an error.\n- `POST` requests accept an optional `Idempotency-Key` header; identical retries replay the stored\n  response rather than creating duplicates.\n\nTwo things worth knowing when adopting v3:\n\n- Custom tables moved behind an allowlist in 3.0.2 - see\n  [`docs/custom-tables.md`](docs/custom-tables.md).\n- New permission rows (Webhooks, Notes, Knowledge Base) must be ticked on existing tokens before\n  those endpoints answer, and before their MCP tools appear in `tools/list`.\n\n---\n\n## Popular integrations & use cases\n\nThe Perfex CRM REST API is commonly used to **connect Perfex CRM with AI agents and third-party applications**:\n\n- **AI assistants (MCP)** — let Claude, ChatGPT or Cursor read and update your CRM through `/api/mcp`.\n- **Zapier / Make / n8n** — no-code automation via ready-made polling triggers (`/api/zapier/*`).\n- **Webhooks** — push Perfex events (new invoice, new lead, 124 events) to Slack, Discord or your own backend, signed with HMAC.\n- **Google Sheets / Power Automate** — sync customers, invoices or payments to spreadsheets and dashboards.\n- **Custom apps & portals** — build a mobile app or customer portal on top of your Perfex data.\n- **Accounting & e-commerce** — sync invoices and items with external billing or shop platforms.\n\nAll of these are powered by the\n[REST API for Perfex CRM](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/) module.\n\n---\n\n## Authentication (summary)\n\n| Method | How |\n| --- | --- |\n| Header (recommended) | `Authtoken: YOUR_API_TOKEN` |\n| Query parameter | `?authtoken=YOUR_API_TOKEN` (handy for quick tests / webhooks) |\n\nTokens are created and scoped (per-resource permissions) in **API → API Management**. Full details in\n[`docs/authentication.md`](docs/authentication.md).\n\n---\n\n## FAQ\n\n**Does Perfex CRM have a REST API?**\nYes. The [REST API for Perfex CRM](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/)\nmodule adds a full RESTful HTTP/JSON API for customers, leads, invoices, estimates, projects, tasks and more,\nplus a v3 **MCP server**, **webhooks**, **batch** and **automation** endpoints.\n\n**Can I use Perfex CRM with AI agents / ChatGPT / Claude?**\nYes — v3 ships an **MCP server** at `POST /api/mcp` that exposes permission-filtered CRM tools to any\nModel Context Protocol client. See [`docs/mcp.md`](docs/mcp.md).\n\n**How do I authenticate with the Perfex CRM API?**\nSend your token in the `Authtoken` HTTP header (or as an `?authtoken=` query parameter). See\n[`docs/authentication.md`](docs/authentication.md).\n\n**What is the base URL of the Perfex CRM API?**\n`https://yourdomain.com/api` — for example `https://yourdomain.com/api/customers`.\n\n**Can I connect Perfex CRM to Zapier, Make or n8n?**\nYes — v3 has ready-made polling triggers under `/api/zapier/*`, plus webhooks. See\n[Popular integrations](#popular-integrations--use-cases) and [`docs/automation.md`](docs/automation.md).\n\n**Is there a Postman collection for Perfex CRM?**\nYes — import [`postman/perfex-rest-api.postman_collection.json`](postman/perfex-rest-api.postman_collection.json)\nand the bundled environment, set your `base_url` and `authtoken`, and start sending requests.\n\n**How do I create an invoice via the Perfex CRM API?**\n`POST https://yourdomain.com/api/invoices` with the invoice fields and an `items[]` array — v3 auto-calculates\n`subtotal`/`total`. See [`snippets/curl/invoices.sh`](snippets/curl/invoices.sh).\n\n---\n\n## About / Support\n\n<img src=\"assets/perfex-crm-rest-api-icon.png\" width=\"64\" alt=\"Perfex CRM REST API icon\">\n\nThis repository is an **examples companion** to the commercial module:\n\n> **[REST API for Perfex CRM — connect your Perfex CRM with third-party applications](https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/)**\n> by [Themesic Interactive](https://themesic.com).\n\n- 🛒 **Buy / learn more:** https://themesic.com/product/rest-api-module-for-perfex-crm-connect-your-perfex-crm-with-third-party-applications/\n- 📖 **Documentation:** https://perfexcrm.themesic.com/apiguide/\n- 💬 **Support:** https://themesic.com/support\n\nContributions of additional examples are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## License\n\nExample code in this repository is released under the [MIT License](LICENSE). \"Perfex\" is a trademark of\nits respective owner; the REST API module is a commercial product by Themesic Interactive.\n",
  "bytes": 14990,
  "sha": "290c73c206fabb8c32781c1d52c4b2ce14c66147454514fb8d12a1d09998ec9f",
  "repo_slug": "themesic/perfex-rest-api-examples",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_themesic_perfex_crm_9e0d2fe2/readme"
}