Developer docs
Current API v1 reference

From first request to decoded vehicle.

Build automotive and powersports selectors, resolve complete vehicle records, or decode a VIN through one authenticated API.

Make your first request Explore VIN decoding

Automotive

Year → details

Powersports

Type-aware discovery

VIN Decoder Beta

POST one validated VIN

Quick start

A production request in three steps.

1

Choose a plan

Your active plan controls product access and usage allowances.

2

Create a token

Generate a token in the dashboard and configure its permitted server IPs.

3

Send the request

Use Bearer authentication and request JSON from the v1 base URL.

cURL · automotive years 
curl "https://carlistapi.com/api/v1/car-data/get-years/asc" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json"
Server-side only. Keep the token out of browser JavaScript, public repositories, URLs and logs. Requests must originate from an IP allowed on that token.

Authentication

Bearer tokens with IP controls.

All production v1 data and VIN routes require a token, an active account and subscription, enabled API access, the relevant product entitlement, and a matching request IP.

Required headers 
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

Optional server-to-server token creation

POST /api/login accepts account credentials and, when permitted by the account and plan, returns a one-year token restricted to the caller’s IP. Prefer creating and rotating tokens from the dashboard.

POST /api/login 
{
    "email": "developer@example.com",
    "password": "YOUR_PASSWORD"
}

Response contract

JSON that keeps HTTP semantics intact.

Successful lookup endpoints return the requested array or object directly at the JSON root—there is no data envelope. Errors use the proper HTTP status and a safe JSON message. Validation errors generated before a controller may use Laravel’s message and errors fields.

200Successful lookup or VIN decode
401Missing or invalid authentication
403Account, IP, subscription or product access denied
409API token allowance reached during login
422Invalid input or a VIN that could not be decoded
429API or VIN allowance exhausted
502VIN provider temporarily unavailable
Quota response · 429 
{
    "error": "API request limit reached.",
    "limit": 10000,
    "used": 10000,
    "remaining": 0,
    "reset_at": "2026-08-01T00:00:00-07:00"
}

Automotive API

Discover, resolve, then fetch details.

/api/v1/car-data

The standard selector flow is year → make → model → trim → engine → vehicle ID → details. URL-encode every path value, especially trims and engines containing spaces or slashes.

Typical flow 
GET /api/v1/car-data/get-makes/2026/asc
GET /api/v1/car-data/get-models/2026/Chevrolet/asc
GET /api/v1/car-data/get-trims/2026/Chevrolet/Trailblazer/asc
GET /api/v1/car-data/get-engines/2026/Chevrolet/Trailblazer/LT/asc
GET /api/v1/car-data/get-vehicle-id/2026/Chevrolet/Trailblazer/LT/{engine}
GET /api/v1/car-data/get-details/{uuid}
GET/api/v1/car-data/get-years/{sort?}All supported years.
GET/api/v1/car-data/get-years/range/{minYear}/{maxYear}/{sort?}Years within an inclusive range.
GET/api/v1/car-data/all-makes/{sort?}All automotive makes.
GET/api/v1/car-data/get-makes/{year}/{sort?}Makes available for a year.
GET/api/v1/car-data/get-models/{year}/{make}/{sort?}Models for a year and make.
GET/api/v1/car-data/get-trims/{year}/{make}/{model}/{sort?}Trims for a selected vehicle.
GET/api/v1/car-data/get-engines/{year}/{make}/{model}/{trim}/{sort?}Engines for a selected trim.
GET/api/v1/car-data/get-vehicle-id/{year}/{make}/{model}/{trim}/{engine}Resolve a vehicle UUID.
GET/api/v1/car-data/get-details/{uuid}Full normalized details by UUID.
GET/api/v1/car-data/get-make-logo/{make}Logo information for a make.
GET/api/v1/car-data/get-makes-by-year/range/{minYear}/{maxYear}/{sort?}Makes found across a year range.
GET/api/v1/car-data/get-body-styles/{sort?}Distinct body styles.
GET/api/v1/car-data/get-years-by-body-style/{body_style}/{sort?}Years filtered by body style.
GET/api/v1/car-data/get-makes-by-body-style/{body_style}/{sort?}Makes filtered by body style.
GET/api/v1/car-data/get-makes-by-body-style-and-year/{body_style}/{year}/{sort?}Makes filtered by body style and year.
GET/api/v1/car-data/get-drive-types/{sort?}Distinct drive types.
GET/api/v1/car-data/drive-types/get-makes/{driveType}/{sort?}Makes filtered by drive type.
GET/api/v1/car-data/drive-types/get-models/{driveType}/{make}/{sort?}Models filtered by drive type and make.
GET/api/v1/car-data/get-fuel-types/{sort?}Distinct fuel types.
GET/api/v1/car-data/get-fuel-types/get-makes/{fuelType}/{sort?}Makes filtered by fuel type.
GET/api/v1/car-data/get-fuel-types/get-models/{fuelType}/{make}/{sort?}Models filtered by fuel type and make.
GET/api/v1/car-data/get-number-doors/{sort?}Distinct door counts.

