> ## 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 Group Messages > List all group messages. Provisional endpoint
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.

See API Stability & Versioning for details on provisional endpoints. ## OpenAPI ````yaml https://api.catenatelematics.com/v2/telematics/openapi.json get /v2/telematics/group-messages openapi: 3.1.0 info: title: Telematics Data Service - REST API description: Telematics Data Service REST API. version: 0.1.0 servers: - url: https://api.catenatelematics.com description: Catena Telematics API security: [] tags: - name: Fleet Operations & Tracking description: >- Endpoints for tracking vehicles, trailers, assets, and trip activity โ€” including locations, movements, and operational telemetry. Useful for monitoring utilization and real-time operational status. - name: Safety & Driver Behavior description: >- Endpoints that provide safety-related insights such as harsh braking, speeding, and other driver behavior events. Supports risk analysis and safety program automation. - name: Compliance & Regulation description: >- Endpoints covering regulated requirements including DVIR inspections, Hours of Service (HOS), violations, and IFTA fuel tax reporting. Helps organizations meet DOT/FMCSA and interstate regulatory obligations. - name: Maintenance & Vehicle Health description: >- Endpoints providing data for vehicle condition monitoring and maintenance workflows, such as DVIR defects and diagnostic sensor events. Enables early issue detection and reduced downtime. - name: Drivers & Users description: >- Endpoints related to driver and user identities, assignments, and operational context. Supports linking operational and safety data to specific individuals. - name: Reference Data (Supporting Tables) description: >- Lookup tables and enumerations that supply standardized codes, metadata, and classifications used across the API. - name: Analytics (deprecated) description: >- Endpoints providing analytical insights and aggregated data for vehicles, fleets, drivers, and trailers. paths: /v2/telematics/group-messages: get: tags: - Drivers & Users summary: List Group Messages description: List all group messages. operationId: list_group_messages 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: 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 45 days examples: - '2026-06-25T15:05:51.529365Z' 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 45 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 45 days examples: - '2026-06-26T15:05:51.529502Z' 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 45 days - name: include_source_data in: query required: false schema: type: boolean description: >- Include the raw data from the telematics provider. *Useful for auditing or accessing fields not normalized by Catena* default: false title: Include Source Data description: >- Include the raw data from the telematics provider. *Useful for auditing or accessing fields not normalized by Catena* - name: sender_ids in: query required: false schema: anyOf: - type: array items: type: string format: uuid maxItems: 100 - type: 'null' description: >- Limit results to specific senders. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?sender_ids=id1&sender_ids=id2`). title: Sender Ids description: >- Limit results to specific senders. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?sender_ids=id1&sender_ids=id2`). - name: group_ids in: query required: false schema: anyOf: - type: array items: type: string format: uuid maxItems: 100 - type: 'null' description: >- Limit results to specific group IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?group_ids=id1&group_ids=id2`). title: Group Ids description: >- Limit results to specific group IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?group_ids=id1&group_ids=id2`). - name: source_sender_ids in: query required: false schema: anyOf: - type: array items: type: string maxItems: 100 - type: 'null' description: >- Limit results to specific source sender IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?source_sender_ids=id1&source_sender_ids=id2`). title: Source Sender Ids description: >- Limit results to specific source sender IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?source_sender_ids=id1&source_sender_ids=id2`). - name: source_group_ids in: query required: false schema: anyOf: - type: array items: type: string maxItems: 100 - type: 'null' description: >- Limit results to specific source group IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?source_group_ids=id1&source_group_ids=id2`). title: Source Group Ids description: >- Limit results to specific source group IDs. **Maximum:** 100 IDs To specify multiple values, repeat the parameter for each value (e.g., `?source_group_ids=id1&source_group_ids=id2`). - name: sort_by in: query required: false schema: anyOf: - type: string - type: 'null' description: >- The name of the field to sort results by. If not provided, results will be ordered by `occurred_at`. title: Sort By description: >- The name of the field to sort results by. If not provided, results will be ordered by `occurred_at`. - name: sort_order in: query required: false schema: enum: - asc - desc type: string description: >- The order of sorting, either `asc` for ascending or `desc` for descending. Defaults to `asc` if `sort_by` is provided without `sort_order`. default: asc title: Sort Order description: >- The order of sorting, either `asc` for ascending or `desc` for descending. Defaults to `asc` if `sort_by` is provided without `sort_order`. - 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_GroupMessageRead_' '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_GroupMessageRead_: properties: items: items: $ref: '#/components/schemas/GroupMessageRead' 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[GroupMessageRead] 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 GroupMessageRead: properties: fleet_id: anyOf: - type: string format: uuid - type: 'null' title: Fleet Id description: Internal fleet identifier. fleet_ref: anyOf: - type: string - type: 'null' title: Fleet Ref description: External fleet reference in the partner system. id: type: string format: uuid title: Id description: Unique identifier of the record at Catena Telematics. created_at: type: string format: date-time title: Created At description: >- Immutable: The datetime the record was ingested into Catena Telematics. updated_at: type: string format: date-time title: Updated At description: The dateime the record was last modified in Catena Telematics. deleted_at: anyOf: - type: string format: date-time - type: 'null' title: Deleted At description: >- The datetime the record was logically deleted from Catena Telematics. connection_id: type: string format: uuid title: Connection Id description: >- Unique identifier of the connection at Catena Telematics through which this record was ingested. A connection represents a Fleet/TSP pairing. tsp_id: anyOf: - type: string format: uuid - type: 'null' title: Tsp Id description: >- Unique identifier of the TSP at Catena Telematics from which this record was ingested. tsp_slug: anyOf: - type: string - type: 'null' title: Tsp Slug description: >- Human readable slug of the TSP at Catena Telematics from which this record was ingested. source_name: $ref: '#/components/schemas/TspEnum' description: >- The underlying telematics platform that provided this data (e.g., `samsara`, `motive`, `hos247`). Note: Some platforms like `hos247` offer white-labeling, so multiple TSPs may share the same source_name โ€” use `tsp_id` or `tsp_slug` to identify the specific ELD provider. source_data: additionalProperties: true type: object title: Source Data description: >- Raw source payload as ingested from the TSP. **Note: use it for audit/debugging.** source_id: type: string title: Source Id description: >- Unique identifier of the record in the TSP. **Note: we generate a unique composite key based on available fields if the TSP does not provide an unique ID.** source_data_hash: type: string maxLength: 64 title: Source Data Hash description: >- SHA-256 hash of the source data payload. **Note: we use it internally for idempotence and deduplication.** occurred_at: anyOf: - type: string format: date-time - type: 'null' title: Occurred At description: >- Datetime of when the underlying event/observation occurred, as reported by the TSP, or the moment it was ingested by us if not available in the source data. execution_id: anyOf: - type: string format: uuid - type: 'null' title: Execution Id description: >- Unique identifier for the execution that ingested this record into Catena Telematics. **Note: useful for tracing.** schedule_id: anyOf: - type: string format: uuid - type: 'null' title: Schedule Id description: >- Unique identifier for schedule that triggered this record's execution. **Note: useful for tracing.** extras: anyOf: - additionalProperties: true type: object - type: 'null' title: Extras description: >- Additional data available in the TSP (e.g., we may have `external_id`, `provider_resource_id`, etc. โ€” this field captures all those extra attributes in a flexible way). source_sender_id: anyOf: - type: string - type: 'null' title: Source Sender Id description: External system identifier for the sender source_recipient_ids: anyOf: - items: type: string type: array - type: 'null' title: Source Recipient Ids description: External system identifier for the recipient sender_id: anyOf: - type: string format: uuid - type: 'null' title: Sender Id description: Unique identifier for the sender recipient_ids: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Recipient Ids description: Unique identifier for the recipient message_text: anyOf: - type: string - type: 'null' title: Message Text description: The content of the message message_hash: anyOf: - type: string - type: 'null' title: Message Hash description: Unique hash generated from sender, message text and occurred_at status: anyOf: - $ref: '#/components/schemas/MessageStatusEnum' - type: 'null' description: Status of the message delivery (e.g. delivered, read) delivered_at: anyOf: - type: string format: date-time - type: 'null' title: Delivered At description: Timestamp indicating when the message was delivered sent_by_driver: anyOf: - type: boolean - type: 'null' title: Sent By Driver description: Whether the message was sent by a driver sender_name: anyOf: - type: string - type: 'null' title: Sender Name description: The name of the sender at the moment when the message was created thread_id: anyOf: - type: string format: uuid - type: 'null' title: Thread Id description: >- Thread/conversation identifier. Represents a shared conversation across multiple messages. source_thread_id: anyOf: - type: string - type: 'null' title: Source Thread Id description: >- External system thread/conversation identifier. Represents a shared conversation across multiple messages. group_id: anyOf: - type: string format: uuid - type: 'null' title: Group Id description: >- Identifier for the message group. Messages with the same group_id are considered part of the same group message. source_group_id: anyOf: - type: string - type: 'null' title: Source Group Id description: >- External system identifier for the message group. Messages with the same source_group_id are considered part of the same group message. type: object required: - fleet_id - id - created_at - updated_at - connection_id - source_name - source_id - source_data_hash title: GroupMessageRead description: Group Message model for API responses 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 TspEnum: type: string enum: - ada - ai_eld - air_eld - alfa_eld - alpha_eld - als - anytrek_pro - anytrek_classic - apex_eld - apollo - apollocloud - ascend - att - awaregps - azuga - bigroad - bluehorse_eld - blueinktech - bouncie - budgetgps - catena_simulator - captain_eld - carrier_lynx - club_eld - counting_trucks_eld - cyntrx - digital_eld - dragon_eld - drive_hos - drive_hos_v2 - driver_tech - dsg_elogs - dynamic_eld - eighteighteight_eld - eld_88 - eld_books - eld_mandate - eld_mandate_prime - eroad - eva_eld - evo_eld - expressway_eld - extreme_eld - ezlogz - ez_lynk - factor_eld - firstgate - fleetcomplete - fleetcompletehub - fleethunt - fleetpulse - fleetsharp - fleetup - fm - forwardthinking - forza_eld - geotab - gpsinsight - gpstab - gpstrackit - grand_eld - greenlight - groundhog - hcss - hos247 - hutch - intellishift - ironman_eld - isaac - jjkeller - kinexaiot - knight_eld - konexial - lioneight - linxup - loop_eld - lucid_eld - luna_eld - lytx - lytxv3 - mapon - matrack - maven - mdm_eld - mobilefleet - moonlight_eld - motion_eld - motive - my_drivebook - my_logs_eld - nero - netradyne - new_eld_world - nextgen_eld - nextraq - omnitracs - onestep - ontime_eld - optima - orbcomm - orient_eld - panda_eld - payd - peak_eld - peoplenet - phillips_connect - phoenix - pop_eld - prologs - proride_eld - qualitylogs_eld - randmcnally - rastrac - raven - redfox - regulog_eld - ridehub - roadeazy - rock_eld - rollingtrans - routemate - royal_eld - safelane - samsara - selectivedrive - simba_eld - skybitz - smart_elds - sparkle_eld - spireon - sun_eld - surfsight - swift - switchboard - synergy_eld - teletracnavman - teletracnavman_director - telogis - tenna - thermo_king - think - tive - topcompliance_eld - traccar - trackease_eld - trackpro - traclog - transflo - trimble - truckford - truckspy - truckx - trueroad_eld - tt - txt_eld - us_fast_eld - verizon_connect - vista_eld - vistracks - vlog_eld - vulcansols_eld - wialon - webfleet - xplore_eld - zigzag_eld - zms_eld - zonar - zubie title: TspEnum description: Enum for TSPs MessageStatusEnum: type: string enum: - read - sent - delivered - pending title: MessageStatusEnum description: Enum for message statuses 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 ````