# 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 {% hint style="info" %} You can perform up to two concurrent calls at one time. {% endhint %} * **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:** {% hint style="info" %} For each provided VIN, you will receive a list of sightings including `usdot_number,` `time_captured`, `vin`, `mc_number`, `source` and `type` {% endhint %} {% hint style="info" %} #### 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.* {% endhint %} **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: ```bash 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 > 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.
```json {"openapi":"3.0.3","info":{"title":"Carrier Observations by VIN API","version":"1.0.0"},"servers":[{"url":"https://api.genlogs.io"}],"security":[{"AccessTokenAuth":[],"ApiKeyAuth":[]}],"components":{"securitySchemes":{"AccessTokenAuth":{"type":"apiKey","in":"header","name":"Access-Token","description":"JWT provided directly in the Access-Token header.\n"}}},"paths":{"/visual_sightings/carrier-observations/vin":{"get":{"summary":"Get carrier observations by VIN","description":"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.\n","tags":["Carrier Observations"],"parameters":[{"in":"query","name":"vin","required":true,"schema":{"type":"string"},"description":"Vehicle Identification Number (VIN). Must be a non-empty value.\n"},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1},"description":"Page number for pagination."},{"in":"query","name":"page_size","required":false,"schema":{"type":"integer","minimum":1,"maximum":500},"description":"Number of results to return per page."}],"responses":{"200":{"description":"Successful retrieval of observations.","content":{"application/json":{"schema":{"type":"object","properties":{"observations":{"type":"object","description":"Dictionary where each key is a VIN and the value is a list of observations associated with that VIN.\n","additionalProperties":{"type":"array","items":{"type":"object","properties":{"usdot_number":{"type":"string"},"time_captured":{"type":"string","format":"date-time"},"mc_number":{"type":"string"},"vin":{"type":"string"},"source":{"type":"string"},"type":{"type":"string"}}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"results_returned":{"type":"integer"},"has_more":{"type":"boolean"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}},"400":{"description":"Bad Request – Missing or invalid parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"401":{"description":"Unauthorized – Invalid or missing Access-Token.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"403":{"description":"Forbidden – The user lacks required permission.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.genlogs.io/visual-sightings/carrier-observation/carrier-observation-by-vin.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.