> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🧪 List Driver Insurance Signals

> Retrieve underwriting signals per driver for your accessible fleets over a requested time window. Each row carries safety event counts (speeding, harsh cornering, harsh braking) attributed to the driver and the number of hours-of-service violations recorded against them. All signals are measured over the same window. Distance is not reported at this grain: the odometer is recorded per vehicle, so use the vehicle signals endpoint for distance. The window cannot exceed 90 days.

<Callout icon="vial" color="#FFC107" iconType="solid"><strong>Provisional endpoint</strong><br />This endpoint is available for early access. The core schema is stable, but minor details — such as field names or added fields — may change before it becomes generally available. Backward compatibility is not guaranteed.<br /><br /><em>See <a href="/api-reference/stability-versioning">API Stability & Versioning</a> for details on provisional endpoints.</em></Callout>


## OpenAPI

````yaml https://api.catenatelematics.com/v2/intelligence/openapi.json get /v2/intelligence/insurance/driver-signals
openapi: 3.1.0
info:
  title: Telematics Intelligence Service - REST API
  description: Telematics Intelligence Service REST API.
  version: 0.1.0
servers:
  - url: https://api.catenatelematics.com
    description: Catena Intelligence API
security: []
tags:
  - name: Analytics
    description: >-
      Endpoints providing analytical insights and aggregated data for vehicles,
      fleets, drivers, and trailers.
  - name: Benchmarks
    description: >-
      Endpoints providing cross-fleet benchmark data. A vehicle's metrics are
      ranked against a cohort of peer vehicles drawn from the full Catena fleet
      population. Cohort statistics are k-anonymised: percentile and cohort
      counts are suppressed when the cohort covers too few distinct fleets to
      protect individual fleet privacy.
paths:
  /v2/intelligence/insurance/driver-signals:
    get:
      tags:
        - Insurance Signals
      summary: List driver insurance signals
      description: >-
        Retrieve underwriting signals per driver for your accessible fleets over
        a requested time window. Each row carries safety event counts (speeding,
        harsh cornering, harsh braking) attributed to the driver and the number
        of hours-of-service violations recorded against them. All signals are
        measured over the same window. Distance is not reported at this grain:
        the odometer is recorded per vehicle, so use the vehicle signals
        endpoint for distance. The window cannot exceed 90 days.
      operationId: list_driver_insurance_signals
      parameters:
        - name: fleet_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  format: uuid
                maxItems: 100
              - type: 'null'
            description: >-
              Limit results to specific fleets using Catena's fleet IDs. *For
              your own fleet identifiers, use `fleet_refs` instead* To specify
              multiple values, repeat the parameter for each value (e.g.,
              `?fleet_ids=id1&fleet_ids=id2`).
            title: Fleet Ids
          description: >-
            Limit results to specific fleets using Catena's fleet IDs. *For your
            own fleet identifiers, use `fleet_refs` instead* To specify multiple
            values, repeat the parameter for each value (e.g.,
            `?fleet_ids=id1&fleet_ids=id2`).
        - name: fleet_refs
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 100
              - type: 'null'
            description: >-
              Limit results to specific fleets using your organization's fleet
              reference identifiers. To specify multiple values, repeat the
              parameter for each value (e.g.,
              `?fleet_refs=ref1&fleet_refs=ref2`).
            title: Fleet Refs
          description: >-
            Limit results to specific fleets using your organization's fleet
            reference identifiers. To specify multiple values, repeat the
            parameter for each value (e.g., `?fleet_refs=ref1&fleet_refs=ref2`).
        - name: connection_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            description: >-
              Limit results to a specific provider connection. This is the UUID
              assigned by Catena when your fleet connects to a TSP.
            title: Connection Id
          description: >-
            Limit results to a specific provider connection. This is the UUID
            assigned by Catena when your fleet connects to a TSP.
        - name: driver_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  format: uuid
                maxItems: 100
              - type: 'null'
            description: >-
              Limit results to specific drivers. **Maximum:** 100 IDs To specify
              multiple values, repeat the parameter for each value (e.g.,
              `?driver_ids=id1&driver_ids=id2`).
            title: Driver Ids
          description: >-
            Limit results to specific drivers. **Maximum:** 100 IDs To specify
            multiple values, repeat the parameter for each value (e.g.,
            `?driver_ids=id1&driver_ids=id2`).
        - name: from_datetime
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              Return only records that occurred on or after this date and time.
              **Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at >=
              from_datetime` **Default value:** `now() - 1 day` **Restriction:**
              `to_datetime - from_datetime` cannot exceed 90 days
            examples:
              - '2026-08-07T00:17:24.765188Z'
            title: From Datetime
          description: >-
            Return only records that occurred on or after this date and time.
            **Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at >=
            from_datetime` **Default value:** `now() - 1 day` **Restriction:**
            `to_datetime - from_datetime` cannot exceed 90 days
        - name: to_datetime
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              Return only records that occurred before this date and time.
              **Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at <
              to_datetime` **Default value:** `now()` **Restriction:**
              `to_datetime - from_datetime` cannot exceed 90 days
            examples:
              - '2026-08-08T00:17:24.765238Z'
            title: To Datetime
          description: >-
            Return only records that occurred before this date and time.
            **Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at <
            to_datetime` **Default value:** `now()` **Restriction:**
            `to_datetime - from_datetime` cannot exceed 90 days
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Cursor for the next page
            title: Cursor
          description: Cursor for the next page
        - name: size
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: Page size
            default: 300
            title: Size
          description: Page size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_CursorPage_DriverInsuranceSignalsRead_'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not Found
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: Method Not Allowed
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
          description: Not Implemented
      security:
        - Bearer:
            - telematics:read
