> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remapdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UK VRM lookup API

> Look up UK registrations through REST or AI integrations using your shared lookup balance.

Normal UK VRM lookup through the API requires an active **API** or **MAX** subscription, an API key with `vdb_read` scope, and UK VRM entitlement. Trial API access also permits the designated test registrations described below. Free, Plus and Pro cannot use ordinary UK VRM registrations through REST or MCP; widget lookups are available on every plan, including Free with purchased credits. Free has no included allowance.

## Free test registrations

The **API** page and authenticated widget preview list the currently available test registrations. Staff manage this set; it is initially empty until registrations are supplied and saved data is published.

Send a listed plate to the same `POST /v2/vrm/uk/lookup` endpoint with your valid `vdb_read` API key and an idempotency key. Free, Plus, Pro and trial accounts can use this set. The same plates work in embedded widgets, with normal widget authentication and domain checks.

Test results have `is_test: true`, `consumption: "none"` and `cache.hit: true`. `usage` is `null` when your account has test-only access; otherwise it contains your normal usage. No included or purchased credits are reserved or spent. Rate limits still apply. Ordinary responses have `is_test: false`.

Customer test requests never call the lookup provider. Missing or invalidated test data returns `503 test_registration_unavailable`; retrying cannot trigger a paid lookup. Staff removal ends the exemption, and replaying an earlier test lookup is rejected. Normal access indicators and the usage endpoint continue to describe paid VRM access, not test access.

## Check access and limits

Call `GET /v2/subscription` with `Authorization: Bearer <API_KEY>`. Its `subscription` object includes:

| Field | Meaning |
| - | - |
| `api_access` | API access is enabled; this can also be true for catalog-only trials. |
| `catalog_profile` | `full` or `trial`. Trial access permits designated REST test registrations only; it does not enable normal UK VRM API or MCP access. |
| `mcp_access` | The active subscription permits AI integrations. |
| `uk_vrm_access` | The subscription permits UK VRM lookup through REST and MCP. |
| `uk_vrm_limit` | Current period included allowance plus unspent purchased top-ups; zero without UK VRM API access. |
| `uk_vrm_remaining` | Spendable included allowance plus available top-ups, after usage and reservations; zero without UK VRM API access. |

For example, 600 included lookups plus 100 unspent top-ups gives `uk_vrm_limit: 700`. After 6 included lookups, with no pending reservations, `uk_vrm_remaining` is 694. Top-ups carry over; the limit is not a monthly top-up allowance.

Call `GET /v2/vrm/uk/usage` for the current period's included allowance, used and reserved lookups, remaining included balance, purchased credits and reset time. **API → [UK vehicle lookup](https://app.remapdb.com/api/uk-vrm)** shows your access status and links to **UK VRM lookups**, where you can check your balance and activity. The current published allowance for the active plan applies immediately, including within an existing period. Used and reserved lookups remain counted; purchased credits are unchanged. The first upgrade from Free starts included allowance on the paid subscription anniversary.

## Look up a registration

Send `POST /v2/vrm/uk/lookup` with:

```http theme={null}
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: <unique-lookup-identifier>
```

```json theme={null}
{"vrm":"AB12CDE"}
```

Use a unique idempotency key of 8–128 letters, digits, `.`, `_`, `:` or `-` for each lookup. Keep the key unchanged when retrying the same lookup. Reusing it for a different registration returns `409`. A failed or not-found lookup stays final for that key; do not automatically create another paid attempt with a new key.

Results include normalized `vehicle` data, broad original attributes in `vehicle.details`, the available `engine` and tuning stages, cache status, consumption and usage. Reliable registration-only combustion data can include estimated stages and illustrative dyno curves. Hybrid combustion, electric-motor and combined figures remain separate; ambiguous component data does not receive tuning estimates.

## Shared balance

A successful uncached lookup consumes one monthly included lookup, then one purchased lookup if the included balance is exhausted. Cached results consume nothing. Failed and not-found lookups do not consume customer balance. Widgets, REST and MCP share the same account balance. Free accounts can buy top-ups and use them through widgets; top-ups do not unlock REST or MCP access. On a downgrade to Free, purchased credits remain usable in the widget, but any previous paid included allowance is unavailable.

With zero remaining balance, entitled accounts can still retrieve cached vehicles. Without normal UK VRM access, ordinary registration requests are denied, including cached results and idempotent replays. The designated REST test set remains available with a valid scoped API key. Purchased credits do not grant API access by themselves.

## Use through AI integrations

Connect [AI Integrations](https://docs.remapdb.com/api/ai-integrations.md) and use:

* `get_subscription` to check MCP and UK VRM access.
* `get_uk_vrm_usage` to check the shared balance without consuming a lookup.
* `lookup_uk_vrm` with `vrm`, `idempotency_key` and optional `language`.

MCP retains its paid authorization requirements, including for test registrations. Its normal cache, quota and retry rules are unchanged. Use the same idempotency key if continuing the same account lookup through either interface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.