---
title: "CarValue"
description: "The CarValue tool over the API: value a car by VIN or by make and model, and read a VIN from a photo. Scope: carvalue, granted per contract, and the key’s account must also be granted CarValue."
canonical: "https://thecarapi.com/docs/carvalue"
contract_version: "2026-10-05"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/carvalue.md"
---

# CarValue

The CarValue tool over the API: value a car by VIN or by make and model, and read a VIN from a photo. Scope: carvalue, granted per contract, and the key’s account must also be granted CarValue.

## GET /api/carvalue/access

Whether the key’s account may use CarValue.

**Scope:** `carvalue`

### Example requests

```http
GET https://api.thecarapi.com/api/carvalue/access
```

### Example response

```json
{
  "success": true
}
```

**Notes.** Needs the key to be linked to a portal account that has been granted the tool in the admin; a key without that grant gets 403 even with the scope. Responses are the tool’s own body ({ success: true, ... } or { success: false, message }) — the same backend the portal page uses — so they carry no contract_version envelope. Read X-Request-ID from the header.

## GET /api/carvalue/options

What the valuation form can offer: makes, a make’s models, or a model’s years, engines, fuels, gearboxes and countries.

**Scope:** `carvalue`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `brand_id` | Query string | string | no | `12` | /api/carvalue/options -> makes | With it, that make’s models. |
| `model_id` | Query string | string | no | `340` | /api/carvalue/options?brand_id=12 -> models | With brand_id, the model’s years, engines, fuels, gearboxes and countries. |

### Example requests

```http
GET https://api.thecarapi.com/api/carvalue/options
```

```http
GET https://api.thecarapi.com/api/carvalue/options?brand_id=12
```

```http
GET https://api.thecarapi.com/api/carvalue/options?brand_id=12&model_id=340
```

### Example response

```json
{
  "success": true,
  "makes": [
    {
      "id": 12,
      "name": "BMW"
    }
  ]
}
```

**Notes.** Read from the data the valuation holds, so every option offered has prices behind it.

## GET /api/carvalue/valuation

What a car is worth, by VIN or by make and model.

**Scope:** `carvalue`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `vin` | Query string | string | no | `WBA8E9G50GNU12345` | The car’s VIN, or POST /api/carvalue/scan. | Decoded to make, model, year, engine, fuel and gearbox, which then override those parameters. |
| `brand_id / model_id` | Query string | string | no | `12 / 340` | /api/carvalue/options | The make and model, when no VIN is given. |
| `year` | Query string | integer | no | `2019` | The car being valued. | Registration year. |
| `year_flex` | Query string | integer | no | `1` | How wide a range you want. | Years either side of year for the range block. Default 1, maximum 5. |
| `engine` | Query string | number | no | `2.0` | The car being valued. | Litres. |
| `engine_flex` | Query string | number | no | `0.2` | How wide a range you want. | Litres either side of engine. Default 0.2, maximum 1. |
| `fuel / gearbox` | Query string | string | no | `Diesel / Automatic` | /api/carvalue/options | Fuel, and Automatic or Manual. |
| `condition` | Query string | enum | no | `normal` | normal, damaged or any. | Default normal. |
| `mileage` | Query string | integer | no | `120000` | The odometer in km. | Adjusts the estimate. |
| `country` | Query string | string | no | `DE` | /api/carvalue/options | The car’s country. |
| `trend_months` | Query string | integer | no | `12` | How much history to chart. | Maximum 24. |
| `offers_kind / offers_offset` | Query string | string / integer | no | `auction / 24` | Your offer list state. | Limit the reference offers to one kind of price, and page through them 24 at a time. |

### Example requests

```http
GET https://api.thecarapi.com/api/carvalue/valuation?vin=WBA8E9G50GNU12345&mileage=120000
```

```http
GET https://api.thecarapi.com/api/carvalue/valuation?brand_id=12&model_id=340&year=2019&fuel=Diesel
```

### Example response

```json
{
  "success": true,
  "valuation": {
    "exact": {},
    "range": {},
    "countries": [],
    "trend": {},
    "time_to_sell": null,
    "offers": []
  },
  "vehicle": {
    "vin": "WBA8E9G50GNU12345",
    "make": "BMW",
    "model": "320d",
    "year": 2019
  }
}
```

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `valuation` | object | Retail, auction and buy-now prices, per country, trend, time to sell, and reference offers 24 per page from offers_offset — the same document as /api/market/valuation, plus the offers. |
| `vehicle` | object \| null | What the VIN decoded to; null without a VIN. |

**Notes.** 422 when the VIN decoded but not to a model: vehicle carries what was read, so retry with brand_id and model_id. Needs the key to be linked to a portal account that has been granted the tool in the admin; a key without that grant gets 403 even with the scope. Responses are the tool’s own body ({ success: true, ... } or { success: false, message }) — the same backend the portal page uses — so they carry no contract_version envelope. Read X-Request-ID from the header.

## POST /api/carvalue/scan

Read VINs from one photo or camera frame.

**Scope:** `carvalue`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `body` | JSON body | binary | yes | `@frame.jpg` | A camera frame or photo of the VIN plate or paperwork. | The image itself as the request body, Content-Type image/jpeg or image/png, at most 1 MB (413 above). |

### Example requests

```bash
curl -sS -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: image/jpeg" --data-binary @frame.jpg "https://api.thecarapi.com/api/carvalue/scan"
```

### Example response

```json
{
  "success": true,
  "reads": [
    {
      "vin": "WBA8E9G50GNU12345",
      "quad": [
        [
          0.21,
          0.44
        ],
        [
          0.78,
          0.44
        ],
        [
          0.78,
          0.52
        ],
        [
          0.21,
          0.52
        ]
      ],
      "votes": 2
    }
  ]
}
```

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `reads[]` | object[] | Up to three VINs, best first, each with quad (where it is printed, as fractions of the image size, or null) and votes (how many agreeing reads a scanner should collect before accepting it). |

**Notes.** A 429 means the scanner is busy: send the next frame after Retry-After. A busy answer is not charged to your quota.