Skip to main content

​
Introduction

The Vehicles API provides comprehensive endpoints for managing your vehicle inventory throughout the entire vehicle lifecycle - from initial listing to final sale. This includes vehicle data management, damage tracking, inspection coordination, and status updates.

​
Key Features

Inventory Management

Create, update, search, and filter your vehicle inventory with advanced search capabilities

Damage Tracking

Record and manage damage assessments with detailed reporting and cost estimation

Inspection Integration

Connect with AI-powered inspection services for automated damage detection

Status Workflow

Track vehicles through statuses: LOADING, INSPECTED, SOLD with full history

​
Vehicle Lifecycle

​
API Endpoints

​
Vehicle Management

EndpointMethodDescription
/vehiclesGETList all vehicles with filters and pagination
/vehicles/{id}GETGet vehicle details by ID
/vehiclesPOSTCreate a new vehicle
/vehicles/{id}PATCHUpdate vehicle information
/vehicles/{id}DELETEDelete a vehicle

​
Search & Filter

EndpointMethodDescription
/vehicles/publicGETGet published public vehicles
/vehicles/status/{status}GETFilter by purchase status
/vehicles/make/{make}GETFilter by vehicle make
/vehicles/location/{location}GETFilter by location
/vehicles/search/{q}GETFull-text search across vehicles

​
Damage Management

EndpointMethodDescription
/vehicles/{id}/completePUTComplete vehicle data with damages and analytics
/vehicles/{id}/damagesPOSTAdd damage record to vehicle
/vehicles/{id}/damages/{damageId}DELETERemove damage record
/vehicles/{id}/estimate-damagesPOSTTrigger AI damage estimation

​
Inspection Workflow

EndpointMethodDescription
/vehicles/phase/preprocess/{id}POSTAttach preprocessing job to vehicle
/vehicles/webhooks/ml-resultsPOSTWebhook for ML processing results

​
Vehicle Object Schema

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user_uuid",
  "make": "Honda",
  "model": "Civic",
  "overviewYear": 2021,
  "price": 25000,
  "km": 45000,
  "location": "Casablanca, Morocco",
  "seat": 5,
  "gearBox": "Automatic",
  "fuel": "Gasoline",
  "engineDisplacement": 1800,
  "numberCV": 140,
  "averageConsumption": "6.5L/100km",
  "outside": "Excellent",
  "inside": "Good",
  "ownerNumber": 1,
  "purchaseStatus": "INSPECTED",
  "archive": false,
  "published": true,
  "adNumber": 12345,
  "immatricule": "ABC-1234",
  "overviewImgs": "https://...",
  "postedBy": "Dealer XYZ",
  "functionalities": "GPS, Bluetooth, Cruise Control",
  "feature": "Sunroof, Leather Seats",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Query Parameters

​
Filtering Options

All list endpoints support the following filters:
  • search - Global search across make, model, location
  • make - Filter by vehicle make
  • model - Filter by vehicle model
  • minPrice / maxPrice - Price range filter
  • minYear / maxYear - Year range filter
  • minKm / maxKm - Mileage range filter
  • fuel - Filter by fuel type
  • gearBox - Filter by transmission type
  • location - Filter by location
  • purchaseStatus - Filter by status (LOADING, INSPECTED, SOLD)
  • published - Filter by publication status
  • archive - Filter by archive status

​
Pagination & Sorting

  • page - Page number (default: 1)
  • limit - Items per page (default: 10, max: 100)
  • sortBy - Sort field (price, overviewYear, km, createdAt)
  • sortOrder - Sort direction (asc, desc)

​
Purchase Status Workflow

​
Status Transitions

1

LOADING

Vehicle is being added to inventory. Images and details are being collected.
2

INSPECTED

Vehicle has been inspected. Damage reports and condition assessments are complete.
3

SOLD

Vehicle has been sold. Transaction complete.

​
Damage Object Schema

{
  "id": "damage_uuid",
  "type": "Dent",
  "severity": "moderate",
  "location": "Front Right Door",
  "description": "Small dent approximately 5cm diameter",
  "estimatedCost": 350,
  "imageUrls": [
    "https://...",
    "https://..."
  ]
}

​
Severity Levels

  • minor - Cosmetic damage, minimal repair needed
  • moderate - Visible damage requiring professional repair
  • severe - Structural damage requiring significant work

​
Rate Limits

Vehicle API endpoints follow the standard rate limits:
PlanRequests/HourBurst Limit
Free1,00050
Starter10,000200
Professional100,0001,000
EnterpriseUnlimitedCustom

​
Error Codes

CodeDescription
VEHICLE_NOT_FOUNDVehicle ID does not exist
VEHICLE_ALREADY_SOLDCannot modify sold vehicles
UNAUTHORIZED_VEHICLE_ACCESSUser does not own this vehicle
INVALID_PURCHASE_STATUSInvalid status transition
DUPLICATE_IMMATRICULELicense plate already exists

​
Best Practices

Ensure all required fields are provided and valid. Use the schema validation to prevent errors.
For inventories with 1000+ vehicles, always use pagination with reasonable page sizes (10-50).
Public vehicle listings are cached for 5 minutes. Use this to optimize performance.
Maintain audit logs of status changes for compliance and business intelligence.

​
Next Steps

List Vehicles

Learn how to retrieve and filter your vehicle inventory

Create Vehicle

Add new vehicles to your inventory

Damage Management

Manage damage reports and estimates

Search & Filter

Advanced search and filtering options