Paintbase API

https://api.paintbase.app

Authentication


Authorization: Bearer <api_key>

Endpoints

`GET /v1/test`

Used to test your api key.

`GET /v1/vehicle/:regno/:country`

Lookup vehicle data by registration number and country.

country must be one of: SE, NL, NO

Response `200 OK`


{
  "display_name": "string",
  "vin": "string",
  "license_plate": "string",
  "make": "string",
  "model": "string" | null,
  "color_code": "string" | null,
  "year": "string"
}

Response times

Vehicle lookups can sometimes take 30–40 seconds to complete. This is normal — upstream data providers are occasionally slow, and it does not indicate a failed request.

Plan your integration accordingly:

Set HTTP timeouts on your client and any proxy/server to at least 60 seconds
Design your UX for slow lookups: show a clear loading state, avoid duplicate submissions, and do not treat a long wait as an error by default

Use test plate TEST5 to simulate a slow response (~25 s) when validating your timeout and loading behavior.

Rate limits are enforced at the edge (Cloudflare). Contact support if you need a higher limit.

Errors

Common response codes:

400 Invalid input (for example VIN length or country code)
401 Missing or invalid API key
403 Out of credits
404 Vehicle or route not found
502 Upstream provider unavailable

Example error response


{
  "error": "Bad Gateway",
  "message": "Failed to reach the upstream data provider. Please try again later."
}

Test License Plates

Use these special registration numbers on GET /v1/vehicle/:regno/:country (any valid country code) to get deterministic hardcoded responses without hitting the upstream provider. Plates are case-insensitive.

Plate	Scenario	Status	Delay	Response
`TEST1`	Citroën	`200`	—	Citroën C3, color `KKN`
`TEST2`	Vehicle not found	`404`	—	Empty body
`TEST3`	Sparse data	`200`	—	Only `make: "Toyota"`, all other fields `null`
`TEST4`	Compound make	`200`	—	Mercedes-Benz E 220 D, color `197`
`TEST5`	Slow response	`200`	25 s	Volvo V60, color `717`
`TEST6`	Upstream server error	`500`	—	Empty body
`TEST7`	Out of quota	`403`	—	`{ "error": "Forbidden", "message": "Monthly query quota exceeded" }`

Example


GET /v1/vehicle/TEST1/SE
Authorization: Bearer <api_key>


{
  "display_name": "Citroen C3 (2020)",
  "vin": "VF7SAHMZ0EW512345",
  "license_plate": "TEST1",
  "make": "Citroën",
  "model": "C3",
  "color_code": "KKN (Elixir red)",
  "year": "2020"
}