openapi: 3.2.0
info:
  title: APIs Users API
  description: Documentation for Users APIs
  version: '1.0'
  contact: {}
servers:
- url: https://integrations.mavenmachines.com
tags:
- name: users
paths:
  /users:
    get:
      operationId: UsersController_getUsers
      summary: GET /users
      description: "Retrieves a list of users in the Maven system. \n    Retrieves a company location record in the Maven system. A companyLocationId or externalCompanyLocationId must be supplied. \n    If both a supplied, Maven will first search by companyLocationId."
      parameters:
      - name: userId
        required: false
        in: query
        description: Unique identifier for user
        example: 17161
        schema:
          type: number
      - name: externalUserId
        required: false
        in: query
        description: Unique external identifier for user
        example: USER123
        schema:
          type: string
      - name: offset
        required: false
        in: query
        example: 0
        description: Pagination result offset
        schema:
          type: number
      responses:
        '200':
          description: A successful API response for fetching users from the Maven system
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsersApiResponse'
      tags:
      - users
      security:
      - api_key: []
    post:
      operationId: UsersController_createUser
      summary: POST /users
      description: "\n    API endpoints for interacting with user records in the Maven system.\n    \n    Creates a user in the Maven system\n    "
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequestDto'
      responses:
        '201':
          description: A successful API response for user creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserApiResponse'
      tags:
      - users
      security:
      - api_key: []
    put:
      operationId: UsersController_updateUser
      summary: PUT /users
      description: "\n    Updates a user in the Maven system. Either a userId or externalUserId needs to be provided. \n    If both are provided, Maven will first match on userId.\n    "
      parameters:
      - name: userId
        required: false
        in: query
        description: Unique identifier for user
        example: 17161
        schema:
          type: number
      - name: externalUserId
        required: false
        in: query
        description: Unique external identifier for user
        example: USER123
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequestDto'
      responses:
        '200':
          description: A successful API response for user update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserApiResponse'
      tags:
      - users
      security:
      - api_key: []
