/users

Update: Validation for time_tracking_mode

We have now updated this endpoint with validation, so that the value of time_tracking_mode is compatible with the value of eld_mode.

Ensure that the values of time_tracking_mode correspond to the following values of eld_mode:

Time Tracking Mode Value	Must match the following ELD Mode Value
Logs	None or Logs
Timecards	Exempt
Not_required	Exempt

Here is an explanation of the scenarios:

Time Tracking Mode Value	ELD Mode Value	Result
Logs	Logs	The driver need not maintain the log manually, as everything is recorded by the Vehicle Gateway.
Logs	None	The driver must manually maintain an Electronic Logbook on the Motive Driver app. Logging will be disabled on the Vehicle Gateway.
Timecards	Exempt	The driver is exempt from maintaining logs and will use Motive Timecards in the Driver App to track their time.
Not_required	Exempt	The driver is exempt from maintaining logs and is not required to track their time within Motive.

NOTE: Only the above-mentioned combinations are valid and rest all are considered invalid. The API will also validate the combinations and will throw a corresponding error when an invalid combination is found.

Add External Ids

To add external ids to a user record just add the following to the request body. External ID represents a unique identifier for a user in an external system. The name of this external system is stored as integration_name. The combination of external_id and integration_name will always be unique.

{
  "email":"[email protected]",
  "first_name":"John",
  "last_name":"Doe",
  # other attributes for a user
  ...
  ...
  ...
  # add external id for user
  "external_ids_attributes":[
    {
      "external_id":"987",
      "integration_name":"generic_tms"
    }
  ]
}

require 'uri'
require 'net/http'
require 'json'

url = URI('https://api.keeptruckin.com/v1/users')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Authorization'] = "Bearer <OAUTH_TOKEN>"
request['Content-Type'] = 'application/json'
params = {
    :email                        => nil,
    :first_name                   => "John",
    :last_name                    => "Doe",
    :phone                        => nil,
    :phone_ext                    => nil,
    :time_zone                    => nil,
    :carrier_name                 => nil,
    :carrier_street               => nil,
    :carrier_city                 => nil,
    :carrier_state                => nil,
    :carrier_zip                  => nil,
    :violation_alerts             => "1_hour",
    :terminal_street              => nil,
    :terminal_city                => nil,
    :terminal_state               => nil,
    :terminal_zip                 => nil,
    :exception_24_hour_restart    => false,
    :exception_8_hour_break       => false,
    :exception_wait_time          => false,
    :exception_short_haul         => false,
    :exception_ca_farm_school_bus => false,
    :exception_adverse_driving    => false,
    :export_combined              => true,
    :export_recap                 => true,
    :export_odometers             => true,
    :metric_units                 => false,
    :username                     => "john.doe.demo.fleet",
    :password                     => "password",
    :cycle                        => nil,
    :driver_company_id            => nil,
    :minute_logs                  => false,
    :duty_status                  => "off_duty",
    :eld_mode                     => "none",
    :drivers_license_number       => nil,
    :drivers_license_state        => nil,
    :yard_moves_enabled           => false,
    :personal_conveyance_enabled  => false,
    :manual_driving_enabled       => false,
    :role                         => "driver",
    :status                       => "active",
    :dot_id                       => "12345678",
    :time_tracking_mode           => "logs"
}
request.body = params.to_json

response = http.request(request)
puts response.read_body

Restrict fleet user’s access to certain groups

Restrict fleet users access to certain groups, by sending the list of corresponding group_ids inside the custom_user_role object, and not inside the parent level group_ids attribute.

{
  "email":"[email protected]",
  "first_name":"John",
  "last_name":"Doe",
  "role":"fleet_user"
  # other attributes for a user
  ...
  ...
  # restrict fleet user to groups
  "group_visibility":"limited",
  "custom_user_role":{
    "user_role_id":9,
    "group_ids":[
      101
    ]
  }
}

To add a driver to a group the list of group IDs needs to be sent in the group_ids attribute on the user object

{
  "email":"[email protected]",
  "first_name":"John",
  "last_name":"Doe",
  "role":"driver",
  # other attributes for a driver
  ...
  ...
  # add driver to groups
  "group_ids":[
    1,
    2
  ]
}