MileIQ users API

openapi: 3.1.0
info:
  title: MileIQ External groups users API
  description: External API for integrating with the MileIQ Platform.
  termsOfService: https://mileiq.com/terms
  contact:
    name: MileIQ
    url: https://developer.mileiq.com/
    email: support@mileiq.com
  version: 1.4.0
servers:
- url: https://external-api.mileiq.com
  description: MileIQ External API
tags:
- name: users
paths:
  /v1/users/me:
    get:
      tags:
      - users
      summary: Get Current User Profile
      description: Retrieve comprehensive profile information for the currently authenticated user, including personal details, contact information, and account status.
      operationId: get_me
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successfully retrieved current user profile. Returns detailed user information including name, email addresses, username, and account status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSchema'
        '401':
          description: Authentication failed. Invalid or missing authorization token.
        '403':
          description: Insufficient permissions. User does not have the required 'users_read' scope or is not authenticated.
        '404':
          description: User not found. The authenticated user profile could not be located in the system.
        '429':
          description: Rate limit exceeded. Maximum 30 requests per minute allowed.
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/users/{user_id}:
    get:
      tags:
      - users
      summary: Get User by ID
      description: 'Retrieve detailed profile information for a specific user by their unique identifier. Note: Users can only access their own profile data due to privacy restrictions.'
      operationId: get_user
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successfully retrieved user profile. Returns detailed user information including name, email addresses, username, and account status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSchema'
        '401':
          description: Authentication failed. Invalid or missing authorization token.
        '403':
          description: Insufficient permissions. User does not have the required 'users_read' scope, is not authenticated, or is attempting to access another user's profile.
        '404':
          description: User not found. The specified user ID does not exist or is not accessible.
        '422':
          description: Validation error. Invalid user ID format provided.
        '429':
          description: Rate limit exceeded. Maximum 30 requests per minute allowed.
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
  /v1/users/{user_id}/drives:
    get:
      tags:
      - users
      summary: Get User Drives
      description: 'Retrieve a paginated list of drives for a specific user, ordered by last modification date (most recent first). Supports filtering by drive classification (business, personal, or all) and date ranges. Note: The ''created'' field represents when the drive was recorded in the system, while ''started_at'' and ''ended_at'' indicate the actual drive times. Users can only access their own drive data. Returns comprehensive drive information including locations, distance, value calculations, and metadata.'
      operationId: get_user_drives
      parameters:
      - name: classification
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/DriveClassificationFilter'
          description: Drive classification
          default: business
        description: Drive classification
        example: business
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          exclusiveMinimum: 0
          description: The number of drives to retrieve
          default: 100
          title: Limit
        description: The number of drives to retrieve
        example: '50'
      - name: date_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: The end date of the range to retrieve drives for based on the defined filter_by param (exclusive). Filter_by needs to be set for this field to be used. Should be in UTC
          title: Date Before
        description: The end date of the range to retrieve drives for based on the defined filter_by param (exclusive). Filter_by needs to be set for this field to be used. Should be in UTC
        example: '2024-05-05T16:01:07Z'
      - name: date_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: The start date of the range to retrieve drives for based on the defined filter_by param (exclusive). Filter_by needs to be set for this field to be used. Should be in UTC
          title: Date After
        description: The start date of the range to retrieve drives for based on the defined filter_by param (exclusive). Filter_by needs to be set for this field to be used. Should be in UTC
        example: '2024-05-05T16:01:07Z'
      - name: filter_by
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/GetDrivesRequestFilterBy'
          - type: 'null'
          description: Use 'ended' to filter by the date the drive has ended. Use 'modified' to filter by the date the drive was last updated
          title: Filter By
        description: Use 'ended' to filter by the date the drive has ended. Use 'modified' to filter by the date the drive was last updated
      - name: modified_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: The end date of the range to retrieve drives for (exclusive). If the drive was reviewed by an admin, this will be the last review date. If not, this will be the same as the date it was reported. [DEPRECATED] Use [date_before, date_after] + filter_by instead
          title: Modified Before
        description: The end date of the range to retrieve drives for (exclusive). If the drive was reviewed by an admin, this will be the last review date. If not, this will be the same as the date it was reported. [DEPRECATED] Use [date_before, date_after] + filter_by instead
        example: '2024-05-12T16:01:07Z'
      - name: modified_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: The start date of the range to retrieve drives for (exclusive). If the drive was reviewed by an admin, this will be the last review date. If not, this will be the same as the date it was reported. [DEPRECATED] Use [date_before, date_after] + filter_by instead
          title: Modified After
        description: The start date of the range to retrieve drives for (exclusive). If the drive was reviewed by an admin, this will be the last review date. If not, this will be the same as the date it was reported. [DEPRECATED] Use [date_before, date_after] + filter_by instead
        example: '2024-05-05T16:01:07Z'
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successfully retrieved user drives. Returns paginated list of drives with complete details including locations, distance calculations, monetary values, and trip metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDrivesResponse'
        '400':
          description: Bad request. Invalid query parameters such as limit exceeding maximum allowed value, invalid date format, or unsupported classification filter.
        '401':
          description: Authentication failed. Invalid or missing authorization token.
        '403':
          description: Insufficient permissions. User does not have the required drive read scopes, is not authenticated, or is attempting to access another user's drives.
        '404':
          description: User not found. The specified user ID does not exist or is not accessible.
        '422':
          description: Validation error. Invalid user ID format or malformed query parameters.
        '429':
          description: Rate limit exceeded. Maximum 20 requests per minute allowed.
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
components:
  schemas:
    GetDrivesRequestFilterBy:
      type: string
      enum:
      - modified
      - ended
      title: GetDrivesRequestFilterBy
    DistanceUnits:
      type: string
      enum:
      - mi
      - km
      title: DistanceUnits
      description: Different distance units used for drives
    Address:
      properties:
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Country name or code where the location is situated
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: State, province, or administrative region within the country
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: City or municipality name
        street:
          anyOf:
          - type: string
          - type: 'null'
          title: Street
          description: Street address including number and street name
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Postal Code
          description: Postal or ZIP code for the location
      type: object
      title: Address
      description: Geographical address information for drive locations with standardized components
    DriveSchema:
      properties:
        distance:
          anyOf:
          - $ref: '#/components/schemas/Distance'
          - $ref: '#/components/schemas/DistanceWithDiscount'
          - type: 'null'
          title: Distance
          description: The distance of the drive
        value:
          anyOf:
          - $ref: '#/components/schemas/Value'
          - type: 'null'
          description: The value of the drive
        toll_fees:
          anyOf:
          - $ref: '#/components/schemas/Value'
          - type: 'null'
          description: The toll fees of the drive
        parking_fees:
          anyOf:
          - $ref: '#/components/schemas/Value'
          - type: 'null'
          description: The parking fees of the drive
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The description of the drive from the driver notes
        entry:
          $ref: '#/components/schemas/DriveEntry'
          description: The entry method of the drive
        classification:
          anyOf:
          - $ref: '#/components/schemas/DriveClassification'
          - type: 'null'
          description: The classification of the drive
        purpose:
          anyOf:
          - type: string
          - type: 'null'
          title: Purpose
          description: The purpose of the drive
        start:
          anyOf:
          - $ref: '#/components/schemas/Geolocation'
          - type: 'null'
          description: The start location of the drive
        end:
          anyOf:
          - $ref: '#/components/schemas/Geolocation'
          - type: 'null'
          description: The end location of the drive
        drive_id:
          type: integer
          title: Drive Id
          description: The ID of the drive
        created:
          type: string
          format: date-time
          title: Created
          description: The time in which the drive was reported. In ISO 8601 format
        modified:
          type: string
          format: date-time
          title: Modified
          description: The last time the drive was reviewed. If it was not reviewed, should be the same as created.In ISO 8601 format
        started_at:
          type: string
          format: date-time
          title: Started At
          description: The start time for the drive in ISO 8601 format
        ended_at:
          type: string
          format: date-time
          title: Ended At
          description: The end time for the drive in ISO 8601 format
      type: object
      required:
      - distance
      - value
      - toll_fees
      - parking_fees
      - description
      - entry
      - classification
      - purpose
      - start
      - end
      - drive_id
      - created
      - modified
      - started_at
      - ended_at
      title: DriveSchema
      description: Represents a single drive (trip) with all its details.
    Value:
      properties:
        amount:
          type: integer
          title: Amount
          description: The amount of the value, in the smallest unit of currency
        currency:
          $ref: '#/components/schemas/Currency'
          description: The currency of the value, in ISO 4217 format
      type: object
      required:
      - amount
      - currency
      title: Value
      description: Represent the value of a drive (excluding toll & parking fees)
    DistanceWithDiscount:
      properties:
        amount:
          type: number
          title: Amount
          description: The amount of the distance, in the specified units
        units:
          $ref: '#/components/schemas/DistanceUnits'
          description: The units of the distance
        discounted:
          anyOf:
          - type: integer
          - type: 'null'
          title: Discounted
          description: The discounted amount of the distance, in the specified units
      type: object
      required:
      - amount
      - units
      title: DistanceWithDiscount
      description: Represent the distance for a drive, with a discounted value set by the team
    Distance:
      properties:
        amount:
          type: number
          title: Amount
          description: The amount of the distance, in the specified units
        units:
          $ref: '#/components/schemas/DistanceUnits'
          description: The units of the distance
      type: object
      required:
      - amount
      - units
      title: Distance
      description: Represent the distance for a drive
    DriveEntry:
      type: string
      enum:
      - manual
      - automatic
      title: DriveEntry
      description: Whether the drive was entered manually or automatically
    DriveClassificationFilter:
      type: string
      enum:
      - business
      - personal
      - all
      title: DriveClassificationFilter
    Geolocation:
      properties:
        name:
          type: string
          title: Name
          description: The name of the location
        lat:
          anyOf:
          - type: string
          - type: 'null'
          title: Lat
          description: The latitude of the location
        lon:
          anyOf:
          - type: string
          - type: 'null'
          title: Lon
          description: The longitude of the location
        time:
          type: string
          format: date-time
          title: Time
          description: The time in ISO 8601 format
        address:
          anyOf:
          - $ref: '#/components/schemas/Address'
          - type: 'null'
          description: The address of the location
      type: object
      required:
      - name
      - time
      title: Geolocation
      description: Represent the geolocation information of a drive
    Currency:
      type: string
      enum:
      - USD
      - CAD
      - GBP
      title: Currency
      description: Different currencies used for drives
    DriveClassification:
      type: string
      enum:
      - business
      - personal
      - unclassified
      title: DriveClassification
      description: Drive classifications
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Email:
      properties:
        value:
          type: string
          title: Value
          description: The actual email address in standard email format (e.g., user@example.com)
        type:
          type: string
          title: Type
          description: Classification of the email address - typically 'work' for business emails or 'personal' for private emails
        primary:
          type: boolean
          title: Primary
          description: Boolean flag indicating whether this is the user's primary/default email address for communications
          default: true
      type: object
      required:
      - value
      - type
      title: Email
      description: Email address information with classification and priority designation
    Name:
      properties:
        givenName:
          type: string
          title: Givenname
          description: User's first name (given name) as recorded in their profile
        familyName:
          type: string
          title: Familyname
          description: User's last name (family name/surname) as recorded in their profile
        formatted:
          anyOf:
          - type: string
          - type: 'null'
          title: Formatted
          description: Full name formatted for display purposes, combining first and last names in a readable format
      type: object
      required:
      - givenName
      - familyName
      title: Name
      description: Complete name information for a user including both individual components and formatted display
    UserSchema:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the user (Parse ID) - used for API operations and internal references
        userName:
          type: string
          title: Username
          description: User's login username, typically their email address used for authentication
        name:
          $ref: '#/components/schemas/Name'
          description: Structured name information including first name, last name, and formatted display name
        emails:
          items:
            $ref: '#/components/schemas/Email'
          type: array
          title: Emails
          description: Collection of email addresses associated with the user, including primary/secondary designation and type classification
        active:
          type: boolean
          title: Active
          description: Account status flag indicating whether the user account is currently active and operational
          default: true
        displayName:
          anyOf:
          - type: string
          - type: 'null'
          title: Displayname
          description: Formatted display name used throughout the application interface for user identification
      type: object
      required:
      - id
      - userName
      - name
      - emails
      title: UserSchema
      description: Complete user profile information including identity, contact details, and account status
    GetDrivesResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/DriveSchema'
          type: array
          title: Results
          description: Array of drive objects containing comprehensive trip information including locations, distances, values, and metadata
        has_more:
          type: boolean
          title: Has More
          description: Pagination indicator - true if additional drives exist beyond the current result set within the specified filters and date range
      type: object
      required:
      - results
      - has_more
      title: GetDrivesResponse