SAsamsara
Drivers

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 <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

To use this endpoint, select Write Drivers under the Drivers category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

patch/fleet/drivers/{id}

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Path parameters

idstring 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

Request body

currentIdCardCodestring

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.

dateOfBirthstring date

Driver's date of birth in YYYY-MM-DD format. Treated as a calendar date (no time component, no timezone).

deactivatedAtTimestring

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

driverActivationStatus'active' | 'deactivated'

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

eldAdverseWeatherExemptionEnabledboolean

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

eldBigDayExemptionEnabledboolean

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

eldDayStartHourinteger

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

eldExemptboolean

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

eldExemptReasonstring

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

eldPcEnabledboolean

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

eldYmEnabledboolean

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

emailstring email

Driver's email address.

externalIdsobject

The external IDs for the given object.

hasDrivingFeaturesHiddenboolean

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.

hasVehicleUnpinningEnabledboolean

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

licenseNumberstring

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

licenseStatestring

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

locale'us' | 'at' | 'be' | 'ca' | 'gb' | 'fr' | 'de' | 'ie' | 'it' | 'lu' | 'mx' | 'nl' | 'es' | 'ch' | 'pr'

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.

namestring

Driver's name.

notesstring

Notes about the driver.

passwordstring

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

peerGroupTagIdstring

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

phonestring

Phone number of the driver.

profileImageBase64string

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.

profileImageUrlstring

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.

staticAssignedVehicleIdstring

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

tachographCardNumberstring

Driver's assigned tachograph card number (Europe specific)

tagIdsstring[]

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.

timezonestring

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.

trailerGroupTagIdstring

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

usernamestring

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

vehicleGroupTagIdstring

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

waitingTimeDutyStatusEnabledboolean

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

Example request

{
  "attributes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "License Certifications"
    }
  ],
  "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",
  "dateOfBirth": "1985-07-21",
  "deactivatedAtTime": "2019-05-18T20:27:35Z",
  "eldExemptReason": "Bad driver",
  "email": "susan.jones@example.com",
  "externalIds": {
    "maintenanceId": "250020",
    "payrollId": "ABFS18600"
  },
  "hasDrivingFeaturesHidden": true,
  "hasVehicleUnpinningEnabled": true,
  "licenseNumber": "E1234567",
  "licenseState": "CA",
  "name": "Susan Jones",
  "notes": "Also goes by the nickname Furious Fred.",
  "password": "aSecurePassword1234",
  "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",
  "usDriverRulesetOverride": {
    "cycle": "TX 70 hour / 7 day",
    "restart": "34-hour Restart",
    "restbreak": "None",
    "usStateToOverride": "TX"
  },
  "username": "SusanJones",
  "vehicleGroupTagId": "342417"
}

Response

Updated driver object, with ID.

Example response

{
  "data": {
    "attributes": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "License Certifications"
      }
    ],
    "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",
    "dateOfBirth": "1985-07-21",
    "eldExemptReason": "Bad driver",
    "eldSettings": {
      "rulesets": [
        {
          "break": "Property (off-duty/sleeper)",
          "cycle": "USA 60 hour / 7 day",
          "jurisdiction": "AR",
          "restart": "Default",
          "shift": "US Interstate Property"
        }
      ]
    },
    "email": "susan.jones@example.com",
    "externalIds": {
      "maintenanceId": "250020",
      "payrollId": "ABFS18600"
    },
    "hasDrivingFeaturesHidden": true,
    "hasVehicleUnpinningEnabled": true,
    "id": "123",
    "licenseNumber": "E1234567",
    "licenseState": "CA",
    "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"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.