Perfex CRM API Integration: A Developer’s Guide (with Full CRUD Implementation)

Perfex CRM is one of the most powerful self-hosted customer relationship management systems built on the CodeIgniter framework. Designed for flexibility, Perfex is popular among small and medium businesses that want to manage clients, leads, projects, and invoices under one platform.

However, developers often need to connect Perfex CRM with other tools like websites, mobile apps, or third-party software. The best way to achieve this is through Perfex CRM API integration, which allows programmatic access to CRM data.

In this guide, we’ll explore how developers can integrate Perfex CRM using REST API, handle CRUD operations, and use real working code examples (PHP & cURL). We’ll also share FAQs, semantic SEO insights, and troubleshooting tips based on authentic resources from the official Perfex documentation and developer community.

 

What Is Perfex CRM API Integration?

The Perfex CRM API allows developers to securely access and manipulate CRM data through HTTP endpoints. Using the API, you can:

• – Create, Read, Update, and Delete (CRUD) records such as Leads, Customers, Projects, and Invoices.
• – Automate workflows (e.g., adding leads from your website contact form directly into Perfex).
• – Connect external dashboards or mobile apps.
• – Integrate Perfex with marketing automation tools like Zapier, Make (Integromat), or n8n.

While Perfex CRM doesn’t include a public REST API by default, you can enable it by installing the REST API or GraphQL module, available from the Perfex marketplace or third-party developers.

Prerequisites for API Integration

Before starting development, ensure you have the following:

• – A running instance of Perfex CRM (self-hosted or on VPS).
• – REST API or GraphQL module installed and activated from Setup → Modules.
• – A generated API token (Authentication key).
• – Basic understanding of JSON, PHP (or Node/Python), and HTTP requests.
• – HTTPS-enabled domain for secure API communication.

Enabling the API

1. Go to your Perfex Admin Panel → Setup → Modules.
2. Install and activate the REST API module.
3. Navigate to the API Manager section and generate an API token.
4. Assign scopes (permissions) — e.g., leads, clients, invoices.
5. Test the endpoint in Postman:

GET https://yourdomain.com/api/leads
Headers:
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

If you receive a response, your API is working successfully.

4. Understanding Authentication

Perfex API typically uses Bearer Token Authentication. Each request must include the following header:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Some older modules may require:

Authtoken: YOUR_API_TOKEN

Pro Tip: Always use HTTPS and keep your token secure. Create separate tokens for different integrations.

 

CRUD Operations Table (Create, Read, Update, Delete)

Here’s a quick reference table for API endpoints used in CRUD operations for Leads (you can replace “leads” with “customers” or other modules):

Operation	Method	Endpoint	Description	Example Payload or Params
Create	POST	/api/leads	Create a new lead	{ "name": "John", "email": "john@site.com" }
Read (List)	GET	/api/leads	Fetch list of leads	Optional: ?status=1
Read (One)	GET	/api/leads/{id}	Get specific lead by ID	Replace {id} with numeric ID
Update	PUT	/api/leads/{id}	Update existing lead data	{ "status": 2 }
Delete	DELETE	/api/leads/{id}	Delete a lead	Requires lead ID

CRUD Implementation (With Code Examples)

Below are working examples using PHP (cURL) — the most common environment for Perfex CRM developers.

1. Create a Lead

<?php
$token = 'YOUR_API_TOKEN';
$url = 'https://yourdomain.com/api/leads';

$data = [
    "name" => "Jane Doe",
    "email" => "jane@example.com",
    "phonenumber" => "03001234567",
    "source" => 1,
    "status" => 1,
    "assigned" => 2
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

2. Read (List All Leads)

<?php
$token = 'YOUR_API_TOKEN';
$url = 'https://yourdomain.com/api/leads';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

3. Read (Single Lead)

<?php
$leadId = 123;
$token = 'YOUR_API_TOKEN';
$url = "https://yourdomain.com/api/leads/{$leadId}";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

4. Update a Lead

<?php
$leadId = 123;
$token = 'YOUR_API_TOKEN';
$url = "https://yourdomain.com/api/leads/{$leadId}";

$data = ["status" => 2, "phonenumber" => "03007654321"];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

5. Delete a Lead

<?php
$leadId = 123;
$token = 'YOUR_API_TOKEN';
$url = "https://yourdomain.com/api/leads/{$leadId}";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Error Handling & Debugging

Common API issues developers face:

Error Message	Cause	Solution
406 Not Acceptable	Wrong headers	Always use Content-Type: application/json
Invalid Token	Expired or incorrect token	Regenerate from API Manager
Data Not Provided	Missing required fields	Check API documentation for field requirements
Lead Created but Not Visible	Role or permission issue	Ensure assigned user or admin view

Use tools like Postman or Insomnia to debug API requests before implementing in your codebase.

Best practices & architecture patterns

• Retry & idempotency: Use idempotency keys if your module supports them or implement dedupe at your side to avoid duplicate leads on retries.
• Rate limiting: Modules may not enforce limits—implement exponential backoff on client side.
• Sync vs. push: For bi-directional sync, prefer pushing changes from the source system into Perfex and use scheduled pulls for reconciliation.
• Webhook alternative: If available, prefer webhooks for near-real-time updates; otherwise poll with reasonable intervals.

Developer Best Practices

• Security: Always use HTTPS and store tokens in environment variables.
• Idempotency: Prevent duplicate entries by validating data before sending POST requests.
• Pagination: Use query params (?page=2) for large data requests.
• Automation: Combine API calls with cron jobs or webhooks for real-time updates.
• Testing: Validate all CRUD actions on a staging environment first.

Integrations & tools

Many automation platforms (n8n, Zapier/Make) can call Perfex REST endpoints—treat them as generic HTTP actions and replicate the headers/body described above. Community threads show users integrating via HTTP modules.

FAQs About Perfex CRM API Integration: