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

# API für Lead-Management

> Verwalten Sie fahrzeugbezogene Leads, verfolgen Sie Interaktionen und organisieren Sie Vertriebsabläufe

## Überblick

Die Lead-Management-API hilft Ihnen, potenzielle Verkaufschancen für jedes Fahrzeug in Ihrem Bestand zu verfolgen und zu verwalten. Erstellen Sie umsetzbare Aufgaben, setzen Sie Prioritäten und überwachen Sie den Lead-Status im gesamten Vertriebstrichter.

## Endpunkte

### Alle Leads auflisten

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

Ruft alle Leads mit optionaler Filterung und Sortierung ab.

**Query-Parameter:**

<ParamField query="search" type="string">
  Globale Suche über action, targetName, tag
</ParamField>

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

<ParamField query="action" type="string">
  Filter nach Aktionstyp
</ParamField>

<ParamField query="targetName" type="string">
  Filter nach Zielname
</ParamField>

<ParamField query="tag" type="string">
  Filter nach Tag
</ParamField>

<ParamField query="carId" type="string">
  Filter nach zugeordneter Fahrzeug-ID
</ParamField>

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

<ParamField query="sortOrder" type="enum">
  Sortierrichtung: `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"
    }
  }
]
```

***

### Lead nach ID abrufen

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

Ruft detaillierte Informationen zu einem bestimmten Lead ab.

**Path-Parameter:**

<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"
}
```

***

### Lead für Fahrzeug erstellen

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

Erstellt einen neuen Lead für ein bestimmtes Fahrzeug.

**Path-Parameter:**

<ParamField path="carId" type="string" required>
  Fahrzeug-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>
  Aktionsbeschreibung (max. 200 Zeichen)
</ParamField>

<ParamField body="targetName" type="string" required>
  Name des Lead-Kontakts (max. 200 Zeichen)
</ParamField>

<ParamField body="targetInfo" type="string" required>
  Kontaktinformation – Telefon oder E-Mail (max. 500 Zeichen)
</ParamField>

<ParamField body="tag" type="string">
  Lead-Kategorietag (max. 100 Zeichen)
</ParamField>

<ParamField body="note" type="string">
  Zusätzliche Notizen (max. 1000 Zeichen)
</ParamField>

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

<ParamField body="order" type="integer">
  Anzeigereihenfolge für Sortierung (Standard: 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"
}
```

***

### Lead aktualisieren

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

Aktualisiert einen bestehenden Lead.

**Path-Parameter:**

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

**Request Body:**

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

Alle Felder sind optional. Nur übermittelte Felder werden aktualisiert.

**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"
}
```

***

### Leads für Fahrzeug abrufen

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

Ruft alle Leads ab, die einem bestimmten Fahrzeug zugeordnet sind.

**Path-Parameter:**

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

**Query-Parameter:**

Gleiche Filter- und Sortieroptionen wie beim `/leads`-Endpunkt.

**Response:**

Array von Lead-Objekten, standardmäßig nach Reihenfolge sortiert.

***

### Leads nach Status abrufen

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

Filtert Leads nach ihrem aktuellen Status.

**Path-Parameter:**

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

**Response:**

Array von Leads, die dem Status entsprechen.

***

### Leads neu sortieren

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

Aktualisiert die Reihenfolge der Leads eines Fahrzeugs im Bulk.

**Path-Parameter:**

<ParamField path="carId" type="string" required>
  Fahrzeug-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"
}
```

***

### Lead-Reihenfolge aktualisieren

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

Aktualisiert die Reihenfolge eines einzelnen Leads.

**Path-Parameter:**

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

**Request Body:**

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

***

### Lead löschen

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

Löscht einen Lead dauerhaft.

**Path-Parameter:**

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

**Response:**

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

***

## Lead-Status-Ablauf

<Steps>
  <Step title="NEW">
    Lead wird erstellt und erfordert eine Aktion. Dies ist der Standardstatus.
  </Step>

  <Step title="COMPLETED">
    Aktion wurde erfolgreich abgeschlossen. Lead hat sein Ziel erreicht.
  </Step>

  <Step title="NOT_NEEDED">
    Lead ist nicht mehr relevant oder wurde abgebrochen.
  </Step>
</Steps>

## Anwendungsfälle

### Beispiel 1: Testfahrt-Anfragen verfolgen

```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"
  }'
```

### Beispiel 2: Nachfassanruf verfolgen

```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"
  }'
```

### Beispiel 3: Dokumentenprüfung

```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"
  }'
```

## Fehlercodes

| Code                       | Status | Beschreibung                                 |
| -------------------------- | ------ | -------------------------------------------- |
| `LEAD_NOT_FOUND`           | 404    | Lead-ID existiert nicht                      |
| `CAR_NOT_FOUND`            | 404    | Zugehöriges Fahrzeug nicht gefunden          |
| `UNAUTHORIZED_LEAD_ACCESS` | 403    | Benutzer hat keinen Zugriff auf diesen Lead  |
| `INVALID_LEAD_STATUS`      | 400    | Ungültiger Statuswert angegeben              |
| `VALIDATION_ERROR`         | 400    | Validierung des Request Bodys fehlgeschlagen |

## Bewährte Praktiken

<AccordionGroup>
  <Accordion title="Aussagekräftige Aktionen verwenden">
    Beschreibungen sollten klar und umsetzbar sein. Gut: "Follow up call about financing". Schlecht: "Call".
  </Accordion>

  <Accordion title="Tags zur Organisation nutzen">
    Verwenden Sie konsistente Tags im gesamten Unternehmen: "Hot Lead", "Test Drive", "Documentation", "Follow-up".
  </Accordion>

  <Accordion title="Notizen aktuell halten">
    Ergänzen Sie nach jeder Interaktion Notizen, um Kontext und Verlauf zu bewahren.
  </Accordion>

  <Accordion title="Leads nach Priorität sortieren">
    Nutzen Sie das Feld order zur Priorisierung. Niedrigere Zahlen erscheinen zuerst.
  </Accordion>

  <Accordion title="Abgeschlossene Leads bereinigen">
    Archivieren oder löschen Sie abgeschlossene Leads regelmäßig, um die Pipeline sauber zu halten.
  </Accordion>
</AccordionGroup>

## Integrationstipps

Die Leads-API integriert sich nahtlos mit:

* **Vehicles API** – Leads automatisch mit dem Bestand verknüpfen
* **CRM-Systemen** – Leads in externe CRM-Plattformen exportieren
* **E-Mail/SMS-Diensten** – Benachrichtigungen bei Statusänderungen auslösen
* **Analytics** – Conversion-Raten und Lead-Performance verfolgen

<Card title="CRM-Integrationsleitfaden" icon="diagram-project" href="/de/features/crm/overview">
  Erfahren Sie mehr über CRM-Integration und bewährte Praktiken
</Card>