public-api-docs

User API Events Guide

Overview

User events let an operator-built white-label app send lightweight app interaction telemetry to the platform. Use them to understand app usage, map opens, app activation, vehicle selection, Bluetooth actions, and similar client-side behavior that the backend cannot infer from normal rental, booking, or payment endpoints.

Related reference: User API User API Guide Operations API Events Guide Fair-Use Policy

Core Concepts

Device Position Header

Send the user’s current app/device position on User API requests whenever the app has permission and a reasonably fresh location:

Device-Position: 52.520008;13.404954

The format is WGS84 decimal latitude first, longitude second. Core accepts either ; or a space as the separator. When present and valid, this position is stored on events as the user/device position. This is useful for later analytics such as where users open the app, where they browse the map, and where app actions happen.

Do not send a stale or guessed location. If the user has not granted location permission, omit the header and continue the API call. The backend ignores invalid or missing values.

User-Posted vs Backend-Generated Events

POST /userevents is for app-posted APP_ events. The backend already creates operational events for rentals, bookings, payments, vehicles, verification, packages, invoices, and other domain actions. Do not manually post those operational events from the app.

The User API currently accepts only event types whose names start with APP_. Deprecated legacy values such as LOGIN, SIGNUP, LOGOUT, and START, and non-app events such as RENTAL_START or USER_PAYMENT_METHOD_ADD, should not be posted by the app.

Event Payload

The request body is optional JSON and is stored as event request information. Keep it small and product-focused.

Use it for non-sensitive UI context, for example:

{
  "screen": "vehicle_detail",
  "vehicleId": 12345,
  "source": "map_marker"
}

Do not send payment details, tokens, passwords, precise personal documents, or large payloads.

Common User Workflows

Post An App Event

Call POST /userevents?type={eventType}. A successful request returns 204 No Content.

POST /userevents?type=APP_VEHICLE_SELECTION
Authorization: Bearer <access-token>
Device-Position: 52.520008;13.404954
Content-Type: application/json

{
  "vehicleId": 12345,
  "source": "map_marker"
}

The event is linked to the current signed-in user when the app sends a valid access token. The endpoint can also tolerate anonymous app events, but signed-in events are more useful for support and analytics.

User action Event type Suggested payload
App launches or main app shell is ready APP_START screen, appBuild, sessionId
User signs in successfully APP_LOGIN method such as email, phone, social
User completes sign-up in the app APP_SIGNUP method, branchId
User logs out APP_LOGOUT screen
App is backgrounded or closed APP_CLOSE or APP_INACTIVATE screen, sessionDurationSeconds
App returns to foreground APP_ACTIVATE screen
User moves or refreshes the map APP_MAP_NAVIGATION branchId, zoom, radius, categoryIds
User selects a vehicle APP_VEHICLE_SELECTION vehicleId, vehicleCode, source
User performs a Bluetooth action APP_BT_ACTION vehicleId, action
Bluetooth action fails APP_BT_ACTION_FAIL vehicleId, action, reason
Bluetooth lock succeeds APP_BT_LOCK vehicleId, rentalId
Bluetooth unlock succeeds APP_BT_UNLOCK vehicleId, rentalId

Use one event per meaningful interaction, not for every render, animation frame, location update, or polling response.

Position Tracking Pattern

For location-aware app analytics, use both request parameters and the Device-Position header:

  1. On app start, send APP_START with Device-Position if location permission is already available.
  2. On map viewport changes, call discovery endpoints with viewport-derived lat, lng, and rad, and include Device-Position with the user’s actual position if known.
  3. When the user selects a vehicle, post APP_VEHICLE_SELECTION with Device-Position and vehicleId.
  4. During rental or booking actions, keep sending Device-Position on normal API calls so backend-created operational events can also capture user position.

The map center and the user’s physical position are not always the same. Use discovery parameters for the viewport/search area and Device-Position for the user’s device location.

