Create a user with the driver, fleet_user, or admin role in the Motive system.

Validate time_tracking_mode and eld_mode

Set time_tracking_mode to a value that is compatible with eld_mode. The API rejects every other combination.

Use the following combinations for drivers:

Optional: Add external IDs

Add external_ids_attributes to associate the user with an identifier from an external system. An external ID is unique for each external_id and integration_name combination.

Provide all required external ID attributes: external_id, integration_name, external_id_holder_id, and external_id_holder_type.

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "password": "<USER_PASSWORD>",
  "role": "driver",
  "phone_country_code": "+1",
  "external_ids_attributes": [
    {
      "external_id": "987",
      "integration_name": "generic_tms",
      "external_id_holder_id": 9876,
      "external_id_holder_type": "User"
    }
  ]
}

Optional: Restrict a fleet user's group access

To restrict a fleet user's access, set group_visibility to limited and include the group IDs in custom_user_role.group_ids. Do not send these group IDs in the top-level group_ids attribute.

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "password": "<USER_PASSWORD>",
  "role": "fleet_user",
  "phone_country_code": "+1",
  "group_visibility": "limited",
  "custom_user_role": {
    "user_role_id": 9,
    "group_ids": [101]
  }
}

Optional: Add a driver to groups

To add a driver to groups, send the group IDs in the user's top-level group_ids attribute.

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "username": "john.doe",
  "password": "<USER_PASSWORD>",
  "role": "driver",
  "phone_country_code": "+1",
  "group_ids": [1, 2]
}

Response parameters

user

• Type: Object
• Description: Details of the created user.

id

• Type: Integer
• Description: Unique identifier for the user.

first_name

• Type: String
• Description: User's first name.

last_name

• Type: String
• Description: User's last name.

email

• Type: String
• Description: User's primary email address.

role

• Type: String
• Description: System role assigned to the user, such as driver.

status

• Type: String
• Description: Current account status, such as active.

phone

• Type: String
• Description: User's primary phone number.

phone_country_code

• Type: String
• Description: ISO country code for the primary phone number.

phone_ext

• Type: String or null
• Description: Primary phone-number extension, when provided.

phone2

• Type: String
• Description: User's secondary phone number.

phone_country_code2

• Type: String
• Description: ISO country code for the secondary phone number.

time_zone

• Type: String
• Description: User's preferred time zone.

metric_units

• Type: Boolean
• Description: Whether the user prefers metric units.

username

• Type: String
• Description: Unique username used for authentication.

driver_company_id

• Type: String
• Description: Internal company identifier assigned to the driver.

drivers_license_number

• Type: String
• Description: Driver's license number.

drivers_license_state

• Type: String
• Description: State, region, or jurisdiction that issued the driver's license.

drivers_license_country

• Type: String
• Description: Country code for the driver's license issuing authority.

time_tracking_mode

• Type: String
• Description: Method used to track the driver's work hours.

joined_at

• Type: String (date)
• Description: Date when the user joined the company or platform.

user_notes

• Type: String
• Description: Administrator notes about the user.

require_job_type_for_timecard_details

• Type: Boolean
• Description: Whether a job type is required when the user submits timecards.

company_reference_id

• Type: String
• Description: External company reference identifier for the user.

group_ids

• Type: Array of integers
• Description: Group identifiers associated with the user.

tachograph_card_number

• Type: String
• Description: Driver's smart tachograph card number.

tachograph_card_expiry_date

• Type: String (date)
• Description: Expiration date of the driver's tachograph card.

external_ids

• Type: Array of objects
• Description: External integration mapping identifiers.

external_id

• Type: String
• Description: Identifier in the external integration system.

integration_name

• Type: String
• Description: Name of the external integration platform.

company_connection

• Type: Object
• Description: Details about the user's connection to the company.

company_connection_user_roles

• Type: Array
• Description: Sub-roles assigned to the user in the company connection.

mobile_last_active_at

• Type: String (timestamp)
• Description: Date and time when the user was last active in the mobile application.

mobile_current_sign_in_at

• Type: String (timestamp)
• Description: Date and time when the user started their current mobile session.

mobile_last_sign_in_at

• Type: String (timestamp)
• Description: Date and time when the user started their previous mobile session.

web_last_active_at

• Type: String (timestamp) or null
• Description: Date and time when the user was last active in the web application.

created_at

• Type: String (timestamp)
• Description: Date and time when the user record was created.

updated_at

• Type: String (timestamp)
• Description: Date and time when the user record was last updated.