Lytx Trips (GO9) API

openapi: 3.0.1
info:
  title: Lytx..Management.Api Consent Trips (GO9) API
  description: 'API for retrieving and updating user consent status, requiring authentication.

    '
  version: 1.0.0
servers:
- url: https://api.lytx.com/consent-management
security:
- bearerAuth: []
tags:
- name: Trips (GO9)
paths:
  /plus/v1/trips:
    get:
      summary: Get Telematics Trips Data
      description: Retrieve a list of all the trips in an organization or subset of an organization
      tags:
      - Trips (GO9)
      parameters:
      - name: deviceId
        in: query
        required: false
        schema:
          type: string
          nullable: true
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Can use either device serial number or device ID.
      - name: groupId
        in: query
        required: false
        schema:
          type: string
          nullable: true
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Can use group ID or root group ID. All descendant groups under the specified group are included in the response.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          nullable: true
          example: '5000'
        description: Number of records to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          nullable: true
          example: '1500'
        description: Record to start with.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-01'
        description: The start date must be within the last 60 days.
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-02'
        description: End date to filter by.
      - name: order
        in: query
        required: false
        schema:
          type: string
          nullable: true
          example: asc
        description: Sort direction.
      - name: sortProperty
        in: query
        required: false
        schema:
          type: string
          nullable: true
          example: name
        description: Name of property to sort on.
      - name: version
        in: query
        required: true
        schema:
          type: string
          nullable: true
          example: 1
        description: API version number.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TripsResponseViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Bad Request
                  message:
                    type: string
                    example: Invalid request data
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: Access denied
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Forbidden
                  message:
                    type: string
                    example: Non-permited user
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Not Found
                  message:
                    type: string
                    example: No information found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Internal Server Error
                  message:
                    type: string
                    example: An unexpected server error occurred
