Leads API

Leads represent prospective buyers in BrokerOS. All sales, pre-sales, and site visit workflows originate from lead records.

BASE URL: /api/leads

Endpoints Summary

Method	Path	Description	Access
`GET`	`/api/leads`	List leads with filtering and pagination	Authenticated
`POST`	`/api/leads`	Create a single new lead	Authenticated
`POST`	`/api/leads/bulk-create`	Bulk import an array of leads	Authenticated
`POST`	`/api/leads/assign`	Bulk assign leads to an executive or round-robin	Authenticated
`GET`	`/api/leads/employee/:employeeId`	Get all leads assigned to a specific employee	Authenticated
`GET`	`/api/leads/:id`	Fetch full details, history, and activities of a lead	Authenticated
`PATCH`	`/api/leads/:id`	Update lead profile fields	Authenticated
`PATCH`	`/api/leads/:id/status`	Transition lead status and sub-status	Authenticated
`POST`	`/api/leads/:id/avatar`	Upload customer avatar image	Authenticated
`GET`	`/api/leads/:id/avatar-image`	Stream customer avatar image from storage	Public

List Leads

GET /api/leads

Retrieves leads scoped to the current user’s role and assigned permissions. Managers automatically see their team’s leads, while sales executives only see leads assigned to them.

Query Parameters

Parameter	Type	Required	Description
`status`	`string`	No	Filter by `LeadStatus` (`NEW`, `CONTACTED`, `SITE_VISIT_SCHEDULED`, `NEGOTIATION`, `BOOKED`, `LOST`, `ON_HOLD`, etc.)
`isCpProject`	`boolean`	No	When `true`, filters CP partner leads; `false` filters internal brokerage leads
`followUpDate`	`string`	No	ISO date string (`YYYY-MM-DD`) to fetch leads due for follow-up
`siteVisitDate`	`string`	No	ISO date string (`YYYY-MM-DD`) to fetch leads with site visits scheduled
`scoreRange`	`string`	No	AI score range filter, e.g. `80-100`
`managerUnassigned`	`boolean`	No	When `true`, returns leads needing assignment by a manager
`assignedToId`	`string`	No	Filter leads assigned to a specific user ID

Response Example

[
  {
    "id": "cm123lead001",
    "firstName": "Rahul",
    "lastName": "Sharma",
    "phone": "+919876543210",
    "email": "rahul.sharma@example.com",
    "status": "CONTACTED",
    "subStatus": "Callback requested tomorrow",
    "temperature": "HOT",
    "score": 85,
    "budget": 12500000,
    "preferredLocation": "Whitefield, Bengaluru",
    "interestedProjectId": "cm123proj001",
    "assignedUserId": "cm123user002",
    "sourceId": "cm123src001",
    "isCpProject": false,
    "createdAt": "2026-09-28T09:30:00.000Z",
    "updatedAt": "2026-09-29T14:15:00.000Z"
  }
]

Create Lead

POST /api/leads

Creates a new lead. If an assigned user is not specified, managers will see it in their unassigned queue.

Request Body

Field	Type	Required	Description
`firstName`	`string`	Yes	Lead first name
`phone`	`string`	Yes	Phone number with country code (e.g. `+919876543210`)
`lastName`	`string`	No	Lead last name
`email`	`string`	No	Valid email address
`budget`	`number`	No	Target purchase budget in local currency units
`preferredLocation`	`string`	No	Preferred locality or neighborhood
`interestedProjectId`	`string`	No	UUID of the project of interest
`interestedTowerId`	`string`	No	Specific tower UUID
`interestedUnitId`	`string`	No	Specific unit UUID
`temperature`	`string`	No	`HOT`, `WARM`, or `COLD`
`requirements`	`string`	No	Notes on unit type, floor preference, facing, etc.
`sourceId`	`string`	No	Lead source ID from `/sources`
`brokerId`	`string`	No	Broker ID if submitted via Channel Partner network
`assignedUserId`	`string`	No	User ID to assign immediately

