# PlateToVIN API — Full Reference

> A single, predictable REST API for US vehicle data. Turn a license plate into a VIN, read a plate straight from a photo, decode a VIN into a full specification, check open safety recalls, and serve catalog-grade vehicle images — all with plain HTTP and JSON. No SDK required.
>
> This file mirrors the hand-written documentation at https://platetovin.com/doc and must be kept in sync with it.

## Authentication

The JSON endpoints authenticate with an API key sent in the `Authorization` header:

    Authorization: sk_live_your_api_key_here

Keys are on your API Keys page after signing in at https://platetovin.com. Keep the key secret — send it only from your server. The Vehicle Images API uses a different, referer-based model that is safe for the browser (see Vehicle Images below).

## Base URLs

- JSON API: `https://platetovin.com/api`
- Vehicle Images: `https://vehicle-images.platetovin.com`

## License Plate to VIN — POST /api/convert

Convert a single US license plate and state into a VIN, with a quick decode of the core vehicle attributes. Covers all 50 states and DC.

Body parameters:
- `plate` (string, required) — the license plate characters, e.g. `7ABC123`
- `state` (string, required) — two-letter US state code, e.g. `CA`, `TX`, `NY`

Example:

    curl https://platetovin.com/api/convert \
      -H "Authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"state": "CA", "plate": "7ABC123"}'

Response fields:
- `success` (boolean)
- `vin` (object) — the matched VIN and quick decode:
  - `vin` (string) — the 17-character VIN
  - `name` (string) — e.g. `2011 Mercedes-Benz M-Class`
  - `year`, `make`, `model`, `trim`, `style`, `engine`, `fuel`, `driveType`, `transmission` (strings)
  - `GVWR` — gross vehicle weight rating in lbs (integer); an NHTSA GVWR class string (e.g. `Class 3: 10,001 - 14,000 lb`) for vehicles with limited decode data; null when unavailable
  - `color` (object) — `name` (e.g. `Silver`) and `abbreviation` (e.g. `SIL`), where known

Example response:

    {
      "success": true,
      "vin": {
        "vin": "4JGBB8GB9BA648907",
        "name": "2011 Mercedes-Benz M-Class",
        "year": "2011",
        "make": "Mercedes-Benz",
        "model": "M-Class",
        "trim": "ML 350",
        "style": "SUV",
        "engine": "3.5L V6 DOHC 24V",
        "fuel": "Gasoline",
        "driveType": "AWD",
        "transmission": "Automatic",
        "GVWR": 6063,
        "color": { "name": "Silver", "abbreviation": "SIL" }
      }
    }

Billing: plate lookups are billed per request and cached for 7 days — repeat lookups of the same plate within that window are free. No charge when a plate can't be resolved (404).

## License Plate OCR — POST /api/ocr

Read a US license plate from a photo. Plates are detected in full scenes (no cropping needed), characters are read and corrected against the issuing state's plate format. Returns the serial with ranked candidate states, per-character confidences and the bounding box. **Uploaded images are never stored.**

OCR never runs a VIN lookup by itself. When you want the VIN, take `plate` and `state.code` from a trusted read and call `/api/convert` explicitly. Check `trusted` before looking up — `low_confidence` reads carry `trusted: false` and should be treated as suggestions.

Body parameters:
- `image` (string | file, required) — JPEG or PNG, max 15 MB. Base64 string (data: URIs accepted) in JSON, or multipart file upload in the `image` field.
- `state_suggestions` (string[], optional) — ordered guesses for the issuing state, most likely first, e.g. `["NJ", "NY"]`. A prior, not a filter. Comma-separated string also accepted; unknown codes are ignored and echoed in `ignored_suggestions`.

Statuses:
- `ok` — confident read; `plate.trusted` is `true`, safe to feed into /api/convert
- `low_confidence` — best guess with `trusted: false` (blur, glare, angle)
- `no_plate_found` — no license plate detected in the image
- `non_us_plate` — likely Canadian or Mexican; only US jurisdictions supported (50 states, DC, territories)

Response fields (main ones):
- `success` (boolean), `status` (string), `request_id` (string)
- `image` (object) — `width`, `height` of processed image (coordinate space for `bbox`)
- `plate` (object, null when no_plate_found):
  - `plate` (string) — separator-free serial corrected against the state's format; the exact string to use for lookups
  - `plate_display` (string) — with separators, e.g. `ZZC-31V`
  - `confidence` (float 0–1), `char_confidences` (float[]), `bbox` ([x_min, y_min, x_max, y_max]), `detection_confidence` (float)
  - `state` (object) — `code`, `name`, `confidence`
  - `state_candidates` (object[]) — up to 5 ranked alternatives, each with its own `plate` as corrected under that state's format; retry /api/convert with these when the top state misses
  - `plate_type` (string) — `passenger`, `commercial`, `motorcycle`, … or `vanity_or_unrecognized`
  - `is_vanity_likely` (boolean), `warnings` (string[]), `trusted` (boolean)
- `additional_plates` (object[]) — other plates in multi-vehicle scenes
- `ignored_suggestions` (string[])

Billing: plans include a monthly OCR call allowance (unlimited on enterprise). Past the allowance, calls bill per call at the plan's overage rate, or are refused with 403 on plans without overage. Every processed image counts, whatever its status; rejected uploads and service errors don't.

Accuracy methodology: https://platetovin.com/license-plate-ocr/methodology

## VIN Decoding — POST /api/vin-lookup

Decode a VIN into a complete vehicle specification. Requires a plan that includes VIN decoding.

