Partners CRM — API

All endpoints require a valid token_admin JWT. Most CRM endpoints additionally require the named permission crm-partners. Locale filtering is applied automatically based on the authenticated admin's locale assignment.

Endpoint Summary

Method	Path	Auth	Description
GET	/partner/grouped	crm-partners	Kanban view — partners and prospects grouped by pipeline column
GET	/partner/list	crm-partners	Paginated list of partners and prospects
GET	/partner/kpis	crm-partners	Revenue KPI totals per pipeline column
GET	/partner/activities	crm-partners	Calendar events (scheduled follow-ups, UNION of both entity types)
GET	/partner/autocomplete	token_admin	Partner search for autocomplete inputs
GET	/partner/{id}/details	crm-partners	Full detail for a registered partner
POST	/partner/{id}/notes	crm-partners	Create a follow-up note for a registered partner
POST	/partner/{id}/contacts	crm-partners	Add an extra contact to a registered partner
PATCH	/partner/{id}/data	crm-partners	Upsert CRM metadata for a registered partner
POST	/partner/prospect	crm-partners	Create a new partner prospect (type 3)
GET	/prospects/{id}	perm 319	Partner prospect detail (pass source=partner)
POST	/prospects/{id}/notes	perm 319	Create a follow-up note for a partner prospect
PATCH	/prospects/{id}/partner-data	crm-partners	Upsert CRM metadata for a partner prospect

---

GET /partner/grouped

Returns partners and partner prospects grouped into Kanban columns.

Query Parameters

Parameter	Type	Default	Description
start	number	0	Pagination offset (per column)
length	number	20	Page size per column
sortBy	string	—	Sort field
sortType	string	—	ASC or DESC
localeId	any	—	Filter by country locale
report	boolean	—	Include report-level data
counters	boolean	—	Include total counts per column
category	number	—	Filter to a specific pipeline column ID
startDate	string	—	Filter by creation date range start (ISO)
endDate	string	—	Filter by creation date range end (ISO)
source	string	partner	company or partner; always partner for this CRM
follow	string	—	Follow-up status filter
type	string	—	Entity type filter (partner or prospect)
search	string	—	Full-text search (name, email, company)
referrals	boolean	—	Filter to partners with at least one referral

Response

{
  "data": [
    {
      "id": 1,
      "name": "Pipeline Stage Name",
      "order": 1,
      "items": [
        {
          "id": 42,
          "type": "partner",
          "name": "Acme Corp",
          "email": "contact@acme.com",
          "follow_up_id": 1,
          "referrals": 12,
          "revenue": 4500.00
        }
      ],
      "total": 8
    }
  ]
}

---

GET /partner/list

Returns a flat paginated list of partners and partner prospects for the List (table) view.

Query Parameters

Same as /partner/grouped, plus:

Parameter	Type	Description
length	number	Default 100
'createdAt[0]'	string	Creation date range start
'createdAt[1]'	string	Creation date range end
campaing	string	Campaign filter
salesman	string	Assigned salesman filter
status	number	Partner status (0 = removed, 1 = active, 2 = registered)
admin	number	Assigned administrator filter

Response

