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

# Leads Management API

> Manage car-related leads, track interactions, and organize sales workflows

## Overview

The Leads Management API helps you track and manage potential sales opportunities for each vehicle in your inventory. Create actionable tasks, set priorities, and monitor lead status throughout the sales funnel.

## Endpoints

### List All Leads

<ParamField path="GET" type="endpoint">
  /leads
</ParamField>

Retrieve all leads with optional filtering and sorting.

**Query Parameters:**

<ParamField query="search" type="string">
  Global search across action, targetName, tag
</ParamField>

<ParamField query="status" type="enum">
  Filter by status: `NEW`, `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField query="action" type="string">
  Filter by action type
</ParamField>

<ParamField query="targetName" type="string">
  Filter by target name
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag
</ParamField>

<ParamField query="carId" type="string">
  Filter by associated vehicle ID
</ParamField>

<ParamField query="sortBy" type="enum">
  Sort field: `order`, `status`, `action`, `targetName`, `createdAt`
</ParamField>

<ParamField query="sortOrder" type="enum">
  Sort direction: `asc`, `desc`
</ParamField>

**Response:**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "carId": "car_uuid",
    "status": "NEW",
    "action": "Follow up call",
    "targetName": "John Smith",
    "targetInfo": "+212-600-123456",
    "tag": "Hot Lead",
    "note": "Customer interested in financing options",
    "order": 1,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "car": {
      "id": "car_uuid",
      "make": "Honda",
      "model": "Civic",
      "overviewYear": 2021,
      "location": "Casablanca"
    }
  }
]
```

***

### Get Lead by ID

<ParamField path="GET" type="endpoint">
  /leads/{id}
</ParamField>

Retrieve detailed information about a specific lead.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Lead UUID
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "carId": "car_uuid",
  "status": "NEW",
  "action": "Follow up call",
  "targetName": "John Smith",
  "targetInfo": "+212-600-123456",
  "tag": "Hot Lead",
  "note": "Customer interested in financing options",
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

***

### Create Lead for Vehicle

<ParamField path="POST" type="endpoint">
  /leads/car/{carId}
</ParamField>

Create a new lead associated with a specific vehicle.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "jane.doe@email.com",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "status": "NEW",
  "order": 1
}
```

<ParamField body="action" type="string" required>
  Action description (max 200 characters)
</ParamField>

<ParamField body="targetName" type="string" required>
  Lead contact name (max 200 characters)
</ParamField>

<ParamField body="targetInfo" type="string" required>
  Contact information - phone or email (max 500 characters)
</ParamField>

<ParamField body="tag" type="string">
  Lead category tag (max 100 characters)
</ParamField>

<ParamField body="note" type="string">
  Additional notes (max 1000 characters)
</ParamField>

<ParamField body="status" type="enum">
  Lead status: `NEW` (default), `COMPLETED`, `NOT_NEEDED`
</ParamField>

<ParamField body="order" type="integer">
  Display order for sorting (default: 0)
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "carId": "car_uuid",
  "status": "NEW",
  "action": "Schedule test drive",
  "targetName": "Jane Doe",
  "targetInfo": "jane.doe@email.com",
  "tag": "Test Drive",
  "note": "Prefers weekend appointments",
  "order": 1,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

***

### Update Lead

<ParamField path="PATCH" type="endpoint">
  /leads/{id}
</ParamField>

Update an existing lead's information.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Lead UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested."
}
```

All fields are optional. Only provided fields will be updated.

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested.",
  "updatedAt": "2024-01-16T14:20:00Z"
}
```

***

### Get Leads for Vehicle

<ParamField path="GET" type="endpoint">
  /leads/car/{carId}
</ParamField>

Retrieve all leads associated with a specific vehicle.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Query Parameters:**

Same filtering and sorting options as `/leads` endpoint.

**Response:**

Array of lead objects sorted by order (ascending by default).

***

### Get Leads by Status

<ParamField path="GET" type="endpoint">
  /leads/status/{status}
</ParamField>

Filter leads by their current status.

**Path Parameters:**

<ParamField path="status" type="enum" required>
  Status: `NEW`, `COMPLETED`, `NOT_NEEDED`
</ParamField>

**Response:**

Array of lead objects matching the status.

***

### Reorder Leads

<ParamField path="PATCH" type="endpoint">
  /leads/car/{carId}/reorder
</ParamField>

Bulk update lead order positions for a vehicle.

**Path Parameters:**

<ParamField path="carId" type="string" required>
  Vehicle UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "leadOrders": [
    { "id": "lead_id_1", "order": 1 },
    { "id": "lead_id_2", "order": 2 },
    { "id": "lead_id_3", "order": 3 }
  ]
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Leads reordered successfully"
}
```

