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

# Introduction

> Read-only REST API for CRM data integrations

## Base URL

```
https://<your-domain>/api/v2/crm
```

## Key Features

* **Read-only** customer data access
* **Bearer token** authentication (Sanctum)
* **Rate limited** to 60 requests per minute
* **Multi-tenant** — tokens only access your company's data
* **Granular permissions** — control what each token can access

## Response Format

All responses follow a consistent envelope:

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "per_page": 25,
    "next_cursor": "eyJsYXN0X2FjdGl2aXR5X2F0IjoiMjAyNi0wMiIsImlkIjo0NDB9",
    "prev_cursor": null,
    "has_more": true
  }
}
```

For single resources, `data` is an object instead of an array, and `meta` is omitted.

## Error Responses

| Status | Meaning                                           |
| ------ | ------------------------------------------------- |
| 401    | Missing or invalid token                          |
| 403    | Token lacks required permission                   |
| 404    | Resource not found                                |
| 429    | Rate limit exceeded (retry after header included) |

```json theme={null}
{
  "success": false,
  "message": "Unauthenticated."
}
```

## Pagination

The API uses **cursor-based pagination** — no total count, but faster and stable on large datasets.

Use `per_page` (max 100) to control page size. Pass `cursor` from the previous response's `meta.next_cursor` to get the next page.

```
# First page
GET /api/v2/crm/customers?per_page=50

# Next page
GET /api/v2/crm/customers?per_page=50&cursor=eyJsYXN0X2FjdGl2aXR5X2F0IjoiMjAyNiIsImlkIjo0NDB9
```

When `meta.has_more` is `false`, you have reached the last page.

## Filtering

Filters use the `filter` query parameter:

| Filter                     | Example                         | Description           |
| -------------------------- | ------------------------------- | --------------------- |
| `filter[query]`            | `?filter[query]=ahmed`          | Search by name        |
| `filter[lead_status.id][]` | `?filter[lead_status.id][]=3`   | Filter by lead status |
| `filter[owner.id][]`       | `?filter[owner.id][]=7`         | Filter by owner       |
| `filter[lead_source.id][]` | `?filter[lead_source.id][]=2`   | Filter by lead source |
| `filter[priority.id]`      | `?filter[priority.id]=1`        | Filter by priority    |
| `filter[date_from]`        | `?filter[date_from]=2026-01-01` | Created after date    |
| `filter[date_to]`          | `?filter[date_to]=2026-02-28`   | Created before date   |