components:
  schemas:
    GlobalPagination:
      type: object
      properties:
        total:
          type: number
          description: Total number of records
          example: 15
        hasNextPage:
          type: boolean
          description: Bool to indicate if there is another page of data to request.
          example: false
        nextPageOffset:
          type: number
          description: For subsequent requests, set offset to the value of this field to get the next page
          example: null
      required:
      - total
      - hasNextPage
      - nextPageOffset
    EldConfigurationOverrides:
      type: object
      properties:
        timezone:
          type: string
          description: Optional.  Allows overriding the user's terminal timezone or default timezone set in the eld configuration.  If user has no terminal and the company has not set up a default terminal configuration, eld configuration for this user may fail
          example: US/Eastern
        ruleset:
          type: string
          description: Optional.  Allows overriding the default ruleset set in the eld configuration.  If no value is provided and no default eld configuration is set, then the ruleset will default to US Property 70Hr/8day
          example: CALIFORNIA_INTRASTATE_PROPERTY
        logDayStartTime:
          type: number
          description: Optional.  Allows setting of the log start time of the user to either noon or midnight.  Defaults to midnight if not provided.  Set 0 for midnight, or 12 for noon.  Other values will be ignored.
          example: 12
        exemptStatus:
          type: boolean
          description: Optional.  Allows setting a user as eld exempt.  Note if this value is provided, a value for exemptReason must also be provided.  DO NOT provide a value for ruleset
          example: true
        exemptReason:
          type: string
          description: Optional.  Allows setting the exempt reason for a user.  This value is only applied if the api call has also provided a value for exemptStatus.
          example: Maintenance Mechanic
    Login:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address used to log into the Maven app. May be different than portal login email.
          example: johnmdoe@example.com
        phone:
          type: string
          description: Phone number used to log into the Maven app
          example: '+14125555555'
      required:
      - email
      - phone
    GetUsersApiResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/CreateUserApiResponse'
        pagination:
          $ref: '#/components/schemas/GlobalPagination'
      required:
      - users
    DriversLicense:
      type: object
      properties:
        number:
          type: string
          description: Driver’s license number
          example: '12345678'
        state:
          type: string
          description: Driver’s license issuing state
          enum:
          - AL
          - AK
          - AZ
          - AR
          - CA
          - CO
          - CT
          - DC
          - DE
          - FL
          - GA
          - HI
          - IA
          - ID
          - IL
          - IN
          - KS
          - KY
          - LA
          - MA
          - MD
          - ME
          - MI
          - MN
          - MO
          - MS
          - MT
          - NC
          - ND
          - NE
          - NH
          - NJ
          - NM
          - NV
          - NY
          - OH
          - OK
          - OR
          - PA
          - RI
          - SC
          - SD
          - TN
          - TX
          - UT
          - VA
          - VT
          - WA
          - WI
          - WV
          - WY
          - AS
          - GU
          - MP
          - VI
          - AB
          - BC
          - MB
          - NB
          - NF
          - NS
          - NT
          - 'ON'
          - PE
          - QC
          - SK
          - YT
          - AG
          - BN
          - BS
          - CH
          - CI
          - CL
          - CP
          - CS
          - DF
          - DG
          - GE
          - GJ
          - HD
          - JA
          - MC
          - MR
          - MX
          - NA
          - NL
          - OA
          - PU
          - QE
          - QI
          - SI
          - SL
          - SO
          - TA
          - TB
          - TL
          - VC
          - YU
          - ZA
          - OT
        expirationDate:
          type: string
          format: date
          description: Driver’s license expiration date
          example: '2020-12-31'
        type:
          type: string
          description: Driver’s license type classification
          enum:
          - A
          - B
          - C
          - NC
        endorsements:
          description: 'Driver’s license endorsement classifications. Can be one or more of: ["H","N","P","S","T","X","HM126"]'
          example:
          - H
          type: array
          items:
            type: string
        endorsementExpirations:
          type: object
          description: Optional. Allows setting the expiration dates of endorsements.
          example:
            H: '2024-01-01'
        restrictions:
          description: 'Driver’s license restriction classifications. Can be one or more of: ["E","L","M","N","O","V","Z"]'
          example:
          - E
          type: array
          items:
            type: string
      required:
      - number
      - state
      - expirationDate
      - type
      - endorsements
      - restrictions
    UpdateUserRequestDto:
      type: object
      properties:
        middle:
          type: string
          description: Middle name of user
          example: M
        driversLicense:
          $ref: '#/components/schemas/DriversLicense'
        externalUserId:
          type: string
          description: Unique external identifier for user
          example: USER123
        login:
          $ref: '#/components/schemas/UpdateLogin'
        first:
          type: string
          description: First name of user
          example: John
        last:
          type: string
          description: Last name of user
          example: Doe
        active:
          type: boolean
          description: True for active drivers. false for inactive drivers
          example: true
        externalTerminalIds:
          description: External terminal identifiers associated with this user
          example:
          - PGH
          type: array
          items:
            type: string
        externalGroupIds:
          description: External group identifiers associated with this user
          example:
          - GROUP123
          type: array
          items:
            type: string
        roles:
          description: Roles assigned to this user
          example:
          - Driver
          type: array
          items:
            type: string
    UserGroup:
      type: object
      properties:
        externalGroupId:
          type: string
          description: External identifier for group
          example: GROUP123
        name:
          type: string
          description: Name of group
          example: East Division
      required:
      - externalGroupId
      - name
    CreateUserApiResponse:
      type: object
      properties:
        externalUserId:
          type: string
          description: Unique external identifier for user
          example: USER123
        userId:
          type: number
          description: Unique identifier for user
          example: 17161
        createdOn:
          type: string
          description: Timestamp of record creation in the Maven system
          example: '2020-05-01T13:01:01Z'
        updatedOn:
          type: string
          description: Timestamp of last record update in the Maven system
          example: '2020-05-01T14:59:59Z'
        active:
          type: boolean
          description: True for active drivers. false for inactive drivers
          example: true
        first:
          type: string
          description: First name of user
          example: John
        middle:
          type: string
          description: Middle name of user
          example: M
        last:
          type: string
          description: Last name of user
          example: Doe
        terminals:
          type: array
          items:
            $ref: '#/components/schemas/UserTerminal'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/UserGroup'
        roles:
          description: Roles assigned to this user
          example:
          - Driver
          type: array
          items:
            type: string
        login:
          $ref: '#/components/schemas/Login'
        driversLicense:
          $ref: '#/components/schemas/DriversLicense'
      required:
      - externalUserId
      - userId
      - createdOn
      - updatedOn
      - active
      - first
      - middle
      - last
      - terminals
      - groups
      - roles
      - login
      - driversLicense
    UserTerminal:
      type: object
      properties:
        externalTerminalId:
          type: string
          description: External identifier for terminal
          example: PGH
        name:
          type: string
          description: Name of terminal
          example: Pittsburgh
      required:
      - externalTerminalId
      - name
    UpdateLogin:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address used to log into the Maven app. May be different than portal login email.
          example: johnmdoe@example.com
        phone:
          type: string
          description: Phone number used to log into the Maven app
          example: '+14125555555'
        password:
          type: string
          format: password
          description: Password used to log into the Maven app
          example: password1
    UserConfigurationOverrides:
      type: object
      properties:
        eldConfig:
          $ref: '#/components/schemas/EldConfigurationOverrides'
    CreateUserRequestDto:
      type: object
      properties:
        middle:
          type: string
          description: Middle name of user
          example: M
        driversLicense:
          $ref: '#/components/schemas/DriversLicense'
        login:
          $ref: '#/components/schemas/CreateLogin'
        externalUserId:
          type: string
          description: Unique external identifier for user
          example: USER123
        first:
          type: string
          description: First name of user
          example: John
        last:
          type: string
          description: Last name of user
          example: Doe
        externalTerminalIds:
          description: External terminal identifiers associated with this user. either an externalTerminalId or externalGroupId is required
          example:
          - PGH
          type: array
          items:
            type: string
        externalGroupIds:
          description: External group identifiers associated with this user.  either an externalTerminalId or externalGroupId is required
          example:
          - GROUP123
          type: array
          items:
            type: string
        roles:
          description: Required. roles assigned to this user. an invalid role will error out
          example:
          - Driver
          type: array
          items:
            type: string
        userConfigurationOverrides:
          $ref: '#/components/schemas/UserConfigurationOverrides'
      required:
      - login
      - externalUserId
      - first
      - last
      - roles
    CreateLogin:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address used to log into the Maven app. May be different than portal login email.
          example: johnmdoe@example.com
        phone:
          type: string
          description: Phone number used to log into the Maven app
          example: '+14125555555'
        password:
          type: string
          format: password
          description: Password used to log into the Maven app
          example: password1
      required:
      - password
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: apiKey
x-readme:
  explorer-enabled: true
  proxy-enabled: true