Leads Management API - Steer Autos Documentation

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

GET

endpoint

/leads

Retrieve all leads with optional filtering and sorting. Query Parameters:

string

Global search across action, targetName, tag

status

enum

Filter by status: NEW, COMPLETED, NOT_NEEDED

action

string

Filter by action type

targetName

string

Filter by target name

tag

string

Filter by tag

carId

string

Filter by associated vehicle ID

sortBy

enum

Sort field: order, status, action, targetName, createdAt

sortOrder

enum

Sort direction: asc, desc

Response:

[
  {
    "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

GET

endpoint

/leads/

Retrieve detailed information about a specific lead. Path Parameters:

string

required

Lead UUID

Response:

{
  "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

POST

endpoint

/leads/car/

Create a new lead associated with a specific vehicle. Path Parameters:

carId

string

required

Vehicle UUID

Request Body:

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

action

string

required

Action description (max 200 characters)

targetName

string

required

Lead contact name (max 200 characters)

targetInfo

string

required

Contact information - phone or email (max 500 characters)

tag

string

Lead category tag (max 100 characters)

note

string

Additional notes (max 1000 characters)

status

enum

Lead status: NEW (default), COMPLETED, NOT_NEEDED

order

integer

Display order for sorting (default: 0)

Response:

{
  "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

PATCH

endpoint

/leads/

Update an existing lead’s information. Path Parameters:

string

required

Lead UUID

Request Body:

{
  "status": "COMPLETED",
  "note": "Test drive completed. Customer very interested."
}

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

{
  "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

GET

endpoint

/leads/car/

Retrieve all leads associated with a specific vehicle. Path Parameters:

carId

string

required

Vehicle UUID

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

GET

endpoint

/leads/status/

Filter leads by their current status. Path Parameters:

status

enum

required

Status: NEW, COMPLETED, NOT_NEEDED

Response: Array of lead objects matching the status.

Reorder Leads

PATCH

endpoint

/leads/car//reorder

Bulk update lead order positions for a vehicle. Path Parameters:

carId

string

required

Vehicle UUID

Request Body:

{
  "leadOrders": [
    { "id": "lead_id_1", "order": 1 },
    { "id": "lead_id_2", "order": 2 },
    { "id": "lead_id_3", "order": 3 }
  ]
}

Response:

{
  "success": true,
  "message": "Leads reordered successfully"
}

Update Lead Order

PATCH

endpoint

/leads//order

Update the order position of a single lead. Path Parameters:

string

required

Lead UUID

Request Body:

{
  "order": 5
}

Delete Lead

DELETE

endpoint

/leads/

Permanently delete a lead. Path Parameters:

string

required

Lead UUID

Response:

{
  "success": true,
  "message": "Lead deleted successfully"
}

Lead Status Workflow

NEW

Lead is created and requires action. This is the default status.

COMPLETED

Action has been completed successfully. Lead achieved its goal.

NOT_NEEDED

Lead is no longer relevant or was cancelled.

Use Cases

Example 1: Track Test Drive Requests

# 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

# 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

# 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

Use descriptive actions

Make action descriptions clear and actionable. Good: “Follow up call about financing”. Bad: “Call”.

Leverage tags for organization

Use consistent tags across your organization: “Hot Lead”, “Test Drive”, “Documentation”, “Follow-up”.

Keep notes updated

Add notes after each interaction to maintain context and history.

Reorder leads by priority

Use the order field to prioritize leads. Lower numbers appear first.

Clean up completed leads

Regularly archive or delete completed leads to keep your pipeline clean.

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

CRM Integration Guide

Learn more about CRM integration and best practices

API Documentation

​Overview

​Endpoints

​List All Leads

​Get Lead by ID

​Create Lead for Vehicle

​Update Lead

​Get Leads for Vehicle

​Get Leads by Status

​Reorder Leads

​Update Lead Order

​Delete Lead

​Lead Status Workflow

​Use Cases

​Example 1: Track Test Drive Requests

​Example 2: Follow-up Call Tracking

​Example 3: Document Review

​Error Codes

​Best Practices

​Integration Tips

CRM Integration Guide

Overview

Endpoints

List All Leads

Get Lead by ID

Create Lead for Vehicle

Update Lead

Get Leads for Vehicle

Get Leads by Status

Reorder Leads

Update Lead Order

Delete Lead

Lead Status Workflow

Use Cases

Example 1: Track Test Drive Requests

Example 2: Follow-up Call Tracking

Example 3: Document Review

Error Codes

Best Practices

Integration Tips