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.
NOTE: To add the external Ids, you will require the unique identifier that is assigned to it. This can be obtained from the "Fetch a specific user (ID)" endpoint.
{
"email":"acme@example.com",
"first_name":"John",
"last_name":"Doe",
# other attributes for a user
...
...
...
# add external id for user
"external_ids_attributes":[
{
"id": "9876",
"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_country_code => 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
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_country_code => 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
{
"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_country_code
- Type: String
- Description: The country code associated with the user's phone number. For example, +1 for USA, and +52 for Mexico.
phone_ext
- Type: String
- Description: The extension associated with the user's phone number.
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.