---
title: "Create a new user"
method: POST
path: "/v1/users"
---

# Create a new user

`POST /v1/users`

## Headers

- `X-Time-Zone` string
- `X-Metric-Units` boolean
- `X-User-Id` integer

## Request body

- object
  - `first_name` string, required — Enter the first name of the user.
  - `last_name` string, required — Enter the last name of the user.
  - `email` string, required — Specify the email address of the user.
  - `username` string, required — Enter the user name of the user that you are creating.
  - `password` string, required — Specify a password for the user.
  - `role` string, required — Specify the role of the user. Possible values are driver, fleet_user, or admin.
  - `phone` string — Enter the phone number of the user.
  - `phone_country_code` string, required — Specify the user's phone country code. For example if you are creating a user in the USA, enter the country code as <b>+1</b>
  - `phone_ext` string — Enter the phone number extension if available.
  - `driver_company_id` string — Enter the driver's company ID.
  - `time_zone` string — Specify the time zone of the the user's home terminal.
  - `group_ids` object
    - integer[] — Specify a group ID to assign the user to that group.
  - `group_visibility` string — Mention the data visibility for the fleet users. Allowed values are all or limited. NOTE: This parameter is only applicable to users with the role "fleet_user".
  - `carrier_name` string — Enter the name of the carrier you want to associate the user with.
  - `carrier_street` string — Enter the street address of the carrier.
  - `carrier_city` string — Enter the city of the carrier.
  - `carrier_state` string — Enter the state of the carrier.
  - `carrier_zip` string — Enter the ZIP code of the carrier.
  - `violation_alerts` string — Specify the frequency of the violation alerts that you want the Motive Mobile app to show to your drivers. Allowed values are 15_minutes, 30_minutes, 45_minutes, or 1_hour.
  - `terminal_street` string — Enter the street address of the terminal.
  - `terminal_city` string — Specify the city of the terminal.
  - `terminal_state` string — Specify the state when the terminal is located at.
  - `terminal_zip` string — Specify the ZIP code where the terminal is located at.
  - `cycle` string — Sets the user’s primary HOS cycle. Use one of the supported cycle codes mentioned above in a tabular format (Allowed Cycle Values). Each value maps to a specific Hours of Service rule set, such as U.S. property, oil and gas, passenger, California, Texas, Alaska, or Canadian cycle rules.
  - `exception_24_hour_restart` boolean — Set true when driver is using 24 hours restart exception for cycle.
  - `exception_8_hour_break` boolean — Set true when driver is using 8 hour break exception for cycle.
  - `exception_wait_time` boolean — Set true when driver is using wait time exception for cycle.
  - `exception_short_haul` boolean — Set true when driver is using short haul exception for cycle.
  - `exception_ca_farm_school_bus` boolean — Set true when driver is using CA farm/school bus exception for cycle.
  - `exception_adverse_driving` boolean — Set true when driver is allowed to extend duty day by up to 2 hours when adverse driving conditions are encountered
  - `export_combined` boolean — Set true to export logs and DVIRs on the same page.
  - `export_recap` boolean — Set true to export recap with logs.
  - `export_odometers` boolean — Set true to export odometers with logs.
  - `metric_units` boolean — Set true to use metric units.
  - `minute_logs` boolean — Set true to use minute resolution log events.
  - `eld_mode` string, required — Specify the mode of the vehicle gateway. Allowed values are none, logs, and exempt.
  - `drivers_license_number` string — Specify the license number of the driver. <b>NOTE</b>: This is mandatory only if the eld_mode is "logs".
  - `drivers_license_state` string — Specify the issuing state of the driver's license. <b>NOTE</b>: This is mandatory only if the eld_mode is "logs".
  - `yard_moves_enabled` boolean — Set true if yard moves are allowed for the driver.
  - `personal_conveyance_enabled` boolean — Set true if personal conveyance is allowed for the driver.
  - `status` string — Specify the status of the user. Allowed values are active or pending.
  - `cycle2` string — Driver's secondary cycle. Valid values include 70_8, 60_7, 70_8_o, 60_7_o, 70_8_p, 60_7_p, 80_8, 80_8_o, 80_8_p, tx_70_7, ak_70_7, ak_80_8, ak_70_7_o, ak_80_8_o, ak_70_7_p, ak_80_8_p, 70_7, 120_14, canada_oil, 80_7, 120_14_north, and Other.
  - `exception_24_hour_restart2` boolean — Set true when driver is using 24 hours restart exception for secondary cycle.
  - `exception_8_hour_break2` boolean — Set true when driver is using 8 hour break exception for secondary cycle.
  - `exception_wait_time2` boolean — Set true when driver is using wait time exception for secondary cycle.
  - `exception_short_haul2` boolean — Set true when driver is using short haul exception for secondary cycle.
  - `exception_ca_farm_school_bus2` boolean — Set true when driver is using CA farm/school bus exception for secondary cycle.
  - `exception_adverse_driving2` boolean — Set true when driver is allowed to extend duty day by up to 2 hours when adverse driving conditions are encountered
  - `manual_driving_enabled` boolean — Set true when driver is allowed to manually add driving time
  - `external_ids_attributes` object[] — Specify the external ID of the user and the integration name associated with the ID.
    - `external_id` string, required — Denotes the external ID of the entity.
    - `integration_name` string, required — The integration with which the external_id is associated.
    - `external_id_holder_id` integer, required — The unique identifier assigned to the entity such as a user, vehicle, asset, or a group. If your entity is a user, then enter the user ID here. If a vehicle, enter the vehicle ID. Similarly for asset (asset ID), and group (group ID).
    - `external_id_holder_type` string, required — Type of the external ID holder. Allowed values are <ul><li><b>User</b></li><li><b>Vehicle</b></li><li><b>Asset</b></li><li><b>Group</b></ul>
  - `dot_id` string — Driver's DOT number. <b>NOTE</b>: This is mandatory only if the eld_mode is "logs".
  - `custom_user_role` object — Specify the custom user role.
    - `user_role_id` integer — Specify the ID of the user's role. For example - Driver.
    - `group_ids` integer[] — Specify the IDs of the group the user is associated with.
  - `company_reference_id` string — Internal reference id of a user in the company
  - `time_tracking_mode` string — Specify the time tracking mode of the driver. Allowed values are logs, timecards, & not_required.

