Update a driver

Update a specific driver’s information. This can also be used to activate or de-activate a given driver by setting the driverActivationStatus field. If the driverActivationStatus field is ‘deactivated’ then the user can also specify the deactivatedAtTime. The deactivatedAtTime cannot be more than 6 months in the past and must not come before the dirver’s latest active HOS log. It will be considered an error if deactivatedAtTime is provided with a driverActivationStatus of active.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

To use this endpoint, select Write Drivers under the Drivers category when creating or editing an API token. Learn More.

PATCH /fleet/drivers/{id}

Update a driver

cURL

curl --request PATCH \
  --url https://api.samsara.com/fleet/drivers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attributes": [
    {
      "dateValues": [
        "<string>"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "License Certifications",
      "numberValues": [
        123
      ],
      "stringValues": [
        "<string>"
      ]
    }
  ],
  "carrierSettings": {
    "carrierName": "Acme Inc.",
    "dotNumber": 98231,
    "homeTerminalAddress": "1234 Pear St., Scranton, PA 62814",
    "homeTerminalName": "Acme Inc.",
    "mainOfficeAddress": "1234 Pear St., Scranton, PA 62814"
  },
  "currentIdCardCode": "941767043",
  "deactivatedAtTime": "2019-05-18T20:27:35Z",
  "driverActivationStatus": "active",
  "eldAdverseWeatherExemptionEnabled": true,
  "eldBigDayExemptionEnabled": true,
  "eldDayStartHour": 123,
  "eldExempt": true,
  "eldExemptReason": "Bad driver",
  "eldPcEnabled": true,
  "eldYmEnabled": true,
  "externalIds": {
    "maintenanceId": "250020",
    "payrollId": "ABFS18600"
  },
  "hasDrivingFeaturesHidden": true,
  "hasVehicleUnpinningEnabled": true,
  "hosSetting": {
    "heavyHaulExemptionToggleEnabled": false
  },
  "licenseNumber": "E1234567",
  "licenseState": "CA",
  "locale": "us",
  "name": "Susan Jones",
  "notes": "Also goes by the nickname Furious Fred.",
  "password": "aSecurePassword1234",
  "peerGroupTagId": "<string>",
  "phone": "5558234327",
  "profileImageBase64": "/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "profileImageUrl": "https://example.com/images/driver-profile.jpg",
  "staticAssignedVehicleId": "456",
  "tachographCardNumber": "1000000492436002",
  "tagIds": [
    "147"
  ],
  "timezone": "America/Los_Angeles",
  "trailerGroupTagId": "342418",
  "username": "SusanJones",
  "vehicleGroupTagId": "342417",
  "waitingTimeDutyStatusEnabled": true
}
'

200