Request Example

{
  "firstName": "Priya",
  "lastName": "Patel",
  "phone": "+919812345678",
  "email": "priya.patel@example.com",
  "budget": 15000000,
  "preferredLocation": "Sarjapur Road",
  "interestedProjectId": "cm123proj001",
  "temperature": "HOT",
  "requirements": "Looking for 3BHK East facing above 10th floor"
}

Bulk Create Leads

POST /api/leads/bulk-create

Import multiple leads in a single batch. Ideal for CSV imports and lead syndication integrations.

Request Body

{
  "leads": [
    {
      "firstName": "Amit",
      "lastName": "Kumar",
      "phone": "+919822233441",
      "email": "amit.k@example.com",
      "budget": 8500000,
      "interestedProjectId": "cm123proj001"
    },
    {
      "firstName": "Sneha",
      "lastName": "Reddy",
      "phone": "+919822233442",
      "email": "sneha.r@example.com",
      "budget": 9500000,
      "interestedProjectId": "cm123proj001"
    }
  ]
}

Assign Leads

POST /api/leads/assign

Reassigns one or more leads to an executive, or distributes them evenly across available executives using round-robin.

Request Body

Field	Type	Required	Description
`leadIds`	`string[]`	Yes	Array of lead IDs to reassign
`targetUserId`	`string`	No	Specific executive ID to receive all leads
`roundRobin`	`boolean`	No	If `true`, splits `leadIds` evenly across active team members

Request Example

{
  "leadIds": ["cm123lead001", "cm123lead002", "cm123lead003"],
  "roundRobin": true
}

Get Single Lead

GET /api/leads/:id

Returns full lead profile, including recent call logs, site visits, follow-up schedule, and negotiation history.

Update Lead Status

PATCH /api/leads/:id/status

Transitions the lead status along the sales pipeline. Emits real-time notification events to assigned managers.

Request Body

{
  "status": "SITE_VISIT_SCHEDULED",
  "subStatus": "Confirmed for Saturday 11:00 AM with spouse"
}

Valid Lead Statuses

NEW — Ingested, awaiting first contact
CONTACTED — Initial call completed
INTERESTED — Expressed purchase intent
SITE_VISIT_SCHEDULED — Physical or virtual visit booked
SITE_VISIT_COMPLETED — Visit completed and verified
NEGOTIATION — Price discussion in progress
BOOKING_IN_PROGRESS — Token payment or KYC under review
BOOKED — Unit reserved and booking form signed
LOST — Drop-off / not interested
ON_HOLD — Delayed decision (more than 30 days)

Upload Avatar

POST /api/leads/:id/avatar
Content-Type: multipart/form-data

Upload a profile picture or contact card for the lead. The file is securely stored in Vercel Blob storage.

Stream Avatar Image

GET /api/leads/:id/avatar-image

This endpoint is Public and can be embedded directly in <img> tags or mobile image renderers. It securely proxies the underlying private blob storage.

System Architecture

API Reference

Endpoints Summary

List Leads

Query Parameters

Response Example

Create Lead

Request Body

Request Example

Bulk Create Leads

Request Body

Assign Leads

Request Body

Request Example

Get Single Lead

Update Lead Status

Request Body

Valid Lead Statuses

Upload Avatar

Stream Avatar Image

​Endpoints Summary

​List Leads

​Query Parameters

​Response Example

​Create Lead

​Request Body

​Request Example

​Bulk Create Leads

​Request Body

​Assign Leads

​Request Body

​Request Example

​Get Single Lead

​Update Lead Status

​Request Body

​Valid Lead Statuses

​Upload Avatar

​Stream Avatar Image

Endpoints Summary

List Leads

Query Parameters

Response Example

Create Lead

Request Body

Request Example

Bulk Create Leads

Request Body

Assign Leads

Request Body

Request Example

Get Single Lead

Update Lead Status

Request Body

Valid Lead Statuses

Upload Avatar

Stream Avatar Image