Complete API documentation for the Vehicle Database data aggregation service
The Vehicle Database API provides access to comprehensive vehicle data, user authentication, and credit management for vehicle information reports.
https://tc.telecloud.co.za/api/method/vehicle_database.api.vehicle_db_api
All API responses follow a consistent JSON format:
{
"status": "SUCCESS" | "FAILURE",
"message": "Human readable message",
"data": { ... } // Optional additional data
}
The API uses token-based authentication with SMS verification. The authentication flow is:
api_token parameter in all authenticated requestsSend SMS verification code to existing user's mobile number.
Valid South African mobile number (10 digits)
API key for additional authentication
{
"status": "SUCCESS",
"message": "Token sent",
"api_token": "a1b2c3d4e5f6..."
}
{
"status": "FAILURE",
"message": "Phone number not found. Already have an account? Call us to link your number to your account."
}
Register a new user account and send SMS verification code.
Valid South African mobile number
Full name of the user
Email address
Company name
{
"status": "SUCCESS",
"message": "OTP Sent."
}
Verify the SMS code and receive API token for authenticated requests.
Mobile number that received the SMS
6-digit verification code from SMS
{
"status": "SUCCESS",
"message": "SMS Verified",
"api_token": "a1b2c3d4e5f6..."
}
Retrieve account details for the authenticated user.
User's API token from authentication
{
"status": "SUCCESS",
"message": "Account data retrieved",
"id": 123,
"balance": 0,
"company": "Company Name",
"contact": "John Doe",
"phone": "0821234567",
"email": "john@example.com",
"credits_balance": 10
}
Retrieve partner/reseller details.
User's API token
{
"status": "SUCCESS",
"message": "Partner data retrieved",
"account": {
"contact": "Partner Name",
"company": "Partner Company",
"address": "123 Main St",
"phone": "0821234567",
"email": "partner@example.com",
"website_address": "https://example.com"
}
}
Get filter options for vehicle search (makes, models, sub-types, years).
User's API token
Search term to filter results
Filter by vehicle make
Filter by vehicle model
Filter by vehicle sub-type
Filter by year
{
"status": "SUCCESS",
"message": "Success",
"makes": ["Toyota", "Honda", "BMW", ...],
"models": ["Corolla", "Civic", "3 Series", ...],
"sub_types": ["Sedan", "SUV", "Hatchback", ...],
"years": ["2024", "2023", "2022", ...]
}
Search vehicles with filters and pagination.
User's API token
Search term
Filter by make
Filter by model
Filter by sub-type
Filter by year
Page number (default: 0)
Results per page (default: 500)
{
"status": "SUCCESS",
"message": "Success",
"total_rows": 1234,
"rows": [
{
"make": "Toyota",
"model": "Corolla",
"sub_type": "Sedan",
"year": "2024"
},
...
]
}
Create an invoice for purchasing vehicle database credits.
User's API token
Invoice amount
Quantity of credits
Invoice reference/description
{
"status": "SUCCESS",
"message": "Invoice created"
}
Deduct credits from account when generating a report.
User's API token
Number of credits to deduct
Type of report being generated
{
"status": "SUCCESS",
"message": "Credits deducted"
}
Refund credits if report generation fails.
User's API token
Number of credits to refund
Type of report that failed
{
"status": "SUCCESS",
"message": "Credits refunded"
}
Submit a contact form message.
Full name
Phone number
Email address
Message content
{
"status": "SUCCESS",
"message": "Message submitted. Thank you for your message."
}
The API uses standard HTTP status codes and consistent error response format:
// Authentication Errors
{
"status": "FAILURE",
"message": "Token required"
}
{
"status": "FAILURE",
"message": "Invalid token"
}
{
"status": "FAILURE",
"message": "Account disabled"
}
// Validation Errors
{
"status": "FAILURE",
"message": "Mobile number required"
}
{
"status": "FAILURE",
"message": "Amount is required"
}
// Step 1: Sign up new user
POST /api/method/vehicle_database.api.vehicle_db_api.post_signup
{
"mobile_number": "0821234567",
"name": "John Doe",
"email": "john@example.com",
"company": "Example Corp"
}
// Response: { "status": "SUCCESS", "message": "OTP Sent." }
// Step 2: Verify SMS code
POST /api/method/vehicle_database.api.vehicle_db_api.post_sms_token
{
"mobile_number": "0821234567",
"code": "123456"
}
// Response: { "status": "SUCCESS", "message": "SMS Verified", "api_token": "abc123..." }
// Step 3: Use API token for authenticated requests
GET /api/method/vehicle_database.api.vehicle_db_api.get_account?api_token=abc123...
// Response: Account details with credits balance