Perfex CRM REST API Documentation

Welcome to the Tech9Pros REST API documentation for Perfex CRM. This guide provides a complete overview of available endpoints, authentication, request/response formats, and error handling. Each module of Perfex CRM is represented here with examples that have been rewritten with original content and fresh data values.

Use the sidebar to jump to sections such as Leads, Customers, Invoices, Projects, Tickets, and more. All examples use JSON over HTTP and assume that you include your API token in the Authtoken header.

All requests require a valid token generated from your Perfex CRM instance. Include this token in the request headers.

curl -X GET https://your-crm.example.com/api/me \
  -H "Authtoken: YOUR_TOKEN"

Requests are sent using standard HTTP verbs: GET, POST, PUT, DELETE. Pagination is available via ?page and ?per_page. Filtering and sorting are supported with query parameters.

Errors are returned with conventional HTTP status codes. A 200-range indicates success, 400-range indicates client issues, and 500-range indicates server errors.

Status	Meaning
400	Bad Request – Check input fields
401	Unauthorized – Missing or invalid token
403	Forbidden – Token lacks permission
404	Not Found – Resource not found

Manage sales opportunities captured from forms, ads, imports, or manual entry.

List Leads

GET /api/leads?page=1&per_page=2&status=new&q=website
# 200 OK
{
  "data": [
    {
      "id": 9101,
      "first_name": "Reem",
      "last_name": "Safar",
      "email": "reem.safar@orbit-labs.io",
      "phone": "+971 52 111 2205",
      "company": "Orbit Labs",
      "status": "new",
      "source": "website",
      "created_at": "2025-08-19T07:22:01Z"
    },
    {
      "id": 9099,
      "first_name": "Jonas",
      "last_name": "Weiss",
      "email": "jonas.weiss@weissware.de",
      "phone": "+49 171 555 0100",
      "company": "Weissware GmbH",
      "status": "contacted",
      "source": "ads",
      "created_at": "2025-08-18T16:59:44Z"
    }
  ],
  "page": 1,
  "per_page": 2,
  "total": 341
}

Create Lead

POST /api/leads
{
  "first_name": "Aisha",
  "last_name": "Nadeem",
  "email": "aisha.nadeem@example.net",
  "phone": "+971 50 777 2020",
  "company": "Helios Marine",
  "status": "new",
  "source": "referral"
}
# 201 Created
{ "id": 9150, "created_at": "2025-08-22T11:10:12Z" }

Update Lead

PUT /api/leads/9150
{ "status": "qualified", "owner_id": 7 }
# 200 OK
{ "id": 9150, "status": "qualified", "owner_id": 7 }

Delete Lead

DELETE /api/leads/9150
# 204 No Content

Companies or individuals you invoice and support. Customers may have multiple contacts.

Create Customer

POST /api/customers
{
  "company": "Zahara Foods LLC",
  "vat": "AE409887654",
  "website": "https://zaharahq.ae",
  "phone": "+971 4 660 1120",
  "country": "AE",
  "address": "Office 1904, JLT",
  "city": "Dubai",
  "zip": "00000"
}
# 201 Created
{ "id": 4021 }

Add Contact

POST /api/customers/4021/contacts
{
  "first_name": "Karim",
  "last_name": "Rahman",
  "email": "karim@zaharahq.ae",
  "phone": "+971 58 330 8841",
  "position": "Operations Manager"
}
# 201 Created
{ "id": 7345 }

Get Customer

GET /api/customers/4021
# 200 OK
{
  "id": 4021,
  "company": "Zahara Foods LLC",
  "contacts": [ { "id": 7345, "first_name": "Karim", "last_name": "Rahman" } ],
  "created_at": "2025-08-16T09:02:44Z"
}

Bill customers for products and services. Invoices can be sent and paid.

Create Draft Invoice

POST /api/invoices
{
  "customer_id": 4021,
  "currency": "AED",
  "issue_date": "2025-08-22",
  "due_date": "2025-09-04",
  "items": [
    { "description": "Onsite Implementation", "qty": 10, "unit_price": 380 },
    { "description": "Monthly Support (Sept)", "qty": 1, "unit_price": 1200 }
  ]
}
# 201 Created
{ "id": 10045, "status": "draft" }

Send Invoice

POST /api/invoices/10045/send
{ "to": ["accounts@zaharahq.ae"], "message": "Please find your invoice attached." }
# 202 Accepted
{ "status": "sent" }

