Paintbase API

https://api.paintbase.app

Authentication

Authorization: Bearer <api_key>

Quota

Every authenticated response includes remaining_quota: the number of lookups left in the current calendar month (UTC). A lookup counts when it misses the local cache and is sent to the upstream provider, including not-found results and provider errors. Invalid requests and cached results do not count.

Each API key is also limited to its configured number of requests per minute (100/minute by default), and each client IP to 300 requests per minute. Exceeding either limit returns 429 Too Many Requests with a Retry-After header.

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" | null,
  "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" | null,
  "model": "string" | null,
  "color_code": "string" | null,
  "year": "string",
  "remaining_quota": number
}

For vehicle lookups, parenthesized (METALLIC) labels are ignored case-insensitively when parsing color_code. For example, Sea Grey (METALLIC) returns "color_code": "Sea grey"; real parenthesized paint codes are preserved.

When make or model is missing, display_name uses the provider’s displayName when available (for example, Chevrolet Captiva 2.0 D 4WD). Missing make and model fields remain null; they are not inferred from the display name. When both fields are available, the usual formatted name and year are used.

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
}