Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt

Use this file to discover all available pages before exploring further.

​
v2.0.0 - First Stable Release
2nd December 2025
This is the first stable release of the Telematics API v2. This release focuses on consistent filtering, clearer parameter names, richer error responses, and reorganized endpoints across the Telematics API.
Stable Release: This version represents a stable, production-ready API with commitment to backward compatibility within v2.x releases going forward.

​
Endpoint Changes

Removed:
  • /v2/telematics/refs/* (all reference data endpoints)
Added:
  • /v2/telematics/ref-hos-rulesets
  • /v2/telematics/ref-hos-event-codes
  • /v2/telematics/ref-hos-malfunction-codes
  • /v2/telematics/ref-hos-regions
  • /v2/telematics/ref-timezones
Migration: Update all reference data calls to use the new ref-* pattern instead of refs/*.
Removed:
  • /v2/telematics/latest_locations - Get latest locations for all vehicles
  • /v2/telematics/vehicles/{vehicle_id}/locations - Get location history for one vehicle
Added:
  • /v2/telematics/vehicle-locations - Unified endpoint with only_latest parameter (defaults to true)
Migration:
# Before (latest locations)
GET /v2/telematics/latest_locations

# After
GET /v2/telematics/vehicle-locations?only_latest=true

# Before (history for one vehicle)
GET /v2/telematics/vehicles/{vehicle_id}/locations?start_date=...&end_date=...

# After
GET /v2/telematics/vehicle-locations?vehicle_ids={vehicle_id}&only_latest=false&from_datetime=...&to_datetime=...
Removed:
  • /v2/telematics/vehicle-sensors - List all sensor readings
  • /v2/telematics/vehicle-sensors/{vehicle_sensor_id} - Get sensor by ID
Added:
  • /v2/telematics/vehicle-sensor-events - List sensor events with filtering
  • /v2/telematics/vehicles/{vehicle_id}/sensor-events - Get sensor events for specific vehicle
Migration: Use the new sensor events endpoints with time-based filtering instead of accessing individual sensor readings by ID.
Removed:
  • /v2/telematics/dvir-logs/{dvir_log_id} - Get single DVIR log by ID
Still Available:
  • /v2/telematics/dvir-logs - List DVIR logs
  • /v2/telematics/dvir-logs/{dvir_log_id}/defects - Get defects for a specific log
Added:
  • /v2/telematics/dvir-defects - List all defects across DVIR logs
Migration: Use the list endpoint with filtering instead of fetching individual DVIR logs by ID.
Removed:
  • /v2/telematics/hos-events/{hos_event_id}/annotations - Standalone annotations endpoint
New Behavior:
  • Annotations are now included directly in the hos_event payload via an annotations field
Migration:
// Before: Separate API call
GET /v2/telematics/hos-events/{id}/annotations

// After: Included in event response
GET /v2/telematics/hos-events/{id}
{
  "hos_event_id": "evt_123",
  "annotations": [
    {
      "created_at": "2025-12-01T10:30:00Z",
      "remarks": "Driver added manual note"
    }
  ]
}

​
Query Parameter Changes

All list endpoints now use standardized parameter naming:
Old ParameterNew ParameterChange Description
source_datainclude_source_dataRenamed for clarity (boolean flag)
driver_iddriver_idsNow accepts multiple IDs (array, max 100)
vehicle_idvehicle_idsNow accepts multiple IDs (array, max 100)
start_date / end_datefrom_datetime / to_datetimeStandardized time filtering (ISO 8601 UTC)
New Fleet Scoping Filters:
  • fleet_ids - Filter by Catena fleet UUIDs (array)
  • fleet_refs - Filter by your internal fleet references (array)
Migration Example:
# Before
GET /v2/telematics/trips?fleet_id=fleet_123&driver_id=driver_456&start_date=2025-11-01&end_date=2025-11-10&source_data=true

# After
GET /v2/telematics/trips?fleet_ids=fleet_123&driver_ids=driver_456&from_datetime=2025-11-01T00:00:00Z&to_datetime=2025-11-10T23:59:59Z&include_source_data=true

​
Time Filtering Standardization

Before

Inconsistent parameter names:
  • start_date / end_date
  • Hard-coded defaults in spec
  • Varying time formats

After

Standardized across all endpoints:
  • from_datetime / to_datetime
  • ISO 8601 UTC format required
  • Documented defaults (e.g., “now() - 1 day”)
  • Time window limits (commonly 15 days max)
Time Window Limits: Most endpoints now enforce maximum time ranges (typically 15 days). Requests exceeding this limit will return a 422 Unprocessable Entity error.

​
Error Response Changes

Error handling has been standardized across all endpoints:New Status Codes:
  • 400 Bad Request - Invalid parameters or malformed requests
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn’t exist
  • 422 Unprocessable Entity - Validation errors (new schema)
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server-side errors
Deprecated Parameter Errors:
{
  "error": "deprecated_parameter",
  "message": "The parameter 'fleet_id' has been removed. Use 'fleet_ids' instead.",
  "status_code": 400
}
Deprecated Endpoint Errors:
{
  "error": "endpoint_removed",
  "message": "The /annotations endpoint has been removed. Use the 'annotations' field on the hos_event resource instead.",
  "status_code": 410
}
Update your error handling logic to parse the new error schema and handle the expanded set of status codes.

​
New Features

New endpoint for aggregated daily Hours of Service data:
GET /v2/telematics/hos-daily-summaries
Returns daily rollups of driving time, on-duty hours, violations, and remaining available hours per driver.
New endpoint to list all DVIR defects across multiple logs:
GET /v2/telematics/dvir-defects?from_datetime=...&to_datetime=...
Allows filtering defects without needing to query individual DVIR logs.
All list endpoints now support:
  • fleet_ids - Filter by Catena’s internal fleet UUIDs
  • fleet_refs - Filter by your internal fleet identifiers
This enables multi-fleet queries and better isolation of fleet data.
Most endpoints now accept arrays of IDs for efficient batch filtering:
  • driver_ids (max 100)
  • vehicle_ids (max 100)
  • fleet_ids (max 100)
  • fleet_refs (max 100)
Reduces the need for multiple API calls when querying data for multiple entities.

​
Migration Checklist

1

Update Query Parameters

  • Rename source_data → include_source_data
  • Convert singular ID params to plural arrays: driver_id → driver_ids, vehicle_id → vehicle_ids
  • Replace start_date/end_date with from_datetime/to_datetime (ISO 8601 UTC)
  • Add fleet scoping filters where needed: fleet_ids or fleet_refs
2

Update Endpoint Paths

  • Reference data: /refs/* → /ref-*
  • Vehicle locations: Use unified /vehicle-locations with only_latest parameter
  • Vehicle sensors: Use /vehicle-sensor-events or /vehicles/{id}/sensor-events
  • Remove calls to deleted endpoints (single DVIR log by ID, HOS annotations)
3

Update Error Handling

  • Handle new status codes: 400, 401, 403, 404, 422, 429, 500
  • Parse new error response schema
  • Handle deprecated parameter/endpoint errors gracefully
4

Test Time Window Limits

  • Verify your queries respect the 15-day maximum time range
  • Implement pagination for longer historical queries
  • Handle 422 errors when time range is too large
5

Update Client Libraries

  • Regenerate API clients from the new OpenAPI spec
  • Update hardcoded endpoint URLs
  • Test all integration points with the new API structure

​
Need Help?

API Reference

View complete endpoint documentation with the new parameter structure

Contact Support

Questions about migrating your integration? Our team is here to help