Body parameters:
- `vin` (string, required) — a 15–17 character VIN, e.g. `WBAAV53431JR78115`

Response: `data` contains the full specification. Fields without data for a given vehicle are null. Object groups:
- `year · make · model · trim · body_type` — core identity
- `trim_description · platform_code · domestic_import · manufacturer_country` — extended identity
- `msrp · base_invoice` — original USD pricing
- `engine_drivetrain` — `cylinder_layout` (I6, V8…), `engine_displacement` (litres), `engine_type` (gas/diesel/hybrid/electric), `fuel_type`, `valves`, `valve_timing`, `cam_type`, `drivetrain`, `transmission`
- `performance` — `horsepower`, `horsepower_rpm`, `torque` (lb-ft), `torque_rpm`, `zero_to_sixty_time`
- `economy` — `fuel_tank_size` (US gal), `mpg_city/highway/combined`, `range_city/highway/combined` (EVs report range)
- `body` — `gross_weight` (GVWR in lbs; an NHTSA class string on limited-data decodes), `curb_weight` (lbs), `length`, `width`, `height`, `wheelbase` (in), `ground_clearance`, `turning_circle`, `doors`, `seats`, `towing_capacity` (maximum towing capacity in lbs, null when the vehicle has no tow rating)
- `warranty` — `basic`, `drivetrain`, `roadside`, `rust` (e.g. `4 yr./ 50000 mi.`)
- `colors` — `exterior` and `interior` maps of color name → "R,G,B"
- `features` — `suspension`, `front_seats`, `rear_seats`, `features`, `safety` (string arrays)

## Safety Recalls — POST /api/recalls

Open NHTSA safety recall campaigns for a vehicle, newest first. Send a VIN (decoded in-house to year/make/model) or query by make/model/year directly. **Free per call** on plans that include recalls — no credit charge, no monthly cap.

Note: recall campaigns apply to a vehicle configuration (year/make/model), not an individual VIN. Whether a specific VIN has been remedied is manufacturer-held data.

Body parameters:
- `vin` (string) — 15–17 character VIN; not required when make/model/year supplied
- `make`, `model` (strings), `year` (integer) — together, an alternative to `vin`

Response fields:
- `success` (boolean)
- `data` — `vin` (or null), `year`, `make`, `model`, `count`, and `recalls[]`:
  - `campaign_number` (e.g. `22V412000`), `report_date` (YYYY-MM-DD), `component`, `summary`, `consequence`, `remedy`, `notes`, `manufacturer`
  - `park_it` (true = NHTSA advises do not drive), `park_outside` (fire risk), `over_the_air_update`

## Vehicle Images — GET vehicle-images.platetovin.com/image

Catalog-grade vehicle images straight from an `<img>` tag. Transparent PNGs at fixed, consistent framing. Referer-based auth: whitelist your domains in the dashboard, then hotlink the URLs directly — no API key in the browser.

Licensing: without a licence (including unauthenticated requests), images are served as small, watermarked previews for evaluation only. Full-resolution, watermark-free images require an active plan with vehicle images enabled; licensed customers may hotlink via the API or download and self-host the images for use in their own applications and listings. When the licence ends, downloaded images must be deleted. Reselling/redistributing images as standalone assets or removing watermarks is never permitted. PlateToVIN uses automated systems to detect unlicensed use and may request proof of licence; unlicensed use can lead to suspension and legal action. See https://platetovin.com/terms (Section 2.3).

Query parameters:
- `search` (string, required) — make and model, e.g. `BMW 3 Series`
- `year` (integer, required) — model year; newer-than-available years fall back to the closest model year
- `angle` (string) — `front`, `front_angle`, `side`, `rear`, `rear_angle` (default `front_angle`)
- `color` (string) — `base`, `silver`, `black`, `white`, `gray`, `red` (default `base`)
- `size` (string) — `large`, `medium`, `small` (default `large`)
- `tier` (string) — set to `free` for the public, no-auth watermarked preview: front angle only, low-resolution, forced background; all other parameters are ignored and a vehicle without a generated preview returns 404. Omit for licensed full-resolution images.

Free preview: anyone can pull a watermarked preview with `tier=free` (no referer or key), or browse and download previews at https://platetovin.com/car-images.

Example:

    <img src="https://vehicle-images.platetovin.com/image?search=BMW+3+Series&year=2022&angle=front_angle&color=red" alt="2022 BMW 3 Series"/>

## Errors

Failures return `success: false` with a human-readable `message` and a standard HTTP status:
- `200` — success; note validation failures may also return 200 with `success: false` — always check the `success` flag
- `402` — payment required: balance too low; top up or enable auto-deposit
- `403` — forbidden: no billing plan, account suspended, endpoint not in plan, or monthly limit reached without overage
- `404` — no result for the supplied plate or VIN
- `413` — uploaded image exceeds 15 MB (OCR)
- `422` — upload couldn't be decoded as an image (OCR)
- `503` — service temporarily unavailable; safe to retry shortly

## Billing & limits

API access requires an active billing plan (https://platetovin.com/plans). Plate lookups bill per request with a 7-day cache. VIN decoding and vehicle images are included on plans that offer them, up to any monthly ceiling. Recall lookups are free per call. OCR has a monthly allowance with per-call overage.

## Free tools (no account)

- Recall check by plate or VIN: https://platetovin.com/recalls-by-plate
- VIN validator & check digit calculator: https://platetovin.com/vin-validator
- Plate formats by state: https://platetovin.com/license-plate-lookup