Compliance

As a TMS integrator, you can use Samsara’s APIs to pull driver availability, manage driver configurations, and retrieve duty statuses—all essential for accurate dispatch decisions.

Why Integrate Compliance Data?

• Dispatch the Right Driver

  • Automatically check if a driver has enough drive time remaining before assigning a new load.
  • Avoid scheduling conflicts and potential violations.

• Improve Safety & Operational Efficiency

  • Enable proactive alerts when a driver nears on-duty limits.
  • Reduce regulatory risk by maintaining a single source of truth for duty status and historical logs.

• Support Regional Regulations

  • In North America, use HOS (ELD) data.
  • In Europe, fetch Tachograph data for driver and vehicle activity.

1. Managing Driver Compliance Settings

Driver Creation & ELD Rulesets

You can manage drivers via the Samsara Drivers API, which supports:

• Creating, reading, updating, and deactivating drivers
• Setting ELD exemptions (e.g. Adverse weather, Big day, etc.)
• Enabling personal conveyance and yard moves
• ELD day start hour configuration

Note: Certain advanced ELD settings—like ruleset selection for US cycles and restarts—must be configured via the Samsara Dashboard. Attempts to write them directly via the API will be ignored.

curl --request POST 'https://api.samsara.com/fleet/drivers' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Jane Smith",
  "username": "jane.smith",
  "password": "password",
  "hosSetting": {
    "heavyHaulExemptionToggleEnabled": false
  },
  "usDriverRulesetOverride": {
    "cycle": "USA Property (8/70)",
    "restart": "24-hour Restart",
    "restbreak": "Property (off-duty/sleeper)",
    "usStateToOverride": "TX"
  },
  "eldAdverseWeatherExemptionEnabled": true,
  "eldBigDayExemptionEnabled": true,
  "eldDayStartHour": 4,
  "eldExempt": false,
  "eldPcEnabled": true,
  "eldYmEnabled": true
}'

2. Hours of Service (HOS)

2.1 Real-Time Duty Status

The Get HOS Clocks endpoint provides current availability information for each driver:

• Current duty status (offDuty, driving, onDuty, sleeperBerth, etc.)
• Time until break (timeUntilBreakDurationMs)
• Remaining drive/shift/cycle time

This data is essential for real-time dispatch decisions, letting your TMS identify which drivers can legally take a new load.

curl --request GET 'https://api.samsara.com/fleet/hos/clocks' \
     --header 'Authorization: Bearer <token>'

Response snippet:

{
  "data": [
    {
      "clocks": {
        "break": {
          "timeUntilBreakDurationMs": 28800000
        },
        "cycle": {
          "cycleRemainingDurationMs": 252000000,
          "cycleStartedAtTime": "2020-01-27T07:06:25Z",
          "cycleTomorrowDurationMs": 252000000
        },
        "drive": {
          "driveRemainingDurationMs": 39600000
        },
        "shift": {
          "shiftRemainingDurationMs": 50400000
        }
      },
      "currentDutyStatus": {
        "hosStatusType": "offDuty"
      },
      "currentVehicle": {
        "ExternalIds": {
          "maintenanceId": "250020",
          "payrollId": "ABFS18600"
        },
        "id": "123456789",
        "name": "Midwest Truck #4"
      },
      "driver": {
        "id": "88668",
        "name": "Susan Bob"
      },
      "violations": {
        "cycleViolationDurationMs": 39600000,
        "shiftDrivingViolationDurationMs": 39600000
      }
    }
  ],
  "pagination": {
    "endCursor": "MjkY",
    "hasNextPage": true
  }
}

2.2 Daily Duty Status Summaries

Daily HOS logs summarize each driver's activity by day:

• Time spent in each duty status
• Distance driven (including personal conveyance, yard moves)
• Vehicle and trailer assignments
• Shipping doc assignments
• Log certification info

If your TMS needs to generate daily compliance reports or store them for auditing, fetch these via the Get all driver HOS daily logs endpoint.

2.3 Historical Log Retrieval

For more granular analysis, use the GET /fleet/hos/logs endpoint to retrieve each duty status event within a specific time range:

• Start/end times, relevant vehicle assignment, location, edits
• Reflects the current state of the log (including retroactive edits)

This is useful for audits, dispute resolution, or building timecards in your TMS.

Note: If a log is edited, the TMS may need to re-fetch historical logs to ensure it has the latest version.

3. Tachograph (EU Only)

For EU-based fleets, Samsara captures driver and vehicle tachograph files (.ddd). These files track:

• Driver card activity (start/end of trip, breaks, work, driving)
• Vehicle usage (mileage, times, VIN)
• Legally-required remote download of digital tachograph files

3.1 Driver Tachograph Files

• Use GET /fleet/drivers/tachograph-files/history to retrieve URLs for each .ddd driver file uploaded in a given timeframe.
• Files are typically uploaded at the start of every trip.
• Download each .ddd file from the returned URL to store or process in your TMS.

curl --request GET 'https://api.eu.samsara.com/fleet/drivers/tachograph-files/history' \
 --header 'Authorization: Bearer <token>' \
 --data 'startTime=2021-01-01T00:00:00Z' \
 --data 'endTime=2021-01-07T00:00:00Z'

3.2 Vehicle Tachograph Files

• [GET /fleet/vehicles/tachograph-files/history] fetches .ddd vehicle files uploaded every 7 days.
• Similar approach: for each returned file URL, download the .ddd file to integrate into your TMS for further analysis or archiving.

3.3 Parsed Tachograph Activity

• [GET /fleet/drivers/tachograph-activity/history] returns a parsed record of each driver’s “BREAK/REST,” “DRIVING,” “WORK,” etc.
• Updated any time the vehicle is turned ON.
• Ideal for a TMS that needs daily or historical driver activity directly (without manually parsing .ddd files).

4. Choosing Your Data Flow

5. Implementation Tips

1. Audit & Historical Backfill

   • For compliance audits or analytics, retrieve historical logs (/fleet/hos/logs for U.S. or tachograph history for EU).
   • Store these in your TMS to handle driver disputes or regulatory checks.

2. Account for Edits

   • Logs can be edited by carriers or drivers. Re-fetch historical data if you need the most recent version of a log.

3. Regional Differences

   • HOS is primary in North America.
   • Tachograph (driver + vehicle files) is only relevant to EU-based fleets.
   • Some fleets operate in both regions—your TMS may need logic to handle separate rulesets.

4. Integrating with Load Assignment

   • Combine compliance data with your route planning. For example, only assign a route if the driver’s driveRemainingDurationMs is enough to complete it safely.

Example Flow: HOS-Aware Dispatch

1. TMS retrieves driver HOS clocks (/fleet/hos/clocks) or tachograph activity.
2. Dispatcher sees each driver’s remaining drive time.
3. TMS automatically filters out drivers who are close to their daily or cycle limits.
4. Once assigned, the driver’s duty statuses continue to update in Samsara.
5. TMS periodically pulls logs for compliance records, creating daily summaries or dashboards.