https://vinchex.com/api
The VinChex API provides endpoints for managing VINs and billing reports. The API uses OAuth 2.0 client credentials flow for authentication and returns JSON responses.
The API uses OAuth 2.0 client credentials grant type for authentication. You need to obtain an access token before making requests to protected endpoints.
/oauth/token
Obtain an access token using client credentials.
| Parameter | Type | Required | Description |
|---|---|---|---|
| grant_type | string | Yes | Must be "client_credentials" |
| client_id | string | Yes | Your client ID |
| client_secret | string | Yes | Your client secret |
curl -X POST "https://vinchex.com/api/oauth/token" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "your_client_id",
"client_secret": "your_client_secret"
}'{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"expires_at": 1691766000,
"company_id": 123,
"company_name": "Example Company"
}/oauth/revoke
Revoke an access token.
curl -X POST "https://vinchex.com/api/oauth/revoke" \
-H "Content-Type: application/json" \
-d '{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}'All protected endpoints require a valid Bearer token in the Authorization header:
Authorization: Bearer your_access_token
The VinState data type represents the processing status of a VIN in the system. It is an integer-backed enum with the following values:
| Value | Label | Description |
|---|---|---|
| 0 | Inactive | VIN has been deactivated or removed from processing |
| 1 | Pending | VIN is queued for lienholder lookup processing |
| 2 | In Progress | VIN lienholder lookup is currently being processed |
| 3 | Completed | VIN lienholder lookup completed successfully |
0, 1, 2, 3) in query parameters and request bodies"Inactive", "Pending", "In Progress", "Completed")The Priority data type represents the validation priority level of a VIN in the system. It is an integer-backed enum with the following values:
| Value | Label | Description |
|---|---|---|
| 0 | Low | Low Risk |
| 1 | Medium | Medium Risk |
| 2 | High | High Risk |
/vins
Get a paginated list of VINs with optional filtering.
Note: At least one of vin or state parameter is required.
| Parameter | Type | Required | Description |
|---|---|---|---|
| vin | string | Required when state is not present | VIN to search for |
| state | integer | Required when vin is not present | Filter by VinState (only 1=Pending, 3=Completed accepted) |
| per_page | integer | No | Results per page (1-1000, default: 100) |
curl -X GET "https://vinchex.com/api/vins?vin=1HGBH41&state=1&per_page=20" \
-H "Authorization: Bearer your_access_token"{
"success": true,
"message": "VINs retrieved successfully",
"data": [
{
"id": 1234,
"vin": "1HGBH41JXMN109186",
"state": 1,
"registered_state": "CA",
"priority": 2,
"title_date": null,
"lienholder": null,
"restricted_state": false,
"data_found": false
},
{
"id": 1235,
"vin": "1HGBH41KXMN109187",
"state": 1,
"registered_state": "TX",
"priority": 0,
"title_date": "2020-01-01",
"lienholder": "Chase Auto Finance",
"restricted_state": true,
"data_found": true
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 98,
"last_page": 5,
"from": 1,
"to": 20
}
}/vins/add
Add multiple VINs to the system. VINs are queued for asynchronous processing. Creates new VINs or updates existing ones to VinState PENDING.
| Field | Type | Required | Description |
|---|---|---|---|
| vins | array | Yes | Array of VIN objects |
| vins[].vin | string | Yes | VIN string (10-17 chars, alphanumeric excluding I, O, Q) |
| vins[].lienholder | string | Yes | Lienholder name (max 255 chars, case-insensitive lookup) |
| vins[].origination_date | date | No | Date when the VIN originated (format: YYYY-MM-DD) |
curl -X POST "https://vinchex.com/api/vins/add" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"vins": [
{
"vin": "1HGBH41JXMN109186",
"lienholder": "Chase Auto Finance",
"origination_date": "2025-09-15"
},
{
"vin": "2T1BURHE0JC123456",
"lienholder": "Wells Fargo Auto",
"origination_date": "2025-09-20"
}
]
}'{
"success": true,
"message": "VINs have been queued for processing",
"processing_type": "queued",
"total_vins": 2,
"size": "0.5 KB"
}origination_date is now required for all VIN submissionsoptions.ignore_duplicates: true to skip duplicates/vins/remove
Deactivate VINs by setting their state to VinState INACTIVE
curl -X PATCH "https://vinchex.com/api/vins/remove" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"vins": [
"1HGBH41JXMN109186",
"2T1BURHE0JC123456"
]
}'{
"success": true,
"message": "VINs deactivated successfully",
"data": {
"deactivated_count": 2,
"deactivated_vins": [
{
"id": 1236,
"vin": "1HGBH41JXMN109186",
"state": 0,
"state_label": "Inactive",
"deactivated_at": "2024-01-15T14:30:00Z"
},
{
"id": 1237,
"vin": "2T1BURHE0JC123456",
"state": 0,
"state_label": "Inactive",
"deactivated_at": "2024-01-15T14:30:00Z"
}
],
"not_found": [],
"already_inactive": []
}
}The API returns consistent error responses with appropriate HTTP status codes:
{
"success": false,
"message": "Validation failed",
"errors": {
"vin": ["The vin field is required."]
}
}{
"success": false,
"message": "Company not found in authentication context"
}{
"success": false,
"message": "Resource not found"
}{
"success": false,
"message": "An error occurred while processing the request",
"error": "Detailed error message"
}For API support, questions, or feature requests, please contact our development team.
Additional technical documentation and guides are available in the project repository.
Rate limiting is enforced to ensure fair usage. Monitor your usage and implement appropriate throttling.