Start here for the shared architecture, authentication flow, request patterns, and service hosts used across VINquery.com APIs.
API access now uses API Consumers and JWT bearer tokens.
Create an API Consumer in your VINquery.com dashboard for each server-side application. Each API Consumer has:
Keep the Client Secret secure on your server. Before calling an API, request a JWT bearer token from the VINquery Identity service.
API Consumer credentials must only be used by trusted server-side applications. Do not expose Client Secrets in browser-based JavaScript, mobile applications, public source code, or other untrusted environments.
VINquery.com provides a unified suite of automotive APIs for VIN decoding and correction, image and object recognition, license plate recognition, and deterministic business decision support through DecisioQ. Client systems access these capabilities through RESTful API endpoints.
All VINquery.com APIs are secured with JSON Web Tokens (JWTs). The centralized identity service at identity.vinquery.com authenticates API Consumers and issues audience-specific JWT access tokens. Each protected API validates the token before processing a request.
API Consumers must not call VINquery.com APIs directly from browser-side JavaScript, mobile application code, or other publicly distributed client code. Every integration must use a trusted server-side proxy, backend service, gateway, or adapter. The server-side component securely stores the API Consumer credentials, obtains JWTs from identity.vinquery.com, and forwards authenticated requests to the appropriate VINquery.com API.
A key feature of the REST architecture is stateless communication between client and server. Each request contains the information and authorization required for that transaction, the server processes the request and returns a response, and the transaction is completed independently.
To maintain reliability and stability in demo and production environments, VINquery.com enforces API call efficiency guidelines. We continually monitor API usage to support effective load balancing and will contact developers when an integration places an unnecessary burden on the system. Applications must not poll for service status more than once every 15 minutes.
Every API integration must use the following server-side flow:
The Client Secret and JWT must remain on the trusted server side. They must never be embedded in HTML, browser JavaScript, desktop or mobile binaries, public repositories, URLs, query strings, or client-visible logs.
Before calling a protected VINquery.com API, the server-side proxy authenticates the API Consumer with identity.vinquery.com and requests a JWT token for the target API.
Authenticated API requests must include the issued token in the following header:
Authorization: Bearer <access_token>
JWTs are audience-specific. A token issued for one VINquery.com API must not be used to call another API. The server-side proxy should securely cache and reuse a valid token until shortly before it expires, then obtain a new token from the identity service.
VINquery.com APIs process several types of resources and request data:
Image-processing services normalize submitted images as required by their recognition engines. DecisioQ requests must conform to the applicable decision and mapping-profile contracts documented for the selected decision endpoint.
Requests use HTTP GET or HTTP POST according to the selected endpoint. API request and response bodies use JSON unless an individual API endpoint explicitly documents another format.
| REST API | HTTP Type | Base URL |
| VINdecode API 3.0 | GET | https://ws.vinquery.com/vindecode/v3 |
| VINfix API 3.0 | GET | https://www.recognition.ws/vinfix/v3 |
| VINocr API 3.0 | POST | https://www.recognition.ws/vinocr/v3 |
| VINbarcode API 3.0 | POST | https://www.recognition.ws/vinbarcode/v3 |
| LPR API 3.0 | POST | https://lpr.recognition.ws/v2 |
| DecisioQ API 1.0 | GET/POST |
|
All endpoints in the offering require a valid JWT token and must be called through the API Consumer's server-side proxy.
VINquery.com APIs may return the following HTTP status codes:
| HTTP Status Code | Description |
| 200 | Request completed successfully. |
| 400 | The request is invalid or required data is missing. |
| 401 | Authentication failed, the JWT token is missing or invalid, or the JWT token has expired. |
| 403 | The authenticated API Consumer is not authorized to access the requested API or resource. |
| 404 | The requested endpoint or resource was not found. |
| 429 | The permitted request rate or usage limit has been exceeded. |
| 500 | An internal server error occurred. |