Carrier Observation by VIN

The Carrier Observation API provides carrier information based on sightings in the GenLogs Sensor network, FMCSA Inspection Data, and other observation data as available.

The search is performed strictly using VIN-based matching rather than USDOT numbers, ensuring that the returned observations correspond to the specific vehicle associated with the provided VIN.

Authentication

Include the following headers in your requests:

• Access-Token: The access token obtained from the "Create Acess Token" endpoint.

• x-api-key: The API key provided by Genlogs. This header must be included in the request.

Permissions

The carrier-observations-vin-endpoint permission is required to access this endpoint.

Endpoint

• URL: https://api.genlogs.io/visual_sightings/carrier-observations/vin

• Method: GET

Query Parameters

You can perform up to two concurrent calls at one time.

• vin (string, Required): either a single VIN or a comma separated list of up to 50 VIN identifiers.

• page (integer, Optional): Page number of results to return.

• page_size (integer, Optional): Number of results per page.

Response

• 200 OK: A JSON object containing the a list of observations and pagination details.

• 400 Bad Request: If required parameters are missing or invalid.

• 401 Unauthorized: If the authentication credentials (access-token or x-api-key) are missing or incorrect.

• 403 Forbidden: If the permission has not been added to your user.

• 500 Internal Server Error: If there is an issue on the server that prevents processing the request.

Response Body:

For each provided VIN, you will receive a list of sightings including usdot_number, time_captured, vin, mc_number, source and type

Imputed Fields

Fields is_usdot_imputed, is_mc_imputed and is_vin_imputed represent whether the corresponding field value was inferred or auto-filled by the system rather than directly observed.

These fields are boolean and help differentiate between raw observations and system-generated estimations.

*this feature requires the carrier-observations-imputed-fields permission access.

observations (array of Observations objects): List of observations for the search.

• usdot_number: (string) The USDOT number for the carrier.

• time_captured: (string) The timestamp when the data was captured.

• mc_number: (string) Motor Carrier number for the carrier.

• vin: (string) Vehicle Identification Number.

• source: (string) Source of the observation.

• type: (string) Type of the observation (e.g., crash, inspection, detection).

  • 'Crash' and 'Inspection' records are from the FMCSA, 'Detection' records are from GenLogs sensors.

• is_usdot_imputed: (boolean) Indicates if the USDOT number was system-inferred.

• is_mc_imputed: (boolean) Indicates if the MC number was system-inferred.

• is_vin_imputed: (boolean) Indicates if the VIN was system-inferred.

Request Example:

curl -X GET 'https://api.genlogs.io/visual_sightings/carrier-observations/vin?vin=3AKJHHFG4RSUW1128' \
-H 'Access-Token: {access_token}' \
-H 'x-api-key: {your_api_key}' \
-i

Get carrier observations by VIN

get

Returns a list of observations associated with the provided VIN. The VIN parameter is required. Requires valid authentication via Access-Token and x-api-key.

Authorizations

AccessTokenAuth & ApiKeyAuth

Access-TokenstringRequired

JWT provided directly in the Access-Token header.

x-api-keystringRequired

API key provided by GenLogs.

Query parameters

vinstringRequired

Vehicle Identification Number (VIN). Must be a non-empty value.

Example: 3AKJHHFG4RSUW1128

pageinteger · min: 1Optional

Page number for pagination.

Example: 1

page_sizeinteger · min: 1 · max: 500Optional

Number of results to return per page.

Example: 100

Responses

200

Successful retrieval of observations.

application/json

400

Bad Request – Missing or invalid parameters.

application/json

401

Unauthorized – Invalid or missing Access-Token.

application/json

403

Forbidden – The user lacks required permission.

application/json

500

Internal Server Error.

application/json

get

/visual_sightings/carrier-observations/vin

HTTPcURLJavaScriptPython

GET /visual_sightings/carrier-observations/vin?vin=text HTTP/1.1
Host: api.genlogs.io
Access-Token: YOUR_API_KEY
x-api-key: YOUR_API_KEY
Accept: */*

{
  "observations": {
    "3AKJHHFG4RSUW1128": [
      {
        "usdot_number": "806193",
        "time_captured": "2025-12-03T16:53:41Z",
        "mc_number": "MC123456",
        "vin": "3AKJHHFG4RSUW1128",
        "source": "genlogs",
        "type": "detection"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "page_size": 100,
    "results_returned": 70,
    "has_more": false,
    "total": 70,
    "total_pages": 1
  }
}