> ## Documentation Index
> Fetch the complete documentation index at: https://brokeros.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Leads API

> Create, query, assign, update, and manage the full lifecycle of CRM leads.

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

```http theme={null}
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

```http theme={null}
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

```json theme={null}
[
  {
    "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

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
POST /api/leads/bulk-create
```

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

### Request Body

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "leadIds": ["cm123lead001", "cm123lead002", "cm123lead003"],
  "roundRobin": true
}
```

***

## Get Single Lead

```http theme={null}
GET /api/leads/:id
```

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

***

## Update Lead Status

```http theme={null}
PATCH /api/leads/:id/status
```

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

### Request Body

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
GET /api/leads/:id/avatar-image
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.