Vehicle details response

GET /api/v1/car-data/get-details/{uuid} returns the complete vehicle object directly, without a wrapping data property.

Vehicle details · 200 
{
    "id": "9f55fd34-a206-4507-b1ee-6eb2eb9fab35",
    "type": "Automotive",
    "year": "2026",
    "make": "Chevrolet",
    "model": "Trailblazer",
    "subModel": "LT",
    "trim": "LT Sport Utility 4-Door",
    "engineLiter": "1.3L",
    "engine": "1.3L 1349CC 83Cu. In. l3 GAS DOHC Turbocharged",
    "bodyStyle": "Sport Utility",
    "engine_cylinders": "3",
    "cylinder_type": "DOHC",
    "engine_cc": "1349",
    "drive_type": "AWD",
    "fuel_type": "GAS",
    "number_doors": "4",
    "diaplay_name": "Chevrolet Trailblazer 2026 LT",
    "aspiration": "Turbocharged",
    "makeLogoUrl": "https://carlistapi.com/assets/img/car-logos/chevrolet.png"
}

Powersports API

The same predictable discovery flow, with types.

/api/v1/powersports-data

Browse the complete catalog or narrow it by a powersports type. Types can contain slashes, so encode them as path values. Sub-model selection maps to the {trim} segment when resolving the vehicle ID.

GET/api/v1/powersports-data/get-years/{sort?}All supported powersports years.
GET/api/v1/powersports-data/get-years/range/{minYear}/{maxYear}/{sort?}Years within an inclusive range.
GET/api/v1/powersports-data/all-makes/{sort?}All powersports makes.
GET/api/v1/powersports-data/get-makes/{year}/{sort?}Makes available for a year.
GET/api/v1/powersports-data/get-models/{year}/{make}/{sort?}Models for a year and make.
GET/api/v1/powersports-data/get-sub-models/{year}/{make}/{model}/{sort?}Sub-models for a selected model.
GET/api/v1/powersports-data/get-vehicle-id/{year}/{make}/{model}/{trim}Resolve a powersports vehicle UUID.
GET/api/v1/powersports-data/get-details/{uuid}Full normalized details by UUID.
GET/api/v1/powersports-data/get-make-logo/{make}Logo information for a make.
GET/api/v1/powersports-data/get-makes-by-year/range/{minYear}/{maxYear}/{sort?}Makes found across a year range.
GET/api/v1/powersports-data/get-types/{sort?}Distinct powersports types.
GET/api/v1/powersports-data/type/get-years/{type}/{sort?}Years filtered by type.
GET/api/v1/powersports-data/type/get-years/range/{type}/{minYear}/{maxYear}/{sort?}Years filtered by type and range.
GET/api/v1/powersports-data/type/get-makes/{type}/{sort?}Makes filtered by type.
GET/api/v1/powersports-data/type/get-makes-by-year/range/{type}/{minYear}/{maxYear}/{sort?}Makes filtered by type and year range.
GET/api/v1/powersports-data/type/get-makes-by-year/{type}/{year}/{sort?}Makes filtered by type and year.
GET/api/v1/powersports-data/type/get-models-by-year-make/{type}/{year}/{make}/{sort?}Models filtered by type, year and make.
GET/api/v1/powersports-data/type/get-sub-models-by-year-make/{type}/{year}/{make}/{model}/{sort?}Sub-models filtered by type and vehicle.
VIN Decoder Beta

