Event syntax

Events are any of a number of risky and distracted driving incidents that can occur during a trip.

Events are referred to differently in different Surfsight platforms, as outlined in the following table:

Event name API syntax Webhook syntax Event description
Acceleration acceleration acceleration The driver increases speed suddenly.
Possible accident accident accident The g-force of the vehicle is very high, indicating a possible collision.
Button pressed button button The driver manually triggers an event when he spots an unusual incident worth alerting about. To manually trigger an event, the driver presses the event trigger button on the device.
Cell phone use cellPhoneUse cellPhoneUse The driver is using their cell phone.
Cell phone use alert cellPhoneUseBeep cell_phone_use_beep The driver gets an audio and visual alert that they might be using their cell phone. After a few alerts with no change from the driver, a cellPhoneUse event is created.
De-acceleration deceleration de_acceleration The driver reduces speed significantly.
Device activation deviceActivation deviceActivation A device is activated in the system.
Distracted driving distractedDriving distracted_driving The driver is generally distracted from the road.
Distracted driving alert distractedDriverBeep distracted_driver_beep The driver gets an audio and visual alert that they might be driving inattentively. After a few alerts with no change, a distractedDriving event is created.
Driver check-in driverCheckIn drivercheckin The driver is checked in by the device, through a QR code or entering a 5 digit driver PIN code.
Driver check-out driverCheckOut drivercheckout The driver is checked out through the device UI and removed from the device.
Driver unbelted driverUnbelted driverUnbelted The driver does not have their seat belt fastened.
Driver unbelted alert driverUnbeltedBeep driver_unbelted_beep The driver gets an audio and visual alert that they might have their seat belt unbelted. After a few alerts with no change from the driver, a driverUnbelted event is created.
Entering standby standbyEnter standby_enter The device enters standby mode. GPS information is included in this event. The device must be connected to constant power for this event to be triggered.
Exiting standby standbyExit standby_exit The device exits standby mode. GPS information is included in this event. The device must be connected to constant power for this event to be triggered.
Fence geoFence GeoFence The driver enters or exits a geofence.
Food and drink foodDrink foodDrink The driver is eating or drinking.
Food and drink alert foodDrinkBeep food_drink_beep The driver gets an audio and visual alert that they might be eating or drinking. After a few alerts with no change from the driver, a foodDrink event is created.
GSensor high gsensorHigh gsensor_high The g-force of the vehicle is higher than it should be, and is even higher than the level that triggers a g-sensor regular event.
GSensor regular gsensorRegular gsensor_regular The g-force of the vehicle is higher than it should be.
Lane weaving laneWeaving lane_weaving The vehicle crosses over a certain number of lanes in a specific amount of time.
No check-in noCheckIn nocheckin The driver did not check-in through the device when prompted.
Obstruction obstruction obstruction The in-cab lens is fully covered for more than forty seconds.
Passenger unbelted passengerUnbelted passenger_unbelted The passenger does not have their seat belt fastened.
Possible fatigue possibleFatigue possibleFatigue A distracted driving event occurs and the driver has already been driving for more than the number of daily driving hours configured with the drivingDuration parameter.
Power disconnect powerDisconnectAlarm power_disconnect_alarm The power cable is removed from the device.
Power off accOff acc_off The device is shut down.
Power on accOn acc_on The device is turned on or woken up from standby mode to active mode.
QR code qrCode qr_code The in-cab lens scans a QR code.
SD card formatted sdCardFormatted sd_card_formatted The SD card is formatted or reformatted, and a new UUID is assigned.
Smoking smoking smoking The driver is smoking.
Smoking alert smokingBeep smoking_beep The driver gets an audio and visual alert that they might be smoking. After a few alerts with no change from the driver, a smoking event is created.
Speed limit speedLimit SpeedLimit The driver travels at a speed above the speed limit designated in the cloud. The speed is detected through the GPS.
Tailgating tailgating tailgating The vehicle is too close to the vehicle in front of it.
Tamper coverOpened cover_opened The protective cover over the SD and SIM card slots is opened.
Vibration jolt jolt The vehicle moves suddenly while in standby mode. If this is set as a video event, the recording only begins after the event is triggered, since the camera does not generally record during standby mode.
Violent left turn sharpTurnLeft sharp_turn_left The driver turns left quickly.
Violent right turn sharpRightTurn sharp_turn_right The driver turns right quickly.
Virtual event virtualEvent virtual_event An event created by the user through the POST /devices/{imei}/virtual-event call or triggered by a third party.
Wrong PIN code wrongPinCode wrong_pin_code An incorrect PIN has been entered three times within three minutes. This applies to both administrators and drivers.