components:
  schemas:
    _CursorPage_DriverInsuranceSignalsRead_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/DriverInsuranceSignalsRead'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0
          title: Total
        current_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Page
          description: Cursor to refetch the current page
        current_page_backwards:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Page Backwards
          description: Cursor to refetch the current page starting from the last item
        previous_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Page
          description: Cursor for the previous page
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
          description: Cursor for the next page
      type: object
      required:
        - items
        - total
      title: _CursorPage[DriverInsuranceSignalsRead]
    BadRequest:
      properties:
        code:
          type: integer
          title: Code
          default: 400
        message:
          type: string
          title: Message
          default: Bad Request
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: BadRequest
    Unauthorized:
      properties:
        code:
          type: integer
          title: Code
          default: 401
        message:
          type: string
          title: Message
          default: Unauthorized
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Unauthorized
    Forbidden:
      properties:
        code:
          type: integer
          title: Code
          default: 403
        message:
          type: string
          title: Message
          default: Forbidden
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Forbidden
    NotFound:
      properties:
        code:
          type: integer
          title: Code
          default: 404
        message:
          type: string
          title: Message
          default: Not Found
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: NotFound
    MethodNotAllowed:
      properties:
        code:
          type: integer
          title: Code
          default: 405
        message:
          type: string
          title: Message
          default: Method Not Allowed
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: MethodNotAllowed
    Conflict:
      properties:
        code:
          type: integer
          title: Code
          default: 409
        message:
          type: string
          title: Message
          default: Conflict
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Conflict
    UnprocessableEntity:
      properties:
        code:
          type: integer
          title: Code
          default: 422
        message:
          type: string
          title: Message
          default: Invalid Request Body
        detail:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Detail
      type: object
      title: UnprocessableEntity
    TooManyRequests:
      properties:
        code:
          type: integer
          title: Code
          default: 429
        message:
          type: string
          title: Message
          default: Too Many Requests
        detail:
          anyOf:
            - $ref: '#/components/schemas/RetryAfterDetail'
            - type: 'null'
      type: object
      title: TooManyRequests
    InternalServerError:
      properties:
        message:
          type: string
          title: Message
          default: Internal Server Error
      type: object
      title: InternalServerError
    NotImplementedResponse:
      properties:
        code:
          type: integer
          title: Code
          default: 501
        message:
          type: string
          title: Message
          default: Not Implemented
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: NotImplementedResponse
    DriverInsuranceSignalsRead:
      properties:
        driver:
          $ref: '#/components/schemas/DriverEmbeddedRead'
          description: Identifying details for the driver that this row describes.
        fleet_refs:
          items:
            type: string
          type: array
          title: Fleet Refs
          description: >-
            Your assigned reference IDs for the fleets this driver is visible
            through. Almost always one. Empty when no reference has been
            assigned to any of them. The signals below describe the driver and
            do not vary by fleet.
        fleet_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Fleet Ids
          description: >-
            Catena fleet identifiers for the same fleets. Several identifiers
            can share a single `fleet_refs` entry, so this list is usually the
            longer of the two and the two are not positionally paired. Prefer
            `fleet_refs` for grouping and reporting.
        speeding_event_count:
          type: integer
          title: Speeding Event Count
          description: Number of speeding events attributed to this driver in the window.
        harsh_turn_count:
          type: integer
          title: Harsh Turn Count
          description: >-
            Number of harsh cornering events attributed to this driver in the
            window.
        harsh_brake_count:
          type: integer
          title: Harsh Brake Count
          description: >-
            Number of harsh braking events attributed to this driver in the
            window.
        hos_violation_count:
          type: integer
          title: Hos Violation Count
          description: >-
            Number of hours-of-service violations recorded against this driver
            in the window, counting every violation category. `0` means no
            violation was recorded, which for a driver whose provider does not
            report HOS is indistinguishable from full compliance.
      type: object
      required:
        - driver
        - fleet_refs
        - fleet_ids
        - speeding_event_count
        - harsh_turn_count
        - harsh_brake_count
        - hos_violation_count
      title: DriverInsuranceSignalsRead
      description: Underwriting signals for a single driver over the requested time window.
    ValidationErrorDetail:
      properties:
        path:
          type: string
          title: Path
        input:
          type: string
          title: Input
        message:
          type: string
          title: Message
        error_type:
          type: string
          title: Error Type
      type: object
      required:
        - path
        - input
        - message
        - error_type
      title: ValidationErrorDetail
    RetryAfterDetail:
      properties:
        retry_after_seconds:
          type: integer
          title: Retry After Seconds
        message:
          type: string
          title: Message
      type: object
      required:
        - retry_after_seconds
        - message
      title: RetryAfterDetail
    DriverEmbeddedRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier of the record at Catena Telematics.
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: Driver's given name.
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: Driver's family/surname.
        username:
          anyOf:
            - type: string
            - type: 'null'
          title: Username
          description: Unique username/login for the driver (source or Catena).
        user_designation:
          anyOf:
            - type: string
            - type: 'null'
          title: User Designation
          description: >-
            Role/title or TSP designation (e.g., 'DRIVER', 'DISPATCHER',
            'ADMIN').
        employee_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Employee Number
          description: Employer/HR or payroll identifier for the driver (if applicable).
        is_driver:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Driver
          description: Indicates whether the user is a driver (vs. back-office/admin).
        is_active:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Active
          description: Indicates whether the driver is currently active.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: User/account status label (e.g., 'ACTIVE', 'INACTIVE', 'SUSPENDED').
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
          description: Unique identifier of the record in the TSP.
      type: object
      required:
        - id
      title: DriverEmbeddedRead
      description: >-
        Lightweight driver snapshot embedded in other API responses.


        Deliberately excludes personal contact and licence details
        (`user_email`, `phone_number`,

        `license_number`, `license_*`) available on the underlying user record.
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
        authorizationCode:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          authorizationUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/auth
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token

````