API Documentation
One API response. Every verification signal your underwriters need.
Send a VIN and jurisdiction code. Receive a structured JSON response with eight signal categories, confidence scores, and a composite risk score. No manual lookup, no document upload, no integration complexity.
How It Works
Three-stage reconciliation pipeline
GoodToKnow queries multiple authoritative data sources in parallel, applies cross-check reconciliation, and returns a confidence-weighted signal set within a single API round-trip.
Source Ingestion
Upon receiving a VIN and country code, the system dispatches concurrent queries to national vehicle registries, insurance claim databases, and manufacturer recall records. Query routing is jurisdiction-aware: an EE plate routes to the Estonian ARK database and relevant EU cross-border sources.
Cross-Check Reconciliation
Returned records are reconciled against each other. Odometer readings across MOT records, service history, and insurance claims are subjected to statistical consistency checks. Ownership chain entries are compared across sources to surface discrepancies that indicate manipulation or registration errors.
Signal Assembly and Scoring
Each of the eight signal categories receives a status classification (verified, flagged, unavailable) and a confidence score based on source agreement. The composite risk score (0-100) weights the signal set according to the vehicle's jurisdiction and age profile. The full response is returned as structured JSON.
Integration Architecture
The API is REST over HTTPS with JSON request and response bodies. Authentication uses per-integration API keys issued at registration. Responses are returned within 500ms at the 95th percentile. The endpoint supports both single-VIN and batch verification modes. Webhook delivery is available on the Scale tier.
API Reference
Request and response schema
The full verification response returns all eight signals in a single call. No field selection required on the Start tier.
// POST https://api.goodtoknow.net/v1/verify // Content-Type: application/json // Authorization: Bearer <your-api-key> { "vin": "WBA3A5C57DF123456", "country_code": "EE", "signals": [ "registration", "odometer", "ownership", "incidents", "total_loss", "finance", "recall", "residual_value" ] }
{
"risk_score": 72,
"signals": [
{
"name": "registration",
"status": "verified",
"detail": "Active registration. No stolen flag.",
"confidence": 0.98
},
{
"name": "odometer",
"status": "verified",
"detail": "Consistent progression across 6 records.",
"confidence": 0.94
},
{
"name": "finance",
"status": "flagged",
"detail": "Active finance agreement on record.",
"confidence": 0.91
}
],
"metadata": {
"timestamp": "2026-05-14T09:22:31Z",
"jurisdiction": "EE",
"latency_ms": 387
}
}
// HTTP 400 - Invalid request { "error": "invalid_vin", "message": "VIN must be 17 alphanumeric characters." } // HTTP 401 - Authentication failure { "error": "unauthorized", "message": "API key is missing or invalid." } // HTTP 429 - Rate limit exceeded { "error": "rate_limit_exceeded", "message": "Monthly lookup quota reached.", "reset_at": "2026-06-01T00:00:00Z" } // HTTP 404 - VIN not found in available registries { "error": "vin_not_found", "message": "No records found for this VIN in covered jurisdictions." }
Data Coverage
Built for EU motor data infrastructure
GoodToKnow connects to national vehicle registries, insurance claim databases, and manufacturer recall systems across Estonia, Latvia, Lithuania, and expanding EU jurisdictions.
Current Coverage: EE, LV, LT
Full signal coverage for vehicles registered in Estonia, Latvia, and Lithuania. The EE registry integration runs on Estonia's X-Road data exchange layer, providing direct access to the ARK vehicle database. LV and LT connect through national registry APIs.
Expanding EU Jurisdiction Coverage
Scale tier subscribers access extended EU jurisdiction coverage as additional country integrations complete verification and quality testing. Enterprise deployments can request prioritization of specific jurisdictions for custom deployment timelines.
What GoodToKnow does not do
GoodToKnow is not a full vehicle inspection service, a live tracking or telematics feed, or a replacement for a physical condition report. The API verifies documented history from registry and claims sources. It does not assess mechanical condition, produce a valuation certificate, or source data from outside EU regulatory jurisdictions. If your use case requires real-time telemetry, on-site inspection, or non-EU vehicle records, this is not the right tool.
Early Access
Integrate in a day, not a quarter
REST API, JSON responses, under 500ms at p95. Apply for early access and we will set you up with sandbox credentials.