***

### Update Lead Order

<ParamField path="PATCH" type="endpoint">
  /leads/{id}/order
</ParamField>

Update the order position of a single lead.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Lead UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "order": 5
}
```

***

### Delete Lead

<ParamField path="DELETE" type="endpoint">
  /leads/{id}
</ParamField>

Permanently delete a lead.

**Path Parameters:**

<ParamField path="id" type="string" required>
  Lead UUID
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Lead deleted successfully"
}
```

***

## Lead Status Workflow

<Steps>
  <Step title="NEW">
    Lead is created and requires action. This is the default status.
  </Step>

  <Step title="COMPLETED">
    Action has been completed successfully. Lead achieved its goal.
  </Step>

  <Step title="NOT_NEEDED">
    Lead is no longer relevant or was cancelled.
  </Step>
</Steps>

## Use Cases

### Example 1: Track Test Drive Requests

```bash theme={null}
# Create test drive lead
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Schedule test drive",
    "targetName": "Ahmed Benali",
    "targetInfo": "+212-600-123456",
    "tag": "Test Drive",
    "note": "Prefers Saturday morning"
  }'
```

### Example 2: Follow-up Call Tracking

```bash theme={null}
# Create follow-up lead
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Follow-up call",
    "targetName": "Sara Alami",
    "targetInfo": "sara.alami@email.com",
    "tag": "Hot Lead",
    "note": "Interested in financing. Call back Tuesday"
  }'
```

### Example 3: Document Review

```bash theme={null}
# Create document review lead
curl -X POST "https://api.steerai.autos/v1/leads/car/{carId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Prepare sales documents",
    "targetName": "Legal Department",
    "targetInfo": "legal@dealership.com",
    "tag": "Documentation"
  }'
```

## Error Codes

| Code                       | Status | Description                           |
| -------------------------- | ------ | ------------------------------------- |
| `LEAD_NOT_FOUND`           | 404    | Lead ID does not exist                |
| `CAR_NOT_FOUND`            | 404    | Associated vehicle not found          |
| `UNAUTHORIZED_LEAD_ACCESS` | 403    | User doesn't have access to this lead |
| `INVALID_LEAD_STATUS`      | 400    | Invalid status value provided         |
| `VALIDATION_ERROR`         | 400    | Request body validation failed        |

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive actions">
    Make action descriptions clear and actionable. Good: "Follow up call about financing". Bad: "Call".
  </Accordion>

  <Accordion title="Leverage tags for organization">
    Use consistent tags across your organization: "Hot Lead", "Test Drive", "Documentation", "Follow-up".
  </Accordion>

  <Accordion title="Keep notes updated">
    Add notes after each interaction to maintain context and history.
  </Accordion>

  <Accordion title="Reorder leads by priority">
    Use the order field to prioritize leads. Lower numbers appear first.
  </Accordion>

  <Accordion title="Clean up completed leads">
    Regularly archive or delete completed leads to keep your pipeline clean.
  </Accordion>
</AccordionGroup>

## Integration Tips

The Leads API integrates seamlessly with:

* **Vehicles API** - Automatically link leads to inventory
* **CRM Systems** - Export leads to external CRM platforms
* **Email/SMS Services** - Trigger notifications on lead status changes
* **Analytics** - Track conversion rates and lead performance

<Card title="CRM Integration Guide" icon="diagram-project" href="/features/crm/overview">
  Learn more about CRM integration and best practices
</Card>