A webhook event response looks similar to:

Copy
Copied
{
    "type": "event",
    "data": {
        "id": 250278715,
        "serialNumber": "357660101035475",
        "eventType": "sharp_turn_left",
        "time": 1641898435,
        "lat": 32.21452118,
        "lon": 34.8277468,
        "alt": 60.50714111328125,
        "speed": 34.66800041198731,
        "metadata": "[{\"x\":-0.4734216630458832,\"y\":-0.3798898160457611,\"z\":0.2075626403093338,\"time\":1641898430220,\"speed\":10.020000457763672},{\"x\":-0.47667866945266724,\"y\":-0.5670154690742493,\"z\":0.19920749962329865,\"time\":1641898430330.........",
        "other": "",
        "files": [
            {
                "cameraId": 1,
                "file": 1641898435,
                "fileType": "video"
            }
        ]
    }
}
Parameter Description Example
type The type of webhook. event
id The ID assigned to the event. 247195231
serialNumber The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box. 357660101000198
eventType The type of event. sharpturnleft
time The time, in Unix format. 1641366374403
lat The GPS latitude. 32.17380468
lon The GPS longitude. 34.91901649
alt The GPS altitude. 60.50714111328125
speed The speed, in kilometers per hour. 47.124000549316406
metadata -> x The g-force x-axis value, in meters per second squared. -3.2773001194000244
metadata -> y The g-force y-axis value, in meters per second squared. -0.11410520225763321
metadata -> z The g-force z-axis value, in meters per second squared. 0.00830205250531435
metadata -> time The time, in Unix format. 1641366374403
metadata -> speed The speed, in meters per second. 19.479999542236328
other -> geofence_path Whether the vehicle enters or exits the geofence. Entered Fence
other -> geofence_id The ID of the geofence. 1
other -> geofence_name The name of the geofence. home
files -> cameraId The ID of the camera. 1 - road-facing camera; 2 - in-cabin-facing camera; 50+ - auxiliary cameras. 1
files -> file The ID of the file. 1641366379
files -> fileType The file type. video

An event API response, from the GET /devices/{imei}/events or GET GET /devices/{imei}/events/{eventId} call, looks similar to:

Copy
Copied
{
            "id": 250278715,
            "eventType": "sharpTurnLeft",
            "metadata": "[{\"x\":-0.4734216630458832,\"y\":-0.3798898160457611,\"z\":0.2075626403093338,\"time\":1641898430220....",
            "lat": 32.21452118,
            "lon": 34.8277468,
            "speed": 34.66800041198731,
            "status": "new",
            "severity": 3,
            "eventComments": [],
            "time": "2022-01-11T10:53:55.000Z",
            "files": [
                {
                    "cameraId": 1,
                    "fileId": "1641898435",
                    "fileType": "video"
                }
            ]
        }
Parameter Description Example
id The ID assigned to the event. 247195231
eventType The type of event. sharpTurnLeft
metadata -> x The g-force x-axis value, in meters per second squared. -3.2773001194000244
metadata -> y The g-force y-axis value, in meters per second squared. -0.11410520225763321
metadata -> z The g-force z-axis value, in meters per second squared. 0.00830205250531435
metadata -> time The time, in Unix format. 1641366374403
metadata -> speed The speed, in meters per second. 19.479999542236328
lat The GPS latitude. 32.17380468
lon The GPS longitude. 34.91901649
speed The speed, in kilometers per hour. 47.124000549316406
status The review status of the event. new
severity The severity of the event. 1 - high; 2 - medium; 3 - low. 3
eventComments Comments added to the event.
time The time, in UTC format. 2022-01-05T07:06:19.000Z
files -> cameraId The ID of the camera. 1 - road-facing camera; 2 - in-cabin-facing camera; 50+ - auxiliary cameras. 1
files -> fileId The ID of the file. 1641366379
files -> fileType The file type. video