Lytx Geofences (DriveCam) API

openapi: 3.2.0
info:
  title: Lytx.Geofences.Api Geofences (DriveCam) API
  version: 1.0.0
servers:
- url: https://api.lytx.com
security:
- bearerAuth: []
tags:
- name: Geofences (DriveCam)
paths:
  /v1/geofences:
    post:
      tags:
      - Geofences (DriveCam)
      summary: Create Geofence
      description: Create a Geofence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddGeofenceRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleGeofenceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: Bad Request
                  message:
                    type: string
                    example: Invalid ShapeType
        '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-permitted 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
    get:
      tags:
      - Geofences (DriveCam)
      description: Retrieve a list of Geofences filtered by identifier. Only 0 or 1 identifiers are allowed in a query.
      summary: Retrieve Geofences
      parameters:
      - name: geofenceIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Unique Id for Geofence
      - name: deviceIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Device Id or Serial Number.
      - name: groupIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Group Identifier.
      - name: vehicleIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Vehicle Identifier or Vin.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-01'
        description: Filter by start date.
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-02'
        description: Filter by end date.
      - name: offset
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          example: '1500'
        description: Record to start with.
      - name: limit
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          example: '5000'
        description: Number of records to return.
      - name: order
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: asc
        description: Sort direction.
      - name: sort
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: GeofenceName
        description: Name of field to sort on. Sort field must be either "name", "groupId", "groupName", "isInside", or "creationDate".
      - name: includeSubGroups
        in: query
        required: false
        schema:
          type: boolean
          example: 'false'
        description: Include Sub Groups.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGeofenceResponse'
        '204':
          description: 'No Content: HTTP request has been successfully completed, and there is no message body'
        '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-permitted 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
  /v1/geofences/{geofenceIdentifier}:
    delete:
      tags:
      - Geofences (DriveCam)
      description: Delete a Geofence
      summary: Delete Specified Geofence by ID
      parameters:
      - name: geofenceIdentifier
        required: true
        in: path
        schema:
          type: string
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
      responses:
        '204':
          description: Successful deletion of Geofence
        '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-permitted 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
    put:
      tags:
      - Geofences (DriveCam)
      description: Update a specific Geofence by Identifier.
      summary: Update Specified Geofence
      parameters:
      - name: geofenceIdentifier
        required: true
        in: path
        schema:
          type: string
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Geofence Id to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddGeofenceRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleGeofenceResponse'
        '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-permitted 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
  /v1/geofence/activations:
    get:
      tags:
      - Geofences (DriveCam)
      description: Get Geofence Activations
      summary: Get Geofence Activations
      parameters:
      - name: activationIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
        description: Unique Id for Geofence Activation.
      - name: geofenceIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
        description: Unique Id for Geofence.
      - name: deviceIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Device Id or Serial Number.
      - name: groupIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Group Identifier.
      - name: vehicleIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by Vehicle Identifier or Vin.
      - name: userIdentifier
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
        description: Filter by User Identifier.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-01'
        description: Filter by start date.
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
          example: '2023-06-02'
        description: Filter by end date.
      - name: offset
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          example: '1500'
        description: Record to start with.
      - name: limit
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          example: '5000'
        description: Number of records to return.
      - name: order
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: asc
        description: Sort direction.
      - name: sort
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
          example: asc
        description: Name of property to sort on (Default Sort on ActivationStartDate only otherwise LastUpdateDateTime).
      - name: includeSubGroups
        in: query
        required: false
        schema:
          type: boolean
          example: 'false'
        description: Include Sub Groups.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ActivationsResponse'
        '204':
          description: 'No Content: HTTP request has been successfully completed, and there is no message body'
        '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-permitted user
        '404':
          description: Resource 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
  /v1/geofence/activations/endreason:
    get:
      tags:
      - Geofences (DriveCam)
      summary: Get Activation End Reasons
      description: Get the end reasons activations
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ActivationEndReasonResponse'
        '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-permitted user
        '404':
          description: Resource 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:
    SingleGeofenceResponse:
      title: Geofence Response
      type: object
      properties:
        geofenceId:
          type: string
          example: 3F136C14-79C8-4BAA-B9DE-ADA9C0C68EBC
          description: Id of the created Geofence
        name:
          type: string
          example: San Diego 92120
          description: Name of the created Geofence.
        rootGroupId:
          type: string
          example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Id of the unique company identifier that the new Geofence was created in.
        groupId:
          type: string
          example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Id of the Sub-Group the new Geofence was created in. Can be the same as Root Group Id.
        groupName:
          type: string
          example: Root Group
          description: Name of the Sub-Group the new Geofence was created in.
        groupPath:
          type: string
          example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB\\2CB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Hierarchy path showing the Group Ids down from the Root Group Id
        includeSubGroups:
          type: boolean
          example: true
          description: Flag for the newly created Geofence that indicates whether or not the Geofence rules apply to all vehicles below the Group the Geofence is created in the hierarchy.
        isInside:
          type: boolean
          example: true
          description: Flag for the newly created Geofence that states whether or not the Geofence is inside facing or outside facing.
        geofenceGeography:
          type: object
          properties:
            radius:
              type: number
              format: double
              example: 25
              description: Radius for the newly created Geofence. Will be a number other than 0 if the Geofence created is a Circle.
            shapeType:
              type: number
              enum:
              - 1
              - 2
              - 3
              example: 3
              description: 1 is for polygon, 2 is for square, 3 is for circle
            points:
              type: array
              items:
                properties:
                  latitude:
                    type: number
                    format: double
                  longitude:
                    type: number
                    format: double
        color:
          type: string
          example: '#800080'
        effectiveDaysOfWeek:
          type: string
          example: 1,3,5
          description: Comma separated list of active days of the week. If empty, the new Geofence is always active. Days of week start with 1 on Monday.
        createdDate:
          type: string
          format: date-time
          example: '2024-06-28T15:31:42.8955131Z'
          description: Created Date Time in UTC of the newly created Geofence.
        assetGroupId:
          type: string
          format: uuid
          example: 2CB2D9B4-C801-E111-81CE-E61F13277AAB
          description: Optional Group Id that the Geofence will monitor for assets/devices.
        assetIncludeSubGroups:
          type: boolean
          example: false
          description: Optional flag to include Sub Groups for Assets/Devices that the new Geofence will apply to.
        assets:
          type: array
          items:
            properties:
              assetId:
                type: string
                example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
              assetType:
                type: string
                enum:
                - vehicle
                - equipment
                example: vehicle
        effectiveStartTime:
          type: string
          example: '15:00:00'
          description: The effective Start time the created Geofence will be active in UTC. Applicable to Geofences created with active time ranges during the day.
        effectiveEndTime:
          type: string
          example: 05:59:00
          description: The effective End time the created Geofence will cease being active in UTC. Applicable to Geofences created with active time ranges during the day.
        effectiveTimezoneOffset:
          type: string
          example: '-7:00'
          description: Timezone offset from UTC
    ActivationsResponse:
      title: Geofence Activations Response
      type: object
      properties:
        metadata:
          type: object
          properties:
            limit:
              type: number
              example: 5000
              description: Maximum amount of records that can be returned.
            count:
              type: number
              example: 5000
              description: Number of Geofence Activation records returned.
            offset:
              type: number
              example: 0
              description: Number of records skipped.
            startDate:
              type: string
              format: date-time
              example: '2024-07-10T12:12:12Z'
            endDate:
              type: string
              format: date-time
              example: '2024-07-11T12:12:12Z'
        data:
          type: array
          items:
            properties:
              vehicleId:
                type: string
                format: uuid
                example: d77548ad-95db-40a8-bbcd-8259e5063f7f
              vehicleName:
                type: string
                example: 2012 Toyota Tundra
              vin:
                type: string
                example: 1B4HR28Y6XF631743
              deviceId:
                type: string
                format: uuid
                example: d77548ad-95db-40a8-bbcd-8259e5063f7f
              serialNumber:
                type: string
                example: QM123456
              groupId:
                type: string
                format: uuid
                example: d77548ad-95db-40a8-bbcd-8259e5063f7f
              activations:
                type: array
                items:
                  properties:
                    activationId:
                      type: string
                      format: uuid
                      example: a2c08cb1-0df9-4452-a8e8-38b2e74f2e8d
                    geofenceName:
                      type: string
                      example: San Diego - UTC
                    geofenceId:
                      type: string
                      format: uuid
                      example: a2c08cb1-0df9-4452-a8e8-38b2e74f2e8d
                    startPosition:
                      type: object
                      properties:
                        latitude:
                          type: number
                          format: double
                          example: 32.123
                        longitude:
                          type: number
                          format: double
                          example: 101.432
                    activationStartDate:
                      type: string
                      format: date-time
                      example: '2024-07-09T16:11:11Z'
                    activationEndDate:
                      type:
                      - string
                      - 'null'
                      format: date-time
                      example: '2024-07-11T20:31:33Z'
                    endPosition:
                      type:
                      - object
                      - 'null'
                      properties:
                        latitude:
                          type: number
                          format: double
                          example: 32.123
                        longitude:
                          type: number
                          format: double
                          example: 101.432
                    userIdentifier:
                      type: string
                      format: uuid
                      example: d77548ad-95db-40a8-bbcd-8259e5063f7f
                    endReason:
                      type: number
                      example: 1
                    lastUpdateDateTime:
                      type: string
                      example: '2024-07-11T20:31:33Z'
    AddGeofenceRequest:
      title: Add Geofence Request
      type: object
      required:
      - name
      - isInside
      - geofenceGeography
      - colorHex
      - inclusive
      - visible
      properties:
        name:
          type:
          - string
          - 'null'
          example: San Diego
          description: Name for Geofence.
        groupIdentifier:
          type:
          - string
          - 'null'
          example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
          description: Optional Group Id to provide that Geofence will be created under.
        includeSubGroups:
          type: boolean
          example: 'false'
          description: Flag for Geofence to include all assets/vehicles in sub groups.
        isInside:
          type: boolean
          example: 'false'
          description: Flag to indicate whether geofence faces inside or outside.
        isActive:
          type: boolean
          example: 'true'
          description: Flag to indicate whether to create the Geofence in the active or inactive state.
        geofenceGeography:
          type: object
          properties:
            radius:
              type: number
              format: double
              example: 5
              description: Required to be other than 0 if shape is a circle
            shapeType:
              type: number
              enum:
              - 1
              - 2
              - 3
              example: 3
              description: 1 is for polygon, 2 is for square, 3 is for circle
            points:
              type: array
              description: Array of points (lat,long). Circle requires 1 point as the centerpoint, Square requires 4 points, Polygon requires 3+ points.
              items:
                properties:
                  latitude:
                    type: number
                    format: double
                  longitude:
                    type: number
                    format: double
        assets:
          type: array
          items:
            properties:
              assetId:
                type: string
                example: 5100FFFF-60B6-D7CD-3FA2-22CA712B0000
              assetType:
                type: string
                enum:
                - vehicle
                - equipment
                example: vehicle
    ListGeofenceResponse:
      title: Geofences Response
      type: object
      properties:
        metadata:
          type: object
          properties:
            limit:
              type: number
              example: 5000
              description: Maximum amount of records that can be returned.
            count:
              type: number
              example: 5000
              description: Number of Geofence Activation records returned.
            offset:
              type: number
              example: 0
              description: Number of records skipped.
            startDate:
              type: string
              format: date-time
              example: '2024-07-10T12:12:12Z'
            endDate:
              type: string
              format: date-time
              example: '2024-07-11T12:12:12Z'
        data:
          type: array
          items:
            properties:
              geofenceId:
                type: string
                example: 3F136C14-79C8-4BAA-B9DE-ADA9C0C68EBC
                description: Id of the created Geofence
              name:
                type: string
                example: San Diego 92120
                description: Name of the created Geofence.
              rootGroupId:
                type: string
                example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB
                description: Id of the unique company identifier that the new Geofence was created in.
              groupId:
                type: string
                example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB
                description: Id of the Sub-Group the new Geofence was created in. Can be the same as Root Group Id.
              groupName:
                type: string
                example: Root Group
                description: Name of the Sub-Group the new Geofence was created in.
              groupPath:
                type: string
                example: 2BB2D9B4-C801-E111-81CE-E61F13277AAB\\2CB2D9B4-C801-E111-81CE-E61F13277AAB
                description: Hierarchy path showing the Group Ids down from the Root Group Id
              includeSubGroups:
                type: boolean
                example: true
                description: Flag for the newly created Geofence that indicates whether or not the Geofence rules apply to all vehicles below the Group the Geofence is created in t

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lytx/refs/heads/main/openapi/lytx-geofences-drivecam-api-openapi.yml