## Response `200`

200

- object
  - `user` object
    - `id` integer
    - `email` unknown
    - `first_name` string
    - `last_name` string
    - `group_ids` object[]
    - `company_reference_id` string
    - `phone` unknown
    - `phone_country_code` unknown
    - `phone_ext` unknown
    - `time_zone` unknown
    - `metric_units` boolean
    - `carrier_name` string
    - `carrier_street` unknown
    - `carrier_city` unknown
    - `carrier_state` unknown
    - `carrier_zip` unknown
    - `violation_alerts` string
    - `terminal_street` unknown
    - `terminal_city` unknown
    - `terminal_state` unknown
    - `terminal_zip` unknown
    - `cycle` unknown
    - `exception_24_hour_restart` boolean
    - `exception_8_hour_break` boolean
    - `exception_wait_time` boolean
    - `exception_short_haul` boolean
    - `exception_ca_farm_school_bus` boolean
    - `cycle2` unknown
    - `exception_24_hour_restart2` boolean
    - `exception_8_hour_break2` boolean
    - `exception_wait_time2` boolean
    - `exception_short_haul2` boolean
    - `exception_ca_farm_school_bus2` boolean
    - `exception_adverse_driving` boolean
    - `exception_adverse_driving2` boolean
    - `export_combined` boolean
    - `export_recap` boolean
    - `export_odometers` boolean
    - `username` string
    - `driver_company_id` unknown
    - `minute_logs` boolean
    - `duty_status` string
    - `eld_mode` string
    - `drivers_license_number` unknown
    - `drivers_license_state` unknown
    - `yard_moves_enabled` boolean
    - `personal_conveyance_enabled` boolean
    - `manual_driving_enabled` boolean
    - `time_tracking_mode` string
    - `mobile_last_active_at` unknown
    - `mobile_current_sign_in_at` unknown
    - `mobile_last_sign_in_at` unknown
    - `web_last_active_at` unknown
    - `company_connection` object
      - `id` integer
      - `role` string
      - `status` string
      - `company_connection_user_roles` object[]
    - `role` string
    - `status` string
    - `web_current_sign_in_at` unknown
    - `web_last_sign_in_at` unknown
    - `external_ids` object[]
    - `created_at` string
    - `updated_at` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/gomotive/apis/motive.md) · [All operations](https://skmtc.net/gomotive/apis/motive/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gomotive/motive/revisions/c71780e497f5/schema)