Developer docs

Decode a VIN with one authenticated request.

Create an account, generate an API key, and call the VIN endpoint with Bearer authentication. Public docs cover the basics; account pages show your actual keys, usage, and billing state.

Get an API key View pricing Download OpenAPI YAML

Quick start curl

curl -X GET "https://vinstate.com/api/v1/vin/1HGCM82633A004352" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer sk-your-api-key"

Endpoint

GET /api/v1/vin/{vin}

Pass a 17-character VIN in the path. The server trims, uppercases, validates, and decodes it.

Authentication

Bearer API Key

Send Authorization: Bearer sk-your-api-key with every API request.

Billing

1 lookup = 1 request

Successful lookups use included monthly requests first. Overage uses credits at 1 credit = $0.01.

Success response

Example payload

{
  "success": true,
  "request_id": "8d5578ad-27c0-46b8-b0f1-5e6f154ca8d6",
  "data": [
    {
      "vin": "1HGCM82633A004352",
      "decoded": {
        "vehicle": {
          "car": "2003 Honda Accord EX"
        },
        "wmi": {
          "make": "Honda"
        }
      }
    }
  ],
  "meta": {
    "billed": true,
    "funding_source": "included",
    "included_requests_charged": 1,
    "charged_credits": 0
  }
}

Error codes

Common failures

HTTP 401 Not billed

invalid_api_key

Missing or unknown API key.

HTTP 403 Not billed

api_key_inactive / user_inactive

The key or account cannot authenticate requests.

HTTP 429 Not billed

rate_limit_exceeded

The API key exceeded the per-minute limit.

HTTP 422 Not billed

invalid_vin

The normalized VIN failed validation.

HTTP 402 Not billed

insufficient_credits

No included quota or credits remained.

HTTP 404 Not billed

vin_not_found

No VIN record was found.

HTTP 503 Not billed

service_unavailable

The VIN lookup service is temporarily unavailable.

Examples

curl, JavaScript, PHP

curl

curl -X GET "https://vinstate.com/api/v1/vin/1HGCM82633A004352" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer sk-your-api-key"

JavaScript

const response = await fetch(
  "https://vinstate.com/api/v1/vin/1HGCM82633A004352",
  {
    headers: {
      "Accept": "application/json",
      "Authorization": "Bearer sk-your-api-key",
    },
  }
);

const data = await response.json();

PHP

<?php
$ch = curl_init("https://vinstate.com/api/v1/vin/1HGCM82633A004352");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Authorization: Bearer sk-your-api-key",
    ],
]);

$response = curl_exec($ch);
curl_close($ch);