Record Payment

POST /api/invoices/10045/payments
{ "amount": 5000, "paid_at": "2025-08-28", "method": "bank" }
# 201 Created
{ "payment_id": 3051 }

Track actionable work items; can be related to customers or projects.

Create Task

POST /api/tasks
{
  "title": "QA review on estimate",
  "description": "Verify pricing and terms for Zahara Foods",
  "assignee_id": 22,
  "due_date": "2025-08-26",
  "priority": "high",
  "customer_id": 4021
}
# 201 Created { "id": 7050 }

Complete Task

PUT /api/tasks/7050
{ "status": "completed" }
# 200 OK { "id": 7050, "status": "completed", "completed_at": "2025-08-24T13:40:18Z" }

Organize deliverables with tasks, files, and milestones.

Create Project

POST /api/projects
{ "name": "Zahara ERP Rollout", "customer_id": 4021, "start_date": "2025-08-25", "deadline": "2025-10-30", "billing_type": "fixed" }
# 201 Created { "id": 2450 }

Add Project Task

POST /api/projects/2450/tasks
{ "name": "Data migration", "assignee_id": 22, "due_date": "2025-09-05" }
# 201 Created { "id": 7101 }

List Project Files

GET /api/projects/2450/files
# 200 OK
[ { "id": 77, "name": "scope-v2.pdf" } ]

Customer support threads tied to departments and priorities.

Open Ticket

POST /api/tickets
{ "subject": "SLA report not loading", "department_id": 2, "priority": "high", "contact_id": 7345, "message": "Loading spinner persists on /reports" }
# 201 Created { "id": 4609 }

Reply & Close

POST /api/tickets/4609/replies
{ "message": "Issue resolved after cache purge." }
# 201 Created { "reply_id": 133 }

PUT /api/tickets/4609
{ "status": "closed" }
# 200 OK { "id": 4609, "status": "closed" }

Send price quotes that customers can accept/decline.

Create Estimate

POST /api/estimates
{
  "customer_id": 4021,
  "currency": "AED",
  "issue_date": "2025-08-22",
  "expiry_date": "2025-09-12",
  "items": [
    { "description": "Solution Design", "qty": 1, "unit_price": 2400 },
    { "description": "Training (8h)", "qty": 8, "unit_price": 180 }
  ]
}
# 201 Created { "id": 5202, "status": "draft" }

Accept / Decline

POST /api/estimates/5202/accept
# 200 OK { "status": "accepted" }

POST /api/estimates/5202/decline
# 200 OK { "status": "declined" }

Rich, templated offers for leads or customers, with online acceptance.

Create Proposal

POST /api/proposals
{
  "subject": "Implementation Proposal",
  "rel_type": "customer",
  "rel_id": 4021,
  "content": "
Scope
Phase 1 deliverables...
",
  "date": "2025-08-22",
  "open_till": "2025-09-18"
}
# 201 Created { "id": 3301, "status": "draft" }

Send & Accept

POST /api/proposals/3301/send
{ "to": ["karim@zaharahq.ae"], "message": "Please review and sign." }
# 202 Accepted { "status": "sent" }

POST /api/proposals/3301/accept
# 200 OK { "status": "accepted" }

Record operational costs and optionally bill them to projects/customers.

Create Expense

POST /api/expenses
{
  "category_id": 5,
  "date": "2025-08-21",
  "amount": 2350.75,
  "note": "Object storage – August",
  "customer_id": 4021,
  "project_id": 2450,
  "billable": true
}
# 201 Created { "id": 880 }

Internal CRM users with roles and permissions.

List Staff

GET /api/staff?page=1&per_page=25
# 200 OK
{ "data": [ { "id": 22, "firstname": "Sara", "lastname": "Nasr", "role": "admin" } ], "page": 1, "per_page": 25, "total": 8 }

Upload files and attach them to projects, customers, tickets, etc.

Upload File

POST /api/files
FormData {
  file: scope-v2.pdf,
  rel_type: "project",
  rel_id: 2450,
  visible_to_customer: true
}
# 201 Created { "id": 77, "name": "scope-v2.pdf" }

Lightweight annotations attached to various entities.

Create & Delete

POST /api/notes
{ "rel_type": "customer", "rel_id": 4021, "description": "Send statements on the 1st business day." }
# 201 Created { "id": 345 }

DELETE /api/notes/345
# 204 No Content

