SAsamsara
Drivers

Create a driver

Add a driver to the organization.

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>

post/fleet/drivers

Request

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

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).

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 required

Driver's name.

notesstring

Notes about the driver.

passwordstring required

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

peerGroupTagIdstring

The peer group tag id this driver belong to, 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 required

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",
  "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

Newly created driver object, with Samsara-generated 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.