components:
  schemas:
    StopPointResponseViewModel:
      type: object
      properties:
        x:
          type: number
          format: double
        y:
          type: number
          format: double
    UserResponseViewModel:
      type: object
      properties:
        id:
          type: string
          nullable: false
          example: 1b33bcbe-15d3-445e-a06f-dda61208ad18
          description: Unique identifier for the user.
        firstName:
          type: string
          nullable: false
          example: John
          description: First name of the user.
        lastName:
          type: string
          nullable: false
          example: Doe
          description: Last name of the user.
        name:
          type: string
          nullable: true
          example: John Doe
          description: Full name of the user.
        licenseNumber:
          type: string
          nullable: true
          example: DL-123456
          description: License number of the user.
        licenseProvince:
          type: string
          nullable: true
          example: CA
          description: Province/state of the license.
        acceptedEULA:
          type: integer
          nullable: false
          example: 1
          description: Version of the EULA accepted.
        driveGuideVersion:
          type: integer
          example: 2
          description: Drive Guide version used by the user.
        wifiEULA:
          type: integer
          example: 1
          description: WiFi EULA acceptance version.
        activeFrom:
          type: string
          format: date-time
          example: '2023-10-06T00:22:30.000Z'
          description: Start date from which the user is active (UTC).
        activeTo:
          type: string
          format: date-time
          example: '2025-10-06T00:22:30.000Z'
          description: End date until which the user is active (UTC).
        lastAccessDate:
          type: string
          format: date-time
          example: '2025-09-15T12:22:30.000Z'
          description: Last time the user accessed the system.
        companyName:
          type: string
          example: Acme Corp
          description: Name of the company the user belongs to.
        companyAddress:
          type: string
          example: 123 Main Street, Toronto, ON
          description: Address of the company.
        carrierNumber:
          type: string
          example: CARR123
          description: Carrier number.
        isDriver:
          type: boolean
          example: true
          description: Indicates whether the user is a driver.
        isEmailReportEnabled:
          type: boolean
          example: false
          description: Whether email reports are enabled for the user.
        language:
          type: string
          example: en-US
          description: Preferred language of the user.
        timeZoneId:
          type: string
          example: America/Toronto
          description: Time zone of the user.
        userAuthenticationType:
          type: integer
          example: 1
          description: Authentication type of the user.
        zoneDisplayMode:
          type: integer
          example: 2
          description: Zone display mode preference.
        driverGroups:
          type: array
          items:
            $ref: '#/components/schemas/GroupResponseViewModel'
          description: List of driver groups associated with the user.
        companyGroups:
          type: array
          items:
            $ref: '#/components/schemas/GroupResponseViewModel'
          description: List of company groups associated with the user.
        keys:
          type: array
          items:
            type: object
          description: List of keys assigned to the user.
        bookmarks:
          type: array
          items:
            type: object
          description: List of bookmarks for the user.
        viewDriversOwnDataOnly:
          type: boolean
          example: false
          description: Whether user can only view their own driver data.
        designation:
          type: string
          example: Manager
          description: Job designation of the user.
        employeeNo:
          type: string
          example: EMP12345
          description: Employee number of the user.
        phoneNumber:
          type: string
          example: +1-123-456-7890
          description: Phone number of the user.
        phoneNumberExtension:
          type: string
          example: '101'
          description: Extension for the phone number.
    GroupResponseViewModel:
      type: object
      properties:
        id:
          type: string
          nullable: false
          example: grp-123
          description: Unique identifier of the group.
        name:
          type: string
          nullable: false
          example: Drivers Group
          description: Name of the group.
        comment:
          type: string
          example: Main driver group
          description: Additional comments about the group.
        reference:
          type: string
          example: REF123
          description: Reference information for the group.
        parent:
          $ref: '#/components/schemas/GroupResponseViewModel'
        children:
          type: array
          items:
            $ref: '#/components/schemas/GroupResponseViewModel'
          description: List of child groups.
        color:
          $ref: '#/components/schemas/GroupResponseViewModel'
    DeviceResponseViewModel:
      type: object
      properties:
        id:
          type: string
          nullable: false
          example: 1b33bcbe-15d3-445e-a06f-dda61208ad18
          description: Unique ID for the device.
        activeFrom:
          type: string
          format: date-time
          nullable: true
          example: '2023-10-06T00:22:30.000Z'
          description: Start date when the device became active.
        activeTo:
          type: string
          format: date-time
          nullable: true
          example: '2025-10-06T00:22:30.000Z'
          description: End date until which the device remains active.
        comment:
          type: string
          nullable: true
          example: Installed in vehicle A123
          description: Additional comments about the device.
        groups:
          type: array
          items:
            type: string
          nullable: true
          example:
          - Group1
          - Group2
          description: List of groups associated with the device.
        timeZoneId:
          type: string
          nullable: true
          example: America/Toronto
          description: Time zone assigned to the device.
        deviceFlags:
          type: string
          nullable: true
          example: FLAG_001
          description: Flags indicating device-specific properties.
        deviceType:
          type: string
          nullable: true
          example: GO9
          description: Type/model of the device.
        hardwareId:
          type: string
          nullable: true
          example: HW-ABC-12345
          description: Hardware identifier of the device.
        ignoreDownloadsUntil:
          type: string
          format: date-time
          nullable: true
          example: '2025-05-15T12:00:00.000Z'
          description: The device should ignore downloads until this time.
        maxSecondsBetweenLogs:
          type: integer
          nullable: true
          example: 300
          description: Maximum number of seconds allowed between logs.
        name:
          type: string
          nullable: true
          example: Device A123
          description: Name assigned to the device.
        productId:
          type: string
          nullable: true
          example: PROD-456
          description: Product identifier of the device.
        serialNumber:
          type: string
          nullable: true
          example: SN123456789
          description: Serial number of the device.
        timeToDownload:
          type: string
          format: date-time
          nullable: true
          example: '2025-09-20T10:00:00.000Z'
          description: Scheduled time for the device to download updates.
        workTime:
          type: string
          nullable: true
          example: 08:00-17:00
          description: Work time configuration of the device.
        registerDeviceResultLite:
          type: object
          nullable: true
          description: Registration result details for the device.
        devicePlanBillingInfo:
          type: object
          nullable: true
          description: Billing information for the device plan.
        deviceReplacementInfo:
          type: object
          nullable: true
          description: Replacement information for the device.
        customProperties:
          type: object
          nullable: true
          description: Custom properties associated with the device.
        mediaFiles:
          type: array
          items:
            type: string
          nullable: true
          example:
          - file1.jpg
          - file2.mp4
          description: Media files linked to the device.
        tmpTrailerId:
          type: string
          nullable: true
          example: TRAILER-123
          description: Temporary trailer ID linked to the device.
        version:
          type: string
          nullable: true
          example: v1.2.3
          description: Version information of the device.
    TripsResponseViewModel:
      type: object
      properties:
        afterHoursDistance:
          type: number
          format: double
        afterHoursDrivingDuration:
          type: string
          format: duration
        afterHoursEnd:
          type: boolean
        afterHoursStart:
          type: boolean
        afterHoursStopDuration:
          type: string
          format: duration
        averageSpeed:
          type: number
          format: double
        distance:
          type: number
          format: double
        drivingDuration:
          type: string
          format: duration
        engineHours:
          type: number
          format: double
        idlingDuration:
          type: string
          format: duration
        isSeatBeltOff:
          type: boolean
        maximumSpeed:
          type: number
          format: double
        nextTripStart:
          type: string
          format: date-time
        speedRange1:
          type: integer
        speedRange1Duration:
          type: string
          format: duration
        speedRange2:
          type: integer
        speedRange2Duration:
          type: string
          format: duration
        speedRange3:
          type: integer
        speedRange3Duration:
          type: string
          format: duration
        start:
          type: string
          format: date-time
        stop:
          type: string
          format: date-time
        stopDuration:
          type: string
          format: duration
        stopPoint:
          $ref: '#/components/schemas/StopPointResponseViewModel'
        workDistance:
          type: number
          format: double
        workDrivingDuration:
          type: string
          format: duration
        workStopDuration:
          type: string
          format: duration
        device:
          $ref: '#/components/schemas/DeviceResponseViewModel'
        driver:
          $ref: '#/components/schemas/UserResponseViewModel'
        id:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer