Paintbase API

https://api.paintbase.app

Authentication

Authorization: Bearer <api_key>

Quota

Every authenticated response includes remaining_quota: the number of billable lookups left in the current calendar month (UTC). Only successful lookups that return a color code count against your monthly quota.

Endpoints

GET /v1/test

Used to test your api key.

Response 200 OK

{
  "id": "string",
  "label": "string",
  "created_at": "string",
  "remaining_quota": number
}

GET /v1/vehicle/:vin

Lookup vehicle data by VIN. No country code required.

• VIN must be 11–17 alphanumeric characters
• Example: GET /v1/vehicle/VSA63827413144890

Response 200 OK

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

GET /v1/vehicle/:regno/:country

Lookup vehicle data by registration number and country.

• country must be one of: SE, NL, NO
• If :regno looks like a VIN (11–17 alphanumeric characters), the lookup is treated as a VIN lookup and the country is ignored

Response 200 OK

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

Response times

Vehicle lookups usually complete quickly, but can sometimes take 30–40 seconds — and in the worst case up to 2–3 minutes. This is normal — upstream data providers are occasionally slow, and a long wait does not indicate a failed request.

Plan your integration accordingly:

• Set HTTP timeouts on your client and any proxy/server to at least 4 minutes (240 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
• Do not retry while a lookup is still in flight. Lookups are safe to retry after a failure, and repeat lookups for a previously resolved vehicle return instantly from cache

Use test plate TEST5 to simulate a slow response (~25 s), or TEST8 for the worst-case ~3 min delay, 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
• 504 Upstream provider did not respond in time — safe to retry later

Example error response

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

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.

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",
  "remaining_quota": 42
}