> ## 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.

# API Reference

> The BrokerOS REST API is a NestJS 11 application running on port 3001. All endpoints are prefixed with /api.

## Base URL

```
https://api.yourdomain.com
```

All endpoints begin with `/api`. For local development:

```
http://localhost:3001
```

***

## Authentication

All endpoints (except where marked **Public**) require a valid Better Auth session. Include the session cookie in every request — it is set automatically by the browser after login.

For programmatic access (e.g. mobile app background services, scripts), pass the session token as a Bearer header:

```http theme={null}
Authorization: Bearer <session_token>
```

Read the full auth guide → [Authentication](https://brokeros.mintlify.site/api-reference/authentication.md)

***

## Response Format

All responses are JSON. Successful responses return the data directly (object or array). Errors follow this shape:

```json theme={null}
{
  "statusCode": 400,
  "message": "phone must be a string",
  "error": "Bad Request"
}
```

***

## Role-Based Access

Most endpoints check the authenticated user's role before responding. If your role does not have access, you receive:

```json theme={null}
{
  "statusCode": 403,
  "message": "Forbidden resource"
}
```

The role is **always read from the server-side session** — never from the request body.

***

## API Modules

> **[Leads](https://brokeros.mintlify.site/api-reference/leads.md)**
>
> Create, list, update, assign, and bulk-import leads. Core of all CRM operations.

> **[Site Visits](https://brokeros.mintlify.site/api-reference/site-visits.md)**
>
> Schedule, update, and GPS-verify site visits linked to leads.

> **[Follow-Ups](https://brokeros.mintlify.site/api-reference/follow-ups.md)**
>
> Create and manage follow-up tasks for individual leads.

> **[Negotiations](https://brokeros.mintlify.site/api-reference/negotiations.md)**
>
> Submit and retrieve discount negotiation requests for a lead.

> **[Bookings](https://brokeros.mintlify.site/api-reference/bookings.md)**
>
> Create bookings, upload documents, manage loan cases, agreements, and handovers.

> **[Inventory](https://brokeros.mintlify.site/api-reference/inventory.md)**
>
> Manage projects, towers, units, and possession statuses.

> **[Brokers (CP)](https://brokeros.mintlify.site/api-reference/brokers.md)**
>
> Create and manage the external Channel Partner broker network.

> **[Approvals](https://brokeros.mintlify.site/api-reference/approvals.md)**
>
> Submit and manage discount approval requests and messages.

> **[Marketing — Voice](https://brokeros.mintlify.site/api-reference/marketing-voice.md)**
>
> Create and dispatch AI voice campaigns with full audience and analytics control.

> **[Marketing — WhatsApp](https://brokeros.mintlify.site/api-reference/marketing-whatsapp.md)**
>
> Send broadcasts, manage conversations, flows, templates, and pipelines.

> **[Marketing — SMS](https://brokeros.mintlify.site/api-reference/marketing-sms.md)**
>
> Run SMS campaigns, manage integrations, flows, and track delivery.

> **[Marketing — Email](https://brokeros.mintlify.site/api-reference/marketing-email.md)**
>
> Send email campaigns, manage integrations, audience, templates, and analytics.

> **[Users & System](https://brokeros.mintlify.site/api-reference/users.md)**
>
> User location updates, push tokens, roles, sources, and project lookups.

> **[Webhooks](https://brokeros.mintlify.site/api-reference/webhooks.md)**
>
> Inbound webhook endpoints for Meta WhatsApp, SMS gateways, and voice platforms.


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