Drivers

Before you begin

You'll need an API key or OAuth access token with the following scopes:

Read Drivers to list or retrieve drivers
Write Drivers to create or update drivers

Create a driver

Drivers can be created from the Samsara dashboard or the API using the Create a driver endpoint. Once a driver is created, they can log in to the Samsara Driver App to track Hours of Service (HOS), view dispatched loads, send messages, and more.

Below is an example request that creates a new driver. You can include externalIds to store your custom identifiers. For integration flexibility, we recommend storing a driver ID from your database as an external ID on the Samsara driver object and storing the Samsara ID for the driver in your database.

curl --request POST 'https://api.samsara.com/fleet/drivers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "name": "Driver Danielle",
  "username": "driver.danielle",
  "password": "Pa$$word9",
  "externalIds": {
      "tmsId": "98765"
  }
}'

Example response

{
  "data": {
    "id": "52606639",
    "name": "Driver Danielle",
    "username": "driver.danielle",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T18:08:25.663631212Z",
    "createdAtTime": "2025-02-07T18:08:25.663631212Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "driverActivationStatus": "active",
    "externalIds": {
      "tmsId": "98765"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

Notice that the response includes a data object with fields such as id (the Samsara driver ID) and externalIds which can store your own references to this driver.

Retrieving a driver

Once a driver is created, you can retrieve them by performing a GET request with the driver’s ID to the Retrieve a driver endpoint. Use either the Samsara-assigned driver ID (returned in the id field) or an external ID if one has been set.

For example, if your driver has an ID of 52606639 in Samsara:

curl --request GET 'https://api.samsara.com/fleet/drivers/52606639' \
--header 'Authorization: Bearer <TOKEN>'

Or, if you assigned an external ID under tmsId (e.g., tmsId:98765):

curl --request GET 'https://api.samsara.com/fleet/drivers/tmsId:98765' \
--header 'Authorization: Bearer <TOKEN>'

Example response

{
  "data": {
    "id": "52606639",
    "name": "Driver Danielle",
    "username": "driver.danielle",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T18:08:25.663631Z",
    "createdAtTime": "2025-02-07T18:08:25.663631Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "driverActivationStatus": "active",
    "externalIds": {
      "tmsId": "98765"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

Fetching a list of drivers

Use the List all drivers endpoint to fetch all drivers in your Samsara organization.

By default, this endpoint will return only active drivers.

Fetch all active drivers (default)

curl --request GET 'https://api.samsara.com/fleet/drivers' \
--header 'Authorization: Bearer <TOKEN>'

Fetch all deactivated drivers

curl --request GET 'https://api.samsara.com/fleet/drivers?driverActivationStatus=deactivated' \
--header 'Authorization: Bearer <TOKEN>'

Fetch drivers created after a certain date/time (RFC 3339)

curl --request GET 'https://api.samsara.com/fleet/drivers?createdAfterTime=2024-07-01T00:00:00Z' \
--header 'Authorization: Bearer <TOKEN>'

Example response

{
  "data": [
    {
      "id": "52606639",
      "name": "Driver Danielle",
      "username": "driver.danielle",
      "externalIds": {
        "tmsId": "98765"
      },
      "eldSettings": {
        "rulesets": [
          {
            "cycle": "USA 70 hour / 8 day",
            "shift": "US Interstate Property",
            "restart": "34-hour Restart",
            "break": "Property (off-duty/sleeper)"
          }
        ]
      },
      "timezone": "America/New_York",
      "updatedAtTime": "2025-02-06T21:38:17.867951Z",
      "createdAtTime": "2025-01-28T23:19:19.8349Z",
      "carrierSettings": {
        "carrierName": "",
        "mainOfficeAddress": "",
        "dotNumber": 0,
        "homeTerminalName": "",
        "homeTerminalAddress": ""
      },
      "driverActivationStatus": "active",
      "hosSetting": {
        "heavyHaulExemptionToggleEnabled": false
      }
    },
    {
      "id": "52568058",
      "name": "Ahmad Corkery",
      "username": "emilee",
      "eldSettings": {
        "rulesets": [
          {
            "cycle": "USA 70 hour / 8 day",
            "shift": "US Interstate Property",
            "restart": "34-hour Restart",
            "break": "Property (off-duty/sleeper)"
          }
        ]
      },
      "timezone": "America/New_York",
      "updatedAtTime": "2025-02-06T21:38:19.307372Z",
      "createdAtTime": "2025-01-29T21:42:14.95867Z",
      "carrierSettings": {
        "carrierName": "",
        "mainOfficeAddress": "",
        "dotNumber": 0,
        "homeTerminalName": "",
        "homeTerminalAddress": ""
      },
      "driverActivationStatus": "active",
      "externalIds": {
        "tmsId": "4"
      },
      "hosSetting": {
        "heavyHaulExemptionToggleEnabled": false
      }
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Updating a driver

To update an existing driver, use the Update a driver endpoint with a PATCH request. You can modify the driver’s name, username, password, externalIDs, and more. You only need to include the fields you wish to update. Fields omitted from your request remain unchanged.

Update a driver to modify the username and external ID

curl --request PATCH 'https://api.samsara.com/fleet/drivers/52606639' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
    "username": "newusername",
    "externalIds": {
        "tmsId": "newIdentifier-456"
    }
}'

Example response

{
  "data": {
    "id": "52606639",
    "name": "Driver Danielle",
    "username": "newusername",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T18:13:57.654182197Z",
    "createdAtTime": "2025-02-07T18:08:25.663631Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "driverActivationStatus": "active",
    "externalIds": {
      "tmsId": "newIdentifier-456"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

Deleting a driver (Deactivating)

There is no way to permanently delete a driver. To remove a driver from active status, you must deactivate them instead. This preserves the driver's history and logs for compliance purposes.

To deactivate a driver, call the Update a driver endpoint with "driverActivationStatus": "deactivated". Optionally include deactivatedAtTime to specify the date and time when the driver was deactivated. The deactivatedAtTime cannot be more than 6 months in the past and must not come before the driver's latest active HOS log.

Deactivate a driver

curl --request PATCH 'https://api.samsara.com/fleet/drivers/52606639' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "driverActivationStatus": "deactivated"
}'

Example response

{
  "data": {
    "id": "52606639",
    "name": "Driver Danielle",
    "username": "driver.danielle",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T17:43:08Z",
    "createdAtTime": "2025-01-29T21:42:14.95867Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "isDeactivated": true,
    "driverActivationStatus": "deactivated",
    "externalIds": {
      "tmsId": "newIdentifier-456"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

You can later reactivate a driver by setting "driverActivationStatus": "active" in another update request.

Listen for driver updates

To keep your system in sync with the latest driver information, poll the Samsara API for driver changes or handle webhook events that notify you when drivers are updated in Samsara.

Polling the /fleet/drivers endpoint
Periodically call the List all drivers endpoint and compare the response to your local records. For efficient polling, consider using filters like updatedAfterTime to retrieve only drivers updated since your last check.
Handling DriverCreated and DriverUpdated webhooks
Samsara can send a webhook notification whenever a driver is created or updated in your organization. By subscribing to the DriverCreated and DriverUpdated events, your system can receive near real-time notifications and update your database.

Carrier settings

Organizations often operate under a single carrier name, DOT number, and address settings, but certain drivers may work with a different carrier or have a unique home terminal or office address that differs from the company default. By updating the carrier settings for a driver, you can override the organization-wide settings for that individual driver, ensuring their Hours of Service logs and compliance records accurately reflect their specific carrier, DOT number, and office details.

Example: Update carrier settings for a driver

curl --request PATCH 'https://api.samsara.com/fleet/drivers/52606639' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '
{
  "carrierSettings": {
    "carrierName": "Other Carrier",
    "dotNumber": 111222,
    "homeTerminalAddress": "1234 Pear St., Scranton, PA 62814",
    "homeTerminalName": "Other Carrier",
    "mainOfficeAddress": "1234 Pear St., Scranton, PA 62814"
  }
}

Compliance settings

You can override the organization's default Hours of Service (HOS) and ELD rules on a per-driver basis to address unique regulatory or operational needs. For example, a driver might require specialized HOS cycles, Big Day or Adverse Weather exemptions, or specific shift start hours to comply with various regulations.

Hours of Service (HOS)

Example: Updating HOS fields

curl --request PATCH 'https://api.samsara.com/fleet/drivers/52559478' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "eldAdverseWeatherExemptionEnabled": true,
  "eldBigDayExemptionEnabled": false,
  "eldDayStartHour": 0,
  "eldExempt": false,
  "eldExemptReason": "",
  "eldPcEnabled": true,
  "eldYmEnabled": true,
  "hosSetting": {
    "heavyHaulExemptionToggleEnabled": false
  },
  "timezone": "America/New_York"
}'

Example response

{
  "data": {
    "id": "52559478",
    "name": "Antoine Stark",
    "username": "antoine.stark",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T17:31:37.386201085Z",
    "createdAtTime": "2025-01-28T23:19:19.8349Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "driverActivationStatus": "active",
    "externalIds": {
      "tmsId": "2"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

ELD Rule Sets

The eldSettings attribute of a Driver is read only, however you can pass a usDriverRulesetOverride to the API that will add a new US specific Driver Ruleset to the list of eldSettings.rulesets.

curl --request PATCH 'https://api.samsara.com/fleet/drivers/52559478' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "usDriverRulesetOverride": {
    "cycle": "California Farm (8/112)",
    "restart": "36-hour Restart",
    "restbreak": "California Mealbreak (off-duty/sleeper)",
    "usStateToOverride": "CA"
  }
}'

Example response

{
  "data": {
    "id": "52568058",
    "name": "Ahmad Corkery",
    "username": "emilee",
    "eldSettings": {
      "rulesets": [
        {
          "cycle": "CA 112 hour / 8 day",
          "shift": "California Intrastate Farm",
          "restart": "36-hour Restart",
          "break": "California Mealbreak (off-duty/sleeper)",
          "jurisdiction": "CA"
        },
        {
          "cycle": "USA 70 hour / 8 day",
          "shift": "US Interstate Property",
          "restart": "34-hour Restart",
          "break": "Property (off-duty/sleeper)"
        }
      ]
    },
    "timezone": "America/New_York",
    "updatedAtTime": "2025-02-07T18:42:42Z",
    "createdAtTime": "2025-01-29T21:42:14.95867Z",
    "carrierSettings": {
      "carrierName": "",
      "mainOfficeAddress": "",
      "dotNumber": 0,
      "homeTerminalName": "",
      "homeTerminalAddress": ""
    },
    "driverActivationStatus": "active",
    "usDriverRulesetOverride": {
      "usStateToOverride": "CA",
      "cycle": "California Farm (8/112)",
      "restart": "36-hour Restart",
      "restbreak": "California Mealbreak (off-duty/sleeper)"
    },
    "hosSetting": {
      "heavyHaulExemptionToggleEnabled": false
    }
  }
}

[EU Only] Tachograph

You can update the driver's tachographCardNumber following the same pattern above to set the Driver's assigned tachograph card number.