Receive callbacks when events occur.

POST /api/webhooks
{ "url":"https://hooks.tech9pros.dev/perfex","events":["lead.created","invoice.paid"] }

• 1.0 – Initial version with all core modules.

Manage sales opportunities. You can list, create, update, and delete leads.

List Leads

GET /api/leads?page=1&per_page=25
# Response 200
{ "data": [ { "id":8421, "first_name":"Lina", "email":"lina@demo.com" } ], "total": 50 }

Create Lead

POST /api/leads
{ "first_name":"Hana","last_name":"Al Marri","email":"hana@example.net","phone":"+971 50 889 1123" }
# 201 Created
{ "id":8455, "created_at":"2025-08-22T09:41:01Z" }

Update Lead

PUT /api/leads/8455
{ "status":"qualified" }
# 200 { "id":8455, "status":"qualified" }

Delete Lead

DELETE /api/leads/8455
# 204 No Content

Customers are companies or individuals. Each can have multiple contacts.

Create Customer

POST /api/customers
{ "company":"Blue Harbor Trading","website":"https://blueharbor.trade" }
# 201 { "id":3902 }

Add Contact

POST /api/customers/3902/contacts
{ "first_name":"Omar","email":"omar.haddad@blueharbor.trade" }
# 201 { "id":7120 }

Get Customer

GET /api/customers/3902
# 200 { "id":3902, "company":"Blue Harbor Trading" }

Create and manage invoices for customers.

Create Invoice

POST /api/invoices
{ "customer_id":3902, "currency":"AED", "items":[{"description":"Service","qty":2,"unit_price":500}] }
# 201 { "id":9811, "status":"draft" }

Send Invoice

POST /api/invoices/9811/send
{ "to":["billing@blueharbor.trade"], "message":"Your invoice is attached." }
# 202 { "status":"sent" }

Record Payment

POST /api/invoices/9811/payments
{ "amount":1000, "method":"bank" }
# 201 { "payment_id":221 }

Assign tasks to staff and track their completion.

POST /api/tasks
{ "title":"Prepare onboarding deck","assignee_id":22,"due_date":"2025-08-27" }
# 201 { "id":6703 }

PUT /api/tasks/6703
{ "status":"completed" }
# 200 { "id":6703, "status":"completed" }

Projects organize tasks, files, and discussions.

POST /api/projects
{ "name":"Blue Harbor – Rollout","customer_id":3902 }
# 201 { "id":2210 }

GET /api/projects/2210/files
# 200 [ { "id":44, "name":"kickoff-notes.pdf" } ]

Support tickets logged by customers.

POST /api/tickets
{ "subject":"Portal access issue","contact_id":7120 }
# 201 { "id":4401 }

POST /api/tickets/4401/replies
{ "message":"Issue resolved." }
# 201 { "reply_id":119 }

Provide price estimates to customers.

POST /api/estimates
{ "customer_id":3902,"items":[{"description":"Consulting","qty":5,"unit_price":200}] }
# 201 { "id":5107, "status":"draft" }

POST /api/estimates/5107/accept
# 200 { "status":"accepted" }

Send proposals to leads or customers.

POST /api/proposals
{ "subject":"Implementation Proposal","rel_type":"customer","rel_id":3902 }
# 201 { "id":3115, "status":"draft" }

POST /api/proposals/3115/send
{ "to":["omar.haddad@blueharbor.trade"] }
# 202 { "status":"sent" }

Track expenses and optionally mark them billable.

POST /api/expenses
{ "category_id":5, "amount":2350.75, "note":"Cloud hosting – August" }
# 201 { "id":802 }

Manage staff accounts.

GET /api/staff
# 200 { "data": [ { "id":22, "firstname":"Sara" } ] }

Upload files and link them to entities.

POST /api/files
FormData { file: kickoff.pdf, rel_type:"project", rel_id:2210 }
# 201 { "id":44, "name":"kickoff.pdf" }

Freeform notes linked to entities.

POST /api/notes
{ "rel_type":"customer", "rel_id":3902, "description":"Prefers invoices on the 1st" }
# 201 { "id":301 }

DELETE /api/notes/301
# 204 No Content

Get notified of system events.

POST /api/webhooks
{ "url":"https://hooks.tech9pros.dev/perfex", "events":["lead.created","invoice.paid"] }
# 201 { "id":91 }

• 1.1 – Added examples for all modules.