Decode a validated 17-character VIN.

VIN decoding uses its own plan entitlement and hard monthly quota. It is separate from the standard data API allowance.

POST/api/v1/vin-decoder/decode
cURL · decode VIN 
curl -X POST "https://carlistapi.com/api/v1/vin-decoder/decode" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"vin":"1HGCM82633A004352","model_year":2003}'
vinRequired string

Exactly 17 characters after spaces and hyphens are removed. It is uppercased automatically.

model_yearOptional integer

1980 through the current year plus two. Use it only when known.

VINs may contain A–H, J–N, P, R–Z and digits. The letters I, O and Q are invalid.

Successful response

Fields can be null when the provider cannot resolve them. The API preserves partial results and does not invent missing vehicle data.

Response · 200 
{
    "vin": "1HGCM82633A004352",
    "vehicle": "2003 HONDA Accord EX-V6",
    "year": 2003,
    "make": "HONDA",
    "model": "Accord",
    "trim": "EX-V6",
    "vehicleType": "PASSENGER CAR",
    "bodyClass": "Coupe",
    "driveType": null,
    "fuelType": "Gasoline",
    "engineCylinders": 6,
    "engineDisplacementLiters": 3,
    "transmissionStyle": "Automatic",
    "manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
    "plantCountry": "UNITED STATES (USA)",
    "attributes": {
        "gVWR": "Class 1C: 4,001 - 5,000 lb (1,814 - 2,268 kg)",
        "make": "HONDA",
        "trim": "EX-V6",
        "doors": 2,
        "model": "Accord",
        "gVWRTo": "Class 1: 6,000 lb or less (2,722 kg or less)",
        "makeID": 474,
        "bedType": "Not Applicable",
        "busType": "Not Applicable",
        "modelID": 1861,
        "engineHP": 240,
        "nCSAMake": "Honda",
        "bodyClass": "Coupe",
        "modelYear": 2003,
        "nCSAModel": "Accord (Note: For Crosstour model years 2010 and 2011 only. For Crosstour model years 2012-2015, see vehicle model 37-405)",
        "plantCity": "MARYSVILLE",
        "plantState": "OHIO",
        "bodyCabType": "Not Applicable",
        "engineModel": "J30A4",
        "trailerType": "Not Applicable",
        "vehicleType": "PASSENGER CAR",
        "manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
        "nCSABodyType": "2-door sedan,hardtop,coupe",
        "plantCountry": "UNITED STATES (USA)",
        "seatBeltsAll": "Manual",
        "airBagLocSide": "1st Row (Driver and Passenger)",
        "displacementL": 2.998832712,
        "airBagLocFront": "1st Row (Driver and Passenger)",
        "displacementCC": 2998.832712,
        "displacementCI": 183,
        "manufacturerId": 988,
        "engineCylinders": 6,
        "fuelTypePrimary": "Gasoline",
        "trailerBodyType": "Not Applicable",
        "airBagLocCurtain": "1st and 2nd Rows",
        "valveTrainDesign": "Single Overhead Cam (SOHC)",
        "transmissionStyle": "Automatic",
        "vehicleDescriptor": "1HGCM826*3A",
        "busFloorConfigType": "Not Applicable",
        "transmissionSpeeds": 5,
        "engineConfiguration": "V-Shaped",
        "customMotorcycleType": "Not Applicable",
        "motorcycleChassisType": "Not Applicable",
        "motorcycleSuspensionType": "Not Applicable",
        "otherRestraintSystemInfo": "Seat Belt (Rr center position)"
    }
}
403

