Install and use the Car List API PHP SDK

The Car List API PHP SDK is a framework-independent client for the authenticated automotive, powersports, and VIN Decoder endpoints. It works with plain PHP, Symfony, Slim, WordPress, Laravel, and other Composer-based applications.

Initial SDK release: The Car List API PHP SDK is currently at v0.1.0. Before the SDK reaches v1.0, package-level interfaces may evolve as we incorporate developer feedback. Review the package changelog and test dependency updates before deploying them to production. The SDK version is separate from the Car List API version (v1).

Should I use the PHP or Laravel SDK?

Use this PHP SDK when your project does not use Laravel or when you want a framework-independent client that you configure directly.

If your application uses Laravel 11, 12, or 13, the Car List API Laravel SDK provides package auto-discovery, environment-based configuration, dependency injection, and a facade.

Requirements

• PHP 8.2 or newer

• Composer

• An active Car List API token

Install the SDK

Run this command from your project:

composer require codebyray/carlistapi-php-sdk

Create the client

Create a client using your API token:

use CodebyRay\CarListApi\CarListApi;

$carList = new CarListApi(
    token: getenv('CAR_LIST_API_TOKEN'),
);

Store the token in your application's environment or secret manager. Do not hard-code a production token, commit it to source control, expose it in browser-side JavaScript, or include it in support requests.

The default client settings are:

• Base URL: https://carlistapi.com/api

• API version: v1

• Request timeout: 15 seconds

• Connection timeout: 5 seconds

• Retries: 2

Make your first request

Retrieve the supported automotive years:

$years = $carList
    ->automotive()
    ->years()
    ->data;

Automotive example

$makes = $carList
    ->automotive()
    ->makes(2026)
    ->data;

$models = $carList
    ->automotive()
    ->models(2026, 'Toyota')
    ->data;

$vehicle = $carList
    ->automotive()
    ->details($vehicleUuid)
    ->data;

Powersports example

$types = $carList
    ->powersports()
    ->types()
    ->data;

$models = $carList
    ->powersports()
    ->modelsByYearMakeAndType('ATV / Utility', 2026, 'Can-Am')
    ->data;

VIN Decoder example

$vehicle = $carList
    ->vinDecoder()
    ->decode('1HGCM82633A004352')
    ->data;

If you know the model year, you can provide it as an additional argument:

$vehicle = $carList
    ->vinDecoder()
    ->decode('1HGCM82633A004352', modelYear: 2003)
    ->data;

Customize the client

Use a Configuration object when you need to change the API version, base URL, timeout, or retry behavior:

use CodebyRay\CarListApi\CarListApi;
use CodebyRay\CarListApi\Configuration;

$configuration = new Configuration(
    token: getenv('CAR_LIST_API_TOKEN'),
    baseUrl: 'https://carlistapi.com/api',
    version: 'v1',
    timeout: 15,
    connectTimeout: 5,
    retryTimes: 2,
    retrySleepMs: 200,
);

$carList = new CarListApi($configuration);

The base URL must end with /api. Do not add /v1 to the base URL because the SDK appends the configured API version to each request.

Work with responses

Successful requests return an ApiResponse object. You can access its decoded data, HTTP status, and response headers:

$response = $carList->automotive()->years();

$data = $response->data;
$status = $response->status;
$remaining = $response->header('X-RateLimit-Remaining');

The SDK throws typed exceptions for authentication, authorization, validation, rate limits, missing records, server errors, and network failures. Catch the narrowest exception that your application can handle meaningfully, and avoid displaying raw exception details to end users.

Next steps

• Review the complete API documentation.

• View the PHP SDK source and full reference.

• Create and manage API tokens from your Car List API dashboard.

• Report SDK-specific problems through the repository's issue tracker without including your API token.