{
  "data": [
    {
      "id": 42,
      "type": "partner",
      "name": "Acme Corp",
      "email": "contact@acme.com",
      "phone": "+1 555-0100",
      "follow_up_id": 1,
      "follow_up_name": "Active",
      "referrals": 12,
      "revenue": 4500.00,
      "status": 1,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 120
}

---

GET /partner/kpis

Returns total referral revenue per pipeline column. Used by the Kanban view to show USD revenue badges at the top of each column.

Query Parameters

Same as /partner/grouped (same filters apply so KPIs reflect current view state).

Response

{
  "data": [
    {
      "follow_up_id": 1,
      "follow_up_name": "Active",
      "total_revenue": 18500.00
    }
  ]
}

---

GET /partner/activities

Returns scheduled follow-up events for the Calendar view. The result is a UNION of activities for registered partners and partner prospects that have a scheduled_date.

Query Parameters

Parameter	Type	Description
startDate	string	Calendar range start (ISO)
endDate	string	Calendar range end (ISO)
activityFilter	string	overdue, upcoming, today, or month
search	string	Name/email search
follow	string	Pipeline column filter
type	string	partner or prospect
salesman	string	Filter by assigned salesman
localeId	any	Locale filter
start	number	Pagination offset
length	number	Page size

Response

{
  "data": [
    {
      "id": 7,
      "type": "partner",
      "entity_id": 42,
      "name": "Acme Corp",
      "action": "call",
      "note": "Quarterly check-in",
      "scheduled_date": "2024-06-10T14:00:00Z",
      "follow_up_name": "Active"
    }
  ],
  "total": 14
}

---

GET /partner/autocomplete

Lightweight partner search for select inputs (e.g., filtering by partner in other modules).

Query Parameters

Parameter	Type	Description
search	string	Partial name or email

Response

{
  "data": [
    { "id": 42, "name": "Acme Corp", "email": "contact@acme.com" }
  ]
}

---

GET /partner/{id}/details

Returns the full detail payload for a registered partner, including notes and extra contacts.

Path Parameters

Parameter	Type	Description
id	number	Partner ID

Response

{
  "partner": {
    "id": 42,
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "phone": "+1 555-0100",
    "follow_up_id": 1,
    "follow_up_name": "Active",
    "url": "https://acme.com",
    "partner_type_id": 2,
    "partner_origin_id": 1,
    "rating": 4,
    "locale_id": 1,
    "social_network": "@acmecorp",
    "referrals": 12,
    "revenue": 4500.00,
    "admin_name": "Jane Doe",
    "support_name": "John Smith"
  },
  "notes": [
    {
      "id": 100,
      "comment": "Discussed new referral targets",
      "action": "call",
      "follow_up_name": "Active",
      "scheduled_date": null,
      "created_at": "2024-05-20T09:30:00Z",
      "created_by_name": "Jane Doe"
    }
  ],
  "contacts": [
    {
      "id": 5,
      "name": "Bob Jones",
      "email": "bob@acme.com",
      "phone_code": "+1",
      "phone": "555-0101",
      "position": "Marketing Manager"
    }
  ]
}

---

POST /partner/{id}/notes

Creates a follow-up note for a registered partner. Also updates partners.follow_up_id if follow is provided.

Path Parameters

Parameter	Type	Description
id	number	Partner ID (maps to company_id in follow_up_comments)

Request Body

{
  "follow": 2,
  "action": "call",
  "note": "Reviewed Q2 referral performance. Moving to Active.",
  "scheduled_date": "2024-06-15T10:00:00Z"
}

Field	Type	Required	Description
follow	number	No	Target pipeline column ID (updates follow_up_id)
action	string	No	call, whatsapp, email, meeting, sms, other
note	string	Yes	Note text
scheduled_date	ISO datetime	No	Schedule a follow-up date

Response

{ "success": true }

---

POST /partner/{id}/contacts

Adds an extra contact to a registered partner. Stored in extra_contacts keyed by company_id.

Path Parameters

Parameter	Type	Description
id	number	Partner ID

Request Body

{
  "name": "Alice Lee",
  "email": "alice@acme.com",
  "phone_code": "+1",
  "phone": "555-0102",
  "position": "CEO"
}

Field	Type	Required
name	string	Yes
email	string	Yes
phone_code	string	Yes
phone	string	Yes
position	string	No

Response

{ "success": true, "id": 6 }

---

PATCH /partner/{id}/data

Upserts partner_follow_up_data for a registered partner (model = 'partner', model_id = {id}).

Path Parameters

Parameter	Type	Description
id	number	Partner ID

Request Body

{
  "url": "https://acme.com",
  "partner_type_id": 2,
  "partner_origin_id": 1,
  "rating": 4,
  "locale_id": 1,
  "social_network": "@acmecorp"
}

Field	Type	Required	Constraints
url	string	Yes	—
partner_type_id	number	Yes	FK to catalog_partner_types
partner_origin_id	number	Yes	FK to catalog_partner_origins
rating	number (int)	Yes	1–5
locale_id	number	Yes	FK to locales
social_network	string	No	Max 150 chars

Response

{ "success": true }

---

POST /partner/prospect

Creates a new partner prospect (prospection_users with type = 3, company_id = NULL). Also inserts an initial follow-up record with source = 'partner'.

Request Body

{
  "name": "Maria Garcia",
  "company": "Garcia Logistics",
  "email": "maria@garcia-logistics.com",
  "phone": "5550100",
  "code": "+52",
  "locale": 3
}

Field	Type	Required	Description
name	string	Yes	Contact person name
company	string	Yes	Company/organization name
email	string (email)	Yes	Primary email
phone	string	Yes	Phone number
code	string	Yes	Country phone code (e.g. +52)
locale	number	Yes	Locale/country ID
type	number	No	Partner sub-type

Response

{ "success": true, "id": 77, "token": "<jwt>" }

Error Codes

Code	Description
422	Duplicate email already exists as a partner prospect

---

GET /prospects/{id}

Returns detail for a partner prospect. Shared with the main CRM; pass source=partner to signal the Partners CRM context.

Query Parameters

Parameter	Value
source	partner

Auth: Permission 319 (base CRM access).

Response: Same structure as the main CRM prospect detail. Includes prospection_users fields, notes from prospect_follow_up_comments, and extra_contacts.

---

POST /prospects/{id}/notes

Creates a follow-up note for a partner prospect. Stored in prospect_follow_up_comments. Also updates prospection_users.follow_up_id.

Auth: Permission 319.

Request Body: Same schema as POST /partner/{id}/notes.

---

PATCH /prospects/{id}/partner-data

Upserts partner_follow_up_data for a partner prospect (model = 'prospect', model_id = {id}).

Auth: crm-partners.

Request Body: Same schema as PATCH /partner/{id}/data.

---

Catalog Endpoints

These catalog endpoints are used by the Partners CRM UI to populate dropdowns and Kanban columns.

Method	Path	Description
GET	/catalog/tours?type=partner	Follow-up status categories (source = 'partner') for Kanban columns
GET	/catalog/partners/types	Partner type options for the Details form
GET	/catalog/partners/origins	Partner origin/channel options for the Details form

---

Error Codes

HTTP Status	Description
400	Missing or invalid required fields
401	Missing or expired token_admin JWT
403	Admin lacks the required permission (crm-partners or 319)
422	Business rule violation (e.g., duplicate email on prospect creation)
500	Internal server error