{
  "data": {
    "attributes": [
      {
        "dateValues": [
          "<string>"
        ],
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "License Certifications",
        "numberValues": [
          123
        ],
        "stringValues": [
          "<string>"
        ]
      }
    ],
    "carrierSettings": {
      "carrierName": "Acme Inc.",
      "dotNumber": 98231,
      "homeTerminalAddress": "1234 Pear St., Scranton, PA 62814",
      "homeTerminalName": "Acme Inc.",
      "mainOfficeAddress": "1234 Pear St., Scranton, PA 62814"
    },
    "createdAtTime": "2019-05-18T20:27:35Z",
    "currentIdCardCode": "941767043",
    "driverActivationStatus": "active",
    "eldAdverseWeatherExemptionEnabled": false,
    "eldBigDayExemptionEnabled": false,
    "eldDayStartHour": 0,
    "eldExempt": false,
    "eldExemptReason": "Bad driver",
    "eldPcEnabled": false,
    "eldSettings": {
      "rulesets": [
        {
          "break": "Property (off-duty/sleeper)",
          "cycle": "USA 60 hour / 7 day",
          "jurisdiction": "AR",
          "restart": "Default",
          "shift": "US Interstate Property"
        }
      ]
    },
    "eldYmEnabled": false,
    "externalIds": {
      "maintenanceId": "250020",
      "payrollId": "ABFS18600"
    },
    "hasDrivingFeaturesHidden": true,
    "hasVehicleUnpinningEnabled": true,
    "id": "123",
    "isDeactivated": false,
    "licenseNumber": "E1234567",
    "licenseState": "CA",
    "locale": "us",
    "name": "Susan Jones",
    "notes": "Also goes by the nickname Furious Fred.",
    "peerGroupTag": {
      "id": "3914",
      "name": "East Coast",
      "parentTagId": "4815"
    },
    "phone": "5558234327",
    "profileImageUrl": "https://example.com/images/driver-profile.jpg",
    "staticAssignedVehicle": {
      "id": "123456789",
      "name": "Midwest Truck #4"
    },
    "tachographCardNumber": "1000000492436002",
    "tags": [
      {
        "id": "3914",
        "name": "East Coast",
        "parentTagId": "4815"
      }
    ],
    "timezone": "America/Los_Angeles",
    "trailerGroupTag": {
      "id": "3914",
      "name": "West Coast",
      "parentTagId": "4815"
    },
    "updatedAtTime": "2019-06-13T19:08:25Z",
    "usDriverRulesetOverride": {
      "cycle": "TX 70 hour / 7 day",
      "restart": "34-hour Restart",
      "restbreak": "None",
      "usStateToOverride": "TX"
    },
    "username": "SusanJones",
    "vehicleGroupTag": {
      "id": "3914",
      "name": "East Coast",
      "parentTagId": "4815"
    },
    "waitingTimeDutyStatusEnabled": false
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · required

ID of the driver. This can either be the Samsara-specified ID, or an external ID. External IDs are customer specified key-value pairs created in the POST or PATCH requests of this resource. To specify an external ID as part of a path parameter, use the following format: key:value. For example, payrollId:ABFS18600

Body

application/json

Updates to the driver properties.

Driver that should be updated.

attributes · object[]

Show child attributes

carrierSettings · object

Carrier for a given driver. If the driver's carrier differs from the general organization's carrier settings, the override value is used. Updating this value only updates the override setting for this driver.

Show child attributes

currentIdCardCode · string

The ID Card Code on the back of the physical card assigned to the driver. Contact Samsara if you would like to enable this feature.

Example:

"941767043"

deactivatedAtTime · string

The date and time this driver is considered to be deactivated in RFC 3339 format.

Example:

"2019-05-18T20:27:35Z"

driverActivationStatus · enum<string>

A value indicating whether the driver is active or deactivated. Valid values: active, deactivated.

Available options: active, deactivated

eldAdverseWeatherExemptionEnabled · boolean

Flag indicating this driver may use Adverse Weather exemptions in ELD logs.

eldBigDayExemptionEnabled · boolean

Flag indicating this driver may use Big Day exemption in ELD logs.

eldDayStartHour · integer

0 indicating midnight-to-midnight ELD driving hours, 12 to indicate noon-to-noon driving hours.

eldExempt · boolean

Flag indicating this driver is exempt from the Electronic Logging Mandate.

eldExemptReason · string

Reason that this driver is exempt from the Electronic Logging Mandate (see eldExempt).

Example:

"Bad driver"

eldPcEnabled · boolean

Flag indicating this driver may select the Personal Conveyance duty status in ELD logs.

eldYmEnabled · boolean

Flag indicating this driver may select the Yard Move duty status in ELD logs.

externalIds · object

The external IDs for the given object.

Show child attributes

Example:

{
  "maintenanceId": "250020",
  "payrollId": "ABFS18600"
}

hasDrivingFeaturesHidden · boolean

A boolean indicating whether the driver has driving-related features hidden in the Driver App, including Vehicle selection, HOS, Routing, Team Driving, Documents, and Trip Logs. Default value is false if omitted. Note: only available to customers of Connected Forms.

Example:

true

hasVehicleUnpinningEnabled · boolean

A boolean indicating whether the driver has vehicle unpinning enabled. Default value is true if omitted.

Example:

true

hosSetting · object

Hos settings for a driver.

Show child attributes

licenseNumber · string

Driver's state issued license number. The combination of this number and licenseState must be unique.

Example:

"E1234567"

licenseState · string

Abbreviation of US state, Canadian province, or US territory that issued driver's license.

Example:

"CA"

locale · enum<string>

Locale override (uncommon). These are specified by ISO 3166-2 country codes for supported locales. Valid values: us, at, be, ca, gb, fr, de, ie, it, lu, mx, nl, es, ch, pr.

Available options: us, at, be, ca, gb, fr, de, ie, it, lu, mx, nl, es, ch, pr

name · string

Driver's name.

Required string length: 1 - 255

Example:

"Susan Jones"

notes · string

Notes about the driver.

Maximum string length: 4096

Example:

"Also goes by the nickname Furious Fred."

password · string

Password that the driver can use to login to the Samsara driver app.

Example:

"aSecurePassword1234"

peerGroupTagId · string

The peer group tag id this driver belong to, leave blank to be in group with everyone, used for gamification.

phone · string

Phone number of the driver.

Maximum string length: 255

Example:

"5558234327"

profileImageBase64 · string

Base64-encoded profile image data. This field can be used to upload a profile image during driver creation. The image will be processed and stored, and the profileImageUrl will be returned in the response. If Camera ID is enabled, uploaded profile photos are used to train the model to recognize drivers automatically. You can manage this setting in Driver Assignment.

Example:

"/9j/4AAQSkZJRgABAQEAYABgAAD..."

profileImageUrl · string

URL to the driver's profile image. This field is returned in responses and can be used to set a profile image from an external URL during driver creation.

Maximum string length: 1024

Example:

"https://example.com/images/driver-profile.jpg"

staticAssignedVehicleId · string

ID of vehicle that the driver is permanently assigned to. (uncommon).

Example:

"456"

tachographCardNumber · string

Driver's assigned tachograph card number (Europe specific)

Example:

"1000000492436002"

tagIds · string[]

IDs of tags the driver is associated with. If your access to the API is scoped by one or more tags, this field is required to pass in.

timezone · string

Home terminal timezone, in order to indicate what time zone should be used to calculate the ELD logs. Driver timezones use IANA timezone database keys (e.g. America/Los_Angeles, America/New_York, Europe/London, etc.). You can find a mapping of common timezone formats to IANA timezone keys here.

Example:

"America/Los_Angeles"

trailerGroupTagId · string

Tag ID which determines which trailers a driver will see when selecting trailers.

Example:

"342418"

usDriverRulesetOverride · object

US Driver Ruleset override for a given driver. If the driver is operating under a ruleset different from the organization default, the override is used. Updating this value only updates the override setting for this driver. Explicitly setting this field to null will delete driver's ruleset override. If the driver does not have an override ruleset set, the response will not include any usDriverRulesetOverride information.

Show child attributes

username · string

Driver's login username into the driver app. The username may not contain spaces or the '@' symbol. The username must be unique.

Required string length: 1 - 189

Example:

"SusanJones"

vehicleGroupTagId · string

Tag ID which determines which vehicles a driver will see when selecting vehicles.

Example:

"342417"

waitingTimeDutyStatusEnabled · boolean

Flag indicating this driver may select waiting time duty status in ELD logs

Response

200

application/json

Updated driver object, with ID.

A single driver.

data · object

A driver object

Show child attributes