No eligible VIN access

Requires an active eligible subscription and VIN Decoder entitlement.

422

Invalid or undecodable VIN

Covers format validation and provider-declared decode failures.

429

VIN allowance exhausted

Returns limit, used, remaining and reset_at for the VIN quota.

502

Provider unavailable

A safe temporary-failure message is returned without provider internals.

Quota behavior: every successful customer decode counts, including cache hits. Failed decodes release the reservation and do not consume the allowance. Unused decodes do not roll over.

Demo API

Prototype without a token.

Open the guided demo

Demo endpoints are unauthenticated, use a limited dataset, are throttled separately, and return X-Demo-Mode: true. They are for evaluation—not production.

GET/api/v1/car-data-demo/get-years-demo/{sort?}
GET/api/v1/car-data-demo/get-makes-demo/{sort?}
GET/api/v1/car-data-demo/get-details-demo/{uuid}
GET/api/v1/car-data-demo/get-makes-by-year-demo/{year}/{sort?}
GET/api/v1/car-data-demo/get-models-demo/{year}/{make}/{sort?}
GET/api/v1/car-data-demo/get-vehicle-id-demo/{year}/{make}/{model}/{trim}/{engine}
GET/api/v1/car-data-demo/get-trims-demo/{year}/{make}/{model}/{sort?}
GET/api/v1/car-data-demo/get-engines-demo/{year}/{make}/{model}/{trim}/{sort?}
GET/api/v1/powersports-data-demo/get-years-demo/{sort?}
GET/api/v1/powersports-data-demo/get-makes-demo/{sort?}
GET/api/v1/powersports-data-demo/get-makes-by-year-demo/{year}/{sort?}
GET/api/v1/powersports-data-demo/get-models-demo/{year}/{make}/{sort?}
GET/api/v1/powersports-data-demo/get-trims-demo/{year}/{make}/{model}/{sort?}
GET/api/v1/powersports-data-demo/get-types/{sort?}
GET/api/v1/powersports-data-demo/type/get-years/{type}/{sort?}
GET/api/v1/powersports-data-demo/type/get-makes/{type}/{sort?}
GET/api/v1/powersports-data-demo/type/get-makes/{type}/year/{year}/{sort?}
GET/api/v1/powersports-data-demo/type/get-models/{type}/year/{year}/make/{make}
GET/api/v1/powersports-data-demo/type/get-submodels/{type}/year/{year}/make/{make}/model/{model}

Usage & quotas

Two allowances, enforced independently.

Data API usage

Automotive and powersports calls count toward the plan’s API allowance. The reset interval follows the plan configuration.

VIN decode usage

Successful VIN decodes count toward a separate monthly hard limit. Exhausting one allowance does not automatically exhaust the other.

When either limit is reached, stop retrying until reset_at. Surface the returned remaining and reset information to users, and use exponential backoff only for transient network or 5xx failures.

Caching

Cache stable discovery data close to your app.

Successful API responses include cache headers. Respect them where practical and key your application cache with every meaningful path input.

Laravel cache example 
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

$years = Cache::remember('carlistapi:v1:years:asc', 3600, function () {
    return Http::withToken(config('services.carlistapi.token'))
        ->acceptJson()
        ->get('https://carlistapi.com/api/v1/car-data/get-years/asc')
        ->throw()
        ->json();
});
Do not cache errors as successful empty data. Distinguish a real empty result from validation, entitlement, quota and provider failures.

Ship checklist

Before the integration goes live.

Keep tokens server-side and rotate exposed credentials.
Add every production egress IP to the token allowlist.
URL-encode all dynamic path segments.
Validate UUIDs and VINs before requesting the API.
Handle 401, 403, 422, 429 and 5xx responses separately.
Cache discovery data and avoid calls on every keystroke.
Use the dashboard to monitor API and VIN usage.
Never fabricate missing fields from partial VIN results.

Need help mapping your use case?

Send the team your product flow, data needs and expected volume.

Contact the team