public-api-docs

Operations API Events And User Analytics Guide

Overview

Operations event endpoints let operator tools inspect platform events for support, troubleshooting, and analytics. They include app-posted user events from the User API, backend-generated rental and booking events, vehicle events, payment and verification events, and event-position analytics.

Use this guide when building support consoles, branch analytics views, event timelines, or map-based views such as “where users opened the app” or “where rentals were started”.

Related reference: Operations API Operations API Guide User API Events Guide Pagination

Core Concepts

Event Sources

Events can be created by different parts of the platform:

Source Examples Notes
User app APP_START, APP_MAP_NAVIGATION, APP_VEHICLE_SELECTION, Bluetooth app events Posted by POST /userevents in the User API.
Backend domain flows Rental start/end, booking creation, package purchase, invoice retry, verification, payment method changes Created by Core when the action happens.
Vehicle and IoT flows Vehicle command events, offline/online, battery, service state, Bluetooth/RFID interactions Created by backend or device integration workflows.
Operator tools Admin-triggered actions, bulk updates, card management, vehicle/task changes Linked to the admin user where available.

Stored Event Fields

Event responses can include:

Field Meaning
type Event type, such as APP_START, RENTAL_START, or VEHICLE_OFFLINE.
createdAt / time Event creation time.
position User/device position, usually extracted from the User API Device-Position header.
vehiclePosition Vehicle position captured with vehicle/rental-related events.
guser End user linked to the event.
adminGuser Operator/admin user linked to the event, where applicable.
rentalId, bookingId, balanceId, vehicle Linked business objects.
requestInfo Optional app-provided or request-provided JSON context.
error / errorMessage Error code and message for failed operations.
description Human-readable event description where available.

GPS data can be permission-filtered. If an operator does not have position-log permissions for the relevant branch, vehicle/rental position details can be hidden.

Common Operator Workflows

List Event Types

Use GET /events/types to retrieve event types available to the current operator user.

This is useful for building event-type filters rather than hard-coding a stale list. The current Core event catalog is also summarized in the User API Events Guide.

Search Events

Use GET /events for a general event search. The endpoint supports pagination and QueryDSL-style filters from the Event model.

Common filters include:

Filter goal Example
Filter by type GET /events?type=APP_START
Filter by user GET /events?guser.id={userId}
Filter by rental GET /events?rental.id={rentalId}
Filter by booking GET /events?booking.id={bookingId}
Filter by vehicle GET /events?vehicle.id={vehicleId}
Filter by branch GET /events?branch.id={branchId}
Sort newest first GET /events?sort=id,desc

Read pagination headers such as X-Total-Count, X-Total-Pages, X-Page-Number, and X-Page-Size where returned.

Inspect Events For One Entity

Use GET /{entityType}/{entityId}/events.

Supported entityType values are:

Entity type Use it for
CUSTOMERS Timeline for one customer/user.
RENTALS Timeline for one rental.
BOOKINGS Timeline for one booking.
VEHICLES Timeline for one vehicle.

Set includeRelatedEvents=true when a rental or booking timeline should include related vehicle events during the trip.

Examples:

GET /CUSTOMERS/123/events?type=APP_VEHICLE_SELECTION&sort=id,desc
GET /RENTALS/987/events?includeRelatedEvents=true
GET /VEHICLES/456/events?sort=createdAt,desc

Retrieve User-Event Positions

Use GET /analytics/userEvents?branchId={branchId} for map-style analytics of user event positions. The branchId parameter is used for the operator permission check; include event filters such as branch.id={branchId}, type=APP_START, or a time range when the visualization should be scoped to a specific branch, event type, or period.

The response contains TimePosition objects:

Field Meaning
time Timestamp for the event position.
pos Stored event position geometry.
weight Weight for aggregation/visualization.

This endpoint is useful for heatmaps such as where users open the app or interact with the map. It returns only events with a stored position, so it depends on apps sending the Device-Position header and/or app events with current location.

Use GET /analytics/rentals/startPositions?branchId={branchId} for rental-start positions. That endpoint is focused on actual rentals, while GET /analytics/userEvents is focused on app/user-event positions.

Connect User API Events To Operations Views

For best analytics quality:

  1. In the user app, send Device-Position: {latitude};{longitude} on User API calls where location permission is available.
  2. Post app interactions with POST /userevents?type=APP_*.
  3. In operator tools, inspect detailed records with GET /events or GET /CUSTOMERS/{userId}/events.
  4. For branch heatmaps, use GET /analytics/userEvents?branchId={branchId}.

Do not use Operations event polling as a bulk export pipeline. For recurring historical analytics or warehouse ingestion, use Data Exports or the configured warehouse option.

Permissions

Event access is permission-gated:

Endpoint Permission model
GET /events Requires event-read permission on at least one branch.
GET /events/types Requires one of the event-related permissions.
GET /CUSTOMERS/{id}/events Requires user-event permission.
GET /RENTALS/{id}/events Requires rental-event permission on the rental branch.
GET /BOOKINGS/{id}/events Requires booking-event permission on the booking branch.
GET /VEHICLES/{id}/events Requires vehicle-event permission on the vehicle branch.
GET /analytics/userEvents Requires analytics read permission on the branch.

Position details can require additional rental-position-log permission depending on tenant privacy configuration.

Most Relevant APIs

Area Endpoints
Event search GET /events
Event type catalog GET /events/types
Entity event timeline GET /{entityType}/{entityId}/events
User-event positions GET /analytics/userEvents
Rental start positions GET /analytics/rentals/startPositions
App event creation POST /userevents in the User API

Implementation Notes