Create a new user

post https://api.gomotive.com/v1/users

Purpose: Use this API to create a new user in the Motive system. The user can be any one of the following roles:

driver
fleet_user
admin

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":"acme@example.com",
  "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.gomotive.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":"acme@example.com",
  "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":"acme@example.com",
  "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.gomotive.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"
}
request.body = params.to_json

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

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

Response Parameters

user

Type: Object
Description: Details of a user.

id: Integer

Type: Integer
Description: Unique identifier for the user.

email

Type: String
Description: User's email address.

first_name

Type: String
Description: User's first name.

last_name

Type: String
Description: User's last name.

company_reference_id

Type: String
Description: Reference ID for the company.

phone

Type: String
Description: User's phone number.

phone_ext

Type: String
Description: Phone extension.

time_zone

Type: String
Description: Time zone of the user.

carrier_name

Type: String
Description: Carrier name associated with the user.

carrier_street

Type: String
Description: Street address of the carrier.

carrier_city

Type: String
Description: City of the carrier.

carrier_state

Type: String
Description: State of the carrier.

carrier_zip

Type: String
Description: Zip code of the carrier.

violation_alerts

Type: String
Description: Frequency of violation alerts (e.g., 1_hour, 2_hours).

terminal_street

Type: String
Description: Street address of the terminal.

terminal_city

Type: String
Description: City of the terminal.

terminal_state

Type: String
Description: State of the terminal.

terminal_zip

Type: String
Description: Zip code of the terminal.

exception_24_hour_restart

Type: Boolean
Description: Indicates if the 24-hour restart exception is enabled.

exception_8_hour_break

Type: Boolean
Description: Indicates if the 8-hour break exception is enabled.

exception_wait_time

Type: Boolean
Description: Indicates if the wait time exception is enabled.

exception_short_haul

Type: Boolean
Description: Indicates if the short haul exception is enabled.

exception_ca_farm_school_bus

Type: Boolean
Description: Indicates if the California farm school bus exception is enabled.

exception_adverse_driving

Type: Boolean
Description: Indicates if the adverse driving exception is enabled.

export_combined

Type: Boolean
Description: Indicates if the combined export option is enabled.

export_recap

Type: Boolean
Description: Indicates if the recap export option is enabled.

export_odometers

Type: Boolean
Description: Indicates if the odometer export option is enabled.

metric_units

Type: Boolean
Description: Indicates if metric units are used.

username

Type: String
Description: Username of the user.

cycle

Type: String
Description: Cycle type associated with the user.

driver_company_id

Type: String
Description: Driver's company ID.

minute_logs

Type: Boolean
Description: Indicates if minute logs are enabled.

duty_status

Type: String
Description: Current duty status of the user.

eld_mode

Type: String
Description: The mode of the vehicle gateway.

drivers_license_number

Type: String
Description: Driver's license number.

drivers_license_state

Type: String
Description: State where the driver's license was issued.

yard_moves_enabled

Type: Boolean
Description: Indicates if yard moves are enabled.

personal_conveyance_enabled

Type: Boolean
Description: Indicates if personal conveyance is enabled.

manual_driving_enabled

Type: Boolean
Description: Indicates if manual driving is enabled.

role

Type: String
Description: Role of the user (e.g., driver).

status

Type: String
Description: Status of the user (e.g., active).

created_at

Type: String
Description: Timestamp when the user was created.

updated_at

Type: String
Description: Timestamp when the user was last updated.

external_ids

Type: Array
Description: External IDs associated with the user.

dot_id

Type: String
Description: DOT ID associated with the user.