Event Catalog

App-Posted Events

These are the event types the app should post with POST /userevents:

Event type Use it for
APP_LOGIN User signed in successfully in the app.
APP_SIGNUP User completed sign-up in the app.
APP_LOGOUT User logged out.
APP_CLOSE App/session closed.
APP_MAP_NAVIGATION User moved, zoomed, or refreshed the map.
APP_VEHICLE_SELECTION User selected a vehicle from map, list, scan, radar, or deeplink.
APP_START App started or main app shell became active.
APP_INACTIVATE App moved to background/inactive state.
APP_ACTIVATE App returned to active foreground state.
APP_BT_ACTION Bluetooth action was attempted or completed.
APP_BT_ACTION_FAIL Bluetooth action failed.
APP_BT_LOCK Bluetooth lock action succeeded.
APP_BT_UNLOCK Bluetooth unlock action succeeded.

Backend-Generated Event Families

The platform also creates operational events. These are useful in Operations API event views and analytics, but apps should not post them manually.

Family Event types
Rental RENTAL_RESERVATION, RENTAL_START, RENTAL_START_RFID, RENTAL_START_BLUETOOTH, RENTAL_END, RENTAL_END_RFID, RENTAL_END_RFID_IGNORED, RENTAL_END_BLUETOOTH, RENTAL_END_DOCKED, RENTAL_END_INACTIVE, RENTAL_END_USER_BALANCE_DEPLETED, RENTAL_FEEDBACK, RENTAL_DRIVE, RENTAL_DRIVE_BLUETOOTH, RENTAL_PARK, RENTAL_PARK_BLUETOOTH, RENTAL_PARK_INACTIVE, RENTAL_RENEW_RESERVATION, RENTAL_CANCEL_RESERVATION, RENTAL_OPEN_TAILBOX, RENTAL_LIST, RENTAL_DETAILS, RENTAL_BUY_RESERVATION, RENTAL_PRE_END_ACTIONS, RENTAL_OPERATION_FAILED, RENTAL_UPDATE, RENTAL_DEPOSIT_RELEASE, RENTAL_REQUIREMENTS_START_CHECK, RENTAL_REQUIREMENTS_END_CHECK, RENTAL_END_CHECK, RENTAL_FILES_LINKED
Booking BOOKING_CREATED, BOOKING_UPDATED, BOOKING_CANCELED, BOOKING_CANCELED_PAYMENT_FAILURE, BOOKING_SUCCESSFUL, BOOKING_DETAILS, BOOKING_LIST, BOOKING_PICKUP, BOOKING_PICKUP_RFID, BOOKING_PICKUP_BLUETOOTH, BOOKING_TIMESLOT, BOOKING_DELIVERED, BOOKING_CHECKED_IN, BOOKING_APPROVAL, BOOKING_CATEGORY_CHANGED, BOOKING_AVAILABLE_CATEGORIES, BOOKING_AVAILABILITY, BOOKING_STATION_AVAILABILITY, BOOKING_ESTIMATE_EXTENSION, BOOKING_BOOKABLE_CATEGORIES, GROUP_BOOKING_LIST, GROUP_BOOKING_CREATED
Vehicle and commands VEHICLE_LOCATE, VEHICLE_COMMAND_START, VEHICLE_COMMAND_STOP, VEHICLE_COMMAND_LOCK, VEHICLE_COMMAND_UNLOCK, VEHICLE_COMMAND_LOCATE, VEHICLE_COMMAND_OPEN_SADDLE, VEHICLE_COMMAND_OPEN_TAILBOX, VEHICLE_COMMAND_LOCK_TAILBOX, VEHICLE_COMMAND_UNLOCK_TAILBOX, VEHICLE_COMMAND_ALARM_ON, VEHICLE_COMMAND_ALARM_OFF, VEHICLE_COMMAND_SET_MAX_SPEED, VEHICLE_COMMAND_CUSTOM_COMMAND, VEHICLE_COMMAND_UNLOCK_BIKE_LOCK, VEHICLE_COMMAND_UNLOCK_STATION_PORT, VEHICLE_COMMAND_UNKNOWN, VEHICLE_UPDATE, VEHICLE_BRANCH_CHANGED
Vehicle state and faults VEHICLE_SERVICE_STATE_OPERATIONAL, VEHICLE_SERVICE_STATE_OUT_OF_ORDER, VEHICLE_TAGS_UPDATE, VEHICLE_SERVICE_STATE_RETIRED, VEHICLE_COMMAND_REBOOT, VEHICLE_SERVICE_STATE_LOW_SOC, VEHICLE_SERVICE_STATE_UNKNOWN, VEHICLE_FAULT_STATE_FAULT, VEHICLE_FAULT_STATE_ILLEGAL_MOVEMENT, VEHICLE_FAULT_STATE_FALLEN_OVER, VEHICLE_FAULT_STATE_MODULE_REMOVED, VEHICLE_FAULT_STATE_LIFTED_UP, VEHICLE_FAULT_STATE_UNKNOWN, VEHICLE_MAINTENANCE, VEHICLE_OFFLINE, VEHICLE_ONLINE, VEHICLE_OUT_OF_RENTAL_ACTIVITY, VEHICLE_LOST_SCANNED_BY_USER, VEHICLE_IOT_NOT_POWERED, VEHICLE_IOT_POWERED, VEHICLE_BULK_UPDATE, VEHICLE_TASK_BULK_CREATE, VEHICLE_NOTE_BULK_CREATE, VEHICLE_TAGS_BULK_UPDATE
Bluetooth, RFID, and charging VEHICLE_RFID_READER_NO_ACTION, VEHICLE_BLUETOOTH_UNRECOGNIZED_INTERACTION, VEHICLE_BLUETOOTH_INVALID_TOKEN_USAGE, VEHICLE_BLUETOOTH_UNAUTHORIZED_TOKEN_USAGE, VEHICLE_BLUETOOTH_ACTION_UNLOCK, VEHICLE_BLUETOOTH_ACTION_LOCK, VEHICLE_BLUETOOTH_ACTION_UNKNOWN, VEHICLE_BLUETOOTH_NO_ACTION_POSSIBLE, VEHICLE_CHARGING_STARTED, VEHICLE_CHARGING_ENDED, VEHICLE_CHARGING_RESTRICTION_IGNORED
Vehicle service state V2 VEHICLE_SERVICE_STATE_V2_FUNCTIONAL, VEHICLE_SERVICE_STATE_V2_INSPECT, VEHICLE_SERVICE_STATE_V2_RELOCATE, VEHICLE_SERVICE_STATE_V2_COLLECT, VEHICLE_SERVICE_STATE_V2_SERVICE_ON_SITE, VEHICLE_SERVICE_STATE_V2_SERVICE_WORKSHOP, VEHICLE_SERVICE_STATE_V2_SERVICE_EXTERNAL, VEHICLE_SERVICE_STATE_V2_REPLACE, VEHICLE_SERVICE_STATE_V2_IMPOUNDED, VEHICLE_SERVICE_STATE_V2_LOST, VEHICLE_SERVICE_STATE_V2_RETIRED, VEHICLE_SERVICE_STATE_V2_READY_FOR_DEPLOYMENT, VEHICLE_SERVICE_STATE_V2_MAINTENANCE, VEHICLE_SERVICE_STATE_V2_OTHER, VEHICLE_SERVICE_STATE_V2_WAITING_FOR_PARTS, VEHICLE_SERVICE_STATE_V2_UNREPAIRABLE, VEHICLE_SERVICE_STATE_V2_DEFLEETED, VEHICLE_SERVICE_STATE_V2_OPERATIONAL_HOLD, VEHICLE_SERVICE_STATE_V2_AWAITING_ACTION, VEHICLE_SERVICE_STATE_V2_SERVICE_MECHANICS, VEHICLE_SERVICE_STATE_V2_REGULATORY_INSPECTION_READY, VEHICLE_SERVICE_STATE_V2_REGULATORY_INSPECTION, VEHICLE_SERVICE_STATE_V2_SERVICE_WORKSHOP_INSURANCE, VEHICLE_SERVICE_STATE_V2_SERVICE_WORKSHOP_QUEUE, VEHICLE_SERVICE_STATE_V2_READY_FOR_DEPLOYMENT_NEW, VEHICLE_SERVICE_STATE_V2_COLLECT_EXTERNAL
Battery VEHICLE_BATTERY_LEVEL_UNKNOWN, VEHICLE_BATTERY_LEVEL_CRITICAL, VEHICLE_BATTERY_LEVEL_LOW, VEHICLE_BATTERY_LEVEL_MEDIUM, VEHICLE_BATTERY_LEVEL_HIGH
User and verification USER_PASSWORD_RESET_EMAIL, USER_PASSWORD_CHANGED, USER_EMAIL_VERIFIED, USER_EMAIL_CHANGED, USER_LICENCE_VERIFICATION, USER_ID_DOCUMENT_VERIFICATION, USER_MANUAL_VERIFICATION, USER_CUSTOM_EXTERNAL_VERIFICATION, USER_PROFILE_DATA_CHANGED, USER_PAYMENT_METHOD_ADD, USER_PAYMENT_METHOD_CHANGED, USER_PAYMENT_METHOD_REMOVED, USER_PHONE_REGISTRATION_DENIED, USER_PHONE_REGISTRATION_DENIED_SILENT, USER_PHONE_REGISTRATION_NO_SMS_SENT, USER_TERMS_AND_CONDITIONS_ACCEPTED
Payment and commercial products BALANCE_SETTLEMENT_FAILED, BALANCE_SETTLEMENT_SUCCESSFUL, INVOICE_RETRY_PAYMENT, PACKAGE_BUY, PACKAGE_BUY_PUSH, RIDE_PASS_RENEW
Cards, driving log, stations, and parking GENERATE_BLUETOOTH_TOKEN, GENERATE_BLUETOOTH_TOKENS, CUSTOMER_IDENTITY_CARD_CREATE, CUSTOMER_IDENTITY_CARD_CREATE_BULK, CUSTOMER_IDENTITY_CARD_UPDATE, CUSTOMER_IDENTITY_CARD_ASSIGN, CUSTOMER_IDENTITY_CARD_UNASSIGN, VEHICLE_CARD_CREATE, VEHICLE_CARD_CREATE_BULK, VEHICLE_CARD_UPDATE, VEHICLE_CARD_ASSIGN, VEHICLE_CARD_UNASSIGN, DRIVING_LOG_SUBMIT, DRIVING_LOG_ENTRY_CREATE, DRIVING_LOG_ENTRY_UPDATE, DRIVING_LOG_ENTRY_DELETE, PHYSICAL_STATION_SLOT_VEHICLE_CONNECTED, PHYSICAL_STATION_SLOT_VEHICLE_DISCONNECTED, PHYSICAL_STATION_SLOT_VEHICLE_ORPHANED, VEHICLE_CONNECTED_TO_UNKNOWN_SLOT, PARKING_RESERVATION_CREATED, PARKING_RESERVATION_REMOVED, PARKING_RESERVATION_CHANGED
Maintenance and notifications NOTIFICATION, VEHICLE_MAINTENANCE_APPROACH, VEHICLE_MAINTENANCE_DEPLOY, VEHICLE_MAINTENANCE_CLOSE

Most Relevant APIs

Area Endpoints
Post app event POST /userevents
Retrieve event details and positions Operations API Events Guide

Implementation Notes