Surfsight API changelog
E7-8 May 2023
New features and enhancements
New sdCardFormatted
event
SUR-6087
In devices with firmware 3.11.25 or above, each time the SD card is formatted, through the device, or the GET /devices/{imei}/format-storage
API call, the sdCardFormatted
event is triggered and the SD card receives a new UUID, a unique identifier.
In the GET /devices/{imei}/events/{eventId}
, GET /devices/{imei}/events
, and POST /organizations/{orgId}/events
API calls, as well as webhook, the response will include the new event, manufacturer information, and the UUID assigned to the most recent format.
Note
This feature is only available on devices with firmware 3.11.25 or above.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5702 | The following parameters in the PUT /devices/{imei}/event-config , POST /organizations/{orgId}/event-settings , and PUT devices/event-config API calls were optional and did not return an error when missing: PUT /devices/{imei}/event-config , POST /organizations/{orgId}/event-settings , and PUT devices/event-config . |
The following parameters are required in the PUT /devices/{imei}/event-config , POST /organizations/{orgId}/event-settings , and PUT devices/event-config API calls: speedLimit , when configuring speedLimit events; drivingDuration , when configuring possibleFatigue events; headwayAlertDayThreshold , headwayAlertNightThreshold , and headwayAlertTime , when configuring tailgating events; and laneWeavingTimes and laneWeavingDurationSeconds , when configuring laneWeaving events.The API call returns an error when trying to enable the event type without the required parameters.These changes may impact your use of the API service. |
Note
Due to a new more stringent validation process, in devices
with tailgating
events that had corrupted or missing configurations, the tailgating
events were disabled. Partners impacted by this situation were contacted directly by the Technical Account Manager team. If you have any questions please contact your Technical Account Manager.
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Event Syntax Retrieve event Retrieve list of events Retrieve organization events |
sdCardFormatted event added. |
https://developer.surfsight.net/developer-portal/event-syntax/ https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvent/ https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvents/ https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationsEvents/ |
Known issues
Issue ID | Problem |
---|---|
SUR-3605 | Live video may sometimes flash continuously while streaming. We are monitoring this issue and evaluating possible solutions. |
SUR-5044 | Locked dashcams' event settings are not set to off by default. They continue to send video to the cloud using data from the mobile network for any events configured with video attached. Work-around: Before locking a dashcam, change all of its event settings to off. |
SUR-6004 | For a period of time between March 13th and March 28th, all MV+AI beep events (available only through the API) were classified as distracted driving beep events in the cloud. This is no longer occurring. We are working on correctly classifying the beep events from the time period above. |
E5-6 April 30, 2023
New features and enhancements
Add new calls for bulk and organization data usage
SUR-5568
The new POST /devices/bulk-data-usage
call returns an array with the data usage for a list of selected IMEIs for up to 100 devices per call.
The new GET /organizations/{orgId}/devices-data-usage
call returns an array with the data usage for all the devices in an organization. Default pagination is 100 devices per page with a maximum of 200 devices per page.
These calls do not return Twilio data. For Twilio data, use the GET /devices/{imei}/data-usage
call to retrieve data usage for each device.
Note
These calls do not return Twilio data. For Twilio data, use the GET /devices/{imei}/data-usage
call to retrieve data usage for each device.
Recording timeline reusable component
SUR-5681
Using our new recording timeline reusable component, you can now quickly and easily integrate our frontend features inside your application, while keeping your code reliable and consistent across different places and use cases. The recording timeline component shows available recordings in a timeline, enabling selecting, playing, and downloading recordings from a device that is online, or in standby mode. Our reusable component includes in-depth step-by-step guides. For more information, see About reusable components.
The components are reusable, meaning they can be implemented in multiple places inside the platform, eliminating the need to develop and maintain them all. They are configurable based on a list of variables, and their abilities can be extended by adding extra code.
The reusable components are designed to:
- make the integration process easier and faster
- reduce the amount of development resources necessary for integration
Developers can integrate by linking to the cloud, or alternatively embedding the component package within the partner's environment.
New webhook URL parameter for alarms
SUR-5810
A new webhook alarm URL parameter, alarmsWebhookUrl
, has been added to the POST /organizations/{orgId}/webhook-settings
call. This parameter enables partners to receive device related alarms and react accordingly. This parameter is also available in the calls GET /organizations/{orgId}/webhooks
, PUT /organizations/{orgId}/webhooks
, and POST /organizations/{orgId}/webhooks
.
New event parameters have been added to the Organization settings options
SUR-5874
The events laneWeaving
and qrCode
have been added to the POST /organizations/{orgId}/event-settings
call for all devices in an organization.
Increased range for tailgating parameters
SUR-5909
The maximum time for the headwayAlertDayThreshold
and headwayAlertNightThreshold
parameters have been increased to 15,000 milliseconds. These parameters can be found in the API calls PUT /devices/{imei}/event-config
, PUT /devices/event-config
, and POST /organizations/{orgId}/event-settings
.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5727 | Custom styling for reusable components didn't work in Safari iOS. | Custom styling for reusable components works as expected in all web browsers. |
SUR-5743 | Devices saved and uploaded events prior to device activation. | Events created before the device was activated are not saved. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Update device webhooks settings | Added new webhook URL parameter, alarmsWebhookUrl . |
https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhookSettings/ |
Add device to webhook subscription | Added new webhook URL parameter, alarmsWebhookUrl , to call requests and responses. |
https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook/ |
Replace webhooks subscription devices | Added new webhook URL parameter, alarmsWebhookUrl , to call requests and responses. |
https://developer.surfsight.net/openapi/surfsight/operation/putOrganizationWebhooks/ |
Retrieve organization webhooks | Added new webhook URL parameter, alarmsWebhookUrl , to call requests and responses. |
https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationWebhooks/ |
Webhooks | Added information about the new webhook URL parameter, alarmsWebhookUrl . |
https://developer.surfsight.net/developer-portal/webhooks/#what-can-you-use-webhooks-for |
Update default event settings | Added new event parameters. | https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationEventSettings/ |
Recording timeline component | Added new document about the recording timeline component. | https://developer.surfsight.net/developer-portal/components/component-recording-timeline/ |
Set events settings | Updated maximum time for the headwayAlertDayThreshold and headwayAlertNightThreshold parameters. |
https://developer.surfsight.net/openapi/surfsight/operation/putEventConfig/ |
Bulk configure events settings | Updated maximum time for the headwayAlertDayThreshold and headwayAlertNightThreshold parameters. |
https://developer.surfsight.net/openapi/surfsight/operation/putBulkEventConfig/ |
Update default event settings | Updated maximum time for the headwayAlertDayThreshold and headwayAlertNightThreshold parameters. |
https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationEventSettings/ |
E3-4 April 2023
New features and enhancements
Add liveVideoTimeoutSeconds parameter
SUR-5749
The new liveVideoTimeoutSeconds
parameter enables users to set the amount of time a live video plays before ending automatically. Users can choose a time frame of 30 seconds or more.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5946 | Live streaming stops immediately after starting when using Safari browser. | Live streaming works as expected, stopping only when the preset time limit is reached, in all browsers. |
SUR-5869 | The documentation for the POST /organizations/{orgId}/devices/calibrate-accelerometer call stated the device must be online. |
The documentation for the POST /organizations/{orgId}/devices/calibrate-accelerometer call now states the device must be online or in standby mode. |
SUR-5739 | The example given for the response to the POST /organizations/{orgId}/events call was missing the imei parameter. |
Documentation in the Surfsight Developer Portal has been updated to the correct response. |
SUR-5519 | Responses for the GET /organizations/{orgId}/default-settings call returned sensitive information. |
The password parameter in the recordingEncryption object returned in the GET /organizations/{orgId}/default-settings call has been removed.These changes may impact your use of the API service. |
SUR-5574 | When a user attempted to create a virtual event with the POST /devices/{imei}/virtual-event call for a device to which they didn’t have access, an incorrect error message was returned. |
When a user attempts to create a virtual event with the POST /devices/{imei}/virtual-event call for a device to which they don’t have access, a 404 not found error is now returned regardless of the dashcam status. These changes may impact your use of the API service. |
SUR-5696 | Responses to the GET /devices/{imei}/data-usage call displayed the last thirty days.Responses included data that was not relevant. |
Responses for the GET /devices/{imei}data-usage call are now for the current month.The twilioFleet response object is renamed mobileProvider .Some data previously included in the response object has been removed. The response now looks similar to: { These changes may impact your use of the API service. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Update organization | New liveVideoTimeoutSeconds parameter added to documentation. |
https://developer.surfsight.net/openapi/surfsight/operation/patchOrganization/ |
Stream live video | Stream live video | https://developer.surfsight.net/developer-portal/guides/view-live-video/#implementing-live-streaming-in-your-application |
Retrieve organization events | Response corrected to include the mandatory imei parameter. |
https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationsEvents/ |
Calibrate accelerometers | Description corrected to apply to devices online and in standby mode. | https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationDevicesCalibrateAccelerometer/ |
E1-2 February 2023
New features and enhancements
New event for device activation
SUR-5752
An event, deviceActivation
, is now triggered when a device is activated. This event is available in any calls where events are retrieved and via webhook.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5627 | The dashcam PIN 4121 is not available for use. However, it was possible to change the PIN to 4121 in the API. | Using the dashcam PIN 4121 returns the appropriate message that it is not available for use. |
SUR-5663 | When a dashcam was in standby mode, the GET /devices/{imei}/cameras/{cameraId}/snapshot call returned an error message when the time parameter was used. The call also returned the incorrect error message when the dashcam was offline. |
When a dashcam is in standby mode, the GET/devices/{imei}/cameras/{cameraId}/snapshot call with the time parameter returns the requested snapshot. The call returns the correct response message for every dashcam status. |
SUR-5702 | Event settings that were missing required parameters did not return an error message. | Event settings that are missing parameters return the appropriate error message. |
SUR-5741 | The GET /devices/{imei}/gps call on the EU cloud was slow. |
The GET /devices/{imei}/gps call on the EU cloud is now performing at the expected speed. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Event syntax | Add the deviceActivation event |
https://developer.surfsight.net/developer-portal/event-syntax/ |
E24-25 January 2023
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-4888 | The DELETE /devices/{imei}/events/{eventId} call was slow. |
The DELETE /devices/{imei}/events/{eventId} call is now performing at the expected speed. |
SUR-5770 | Some possibleFatigue events received through a webhook did not contain an event ID. |
All events have event IDs attached. |
E22-23 November 2022
No changes in this release.
E20-21 October 2022
New features and enhancements
Event media reusable component
SUR-5197
Using our new event media reusable component, you can now quickly and easily integrate our frontend features inside your application while keeping your code reliable and consistent across different places and use cases. The event media component enables playing video or showing snapshots of an event from a specific device. Our reusable component includes in-depth step-by-step guides.
The components are reusable, meaning they can be implemented in multiple places inside the platform, eliminating the need to develop and maintain both. They are configurable based on a list of variables, and their abilities can be extended by adding extra code. Additionally, if the component appears in several places inside an application, a developer can copy the component to additional places in the project, configuring different functionality and appearance for each place separately.
The reusable components are designed to:
- make the integration process easier and faster
- reduce the amount of development resources necessary for integration
Developers can integrate by linking to the cloud, or alternatively embedding the component package within the reseller partner's environment.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5061 | When devices were offline, a 200 code was returned, indicating that there were no recordings available. | When devices are offline, a 417 code is now returned, indicating that the device is offline. |
SUR-5331 | Speeds were recorded even though vehicles were stationary. | No speed is recorded for stationary vehicles. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Event media component | Added specific details about the Event Media component. | https://developer.surfsight.net/developer-portal/components/reusable-intro/ |
E18-19 October 2022
New features and enhancements
Tailgating
SUR-5526
The headwayAlertTime
parameter is the amount of time during which a vehicle continuously drives too closely to the vehicle in front of it. We increased the maximum value from 5,000 to 60,000 milliseconds.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-4895 | When users added dashcams to an organization, an error message was received, even though the dashcams were successfully added. | When users successfully add dashcams to an organization, no error message appears. |
SUR-5163 | Users could not perform a factory reset on dashcams that were not associated with an organization. | A factory reset can now be performed on all dashcams. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Calibrate road-facing ADAS | Update the maximum value of the headwayAlertTime parameter. |
https://developer.surfsight.net/developer-portal/components/calibrate-adas/ |
API reference Set event settings |
Update the maximum value of the headwayAlertTime parameter. |
https://developer.surfsight.net/openapi/surfsight/operation/putEventConfig/ |
API reference Bulk configure settings |
Update the maximum value of the headwayAlertTime parameter. |
https://developer.surfsight.net/openapi/surfsight/operation/putBulkEventConfig/ |
E16-17 September 2022
New features and enhancements
Increased limit for purge days
SUR-5327
Purge limit has been increased from 120 to a maximum of 366 days. The enhancement requires a commercial agreement. Please contact your account manager for more information.
Users with administrator permissions can now access device metadata
SUR-5115
Once a device is added to an organization, users with administrator permissions can now access device metadata via GET /devices/imei/
API call.
E14-15 August 2022
New features and enhancements
Live Video reusable components
Using our new Live Video reusable componnent, you can now quickly and easily integrateour frontend features inside your application while keeping your code reliable andconsistent across different places and use cases. Our reusable component includes in-depth step-by-step guides.
The components are reusable, meaning they can be implemented in multiple places insidethe platformeliminating the need to develop and maintain both., they are configurablebased on a list of variables, and their abilities can be extended by adding extra code.Additionally, if the component appears in several places inside an application, a developercan copy the component to additional places in the project, configuringdifferentfunctionality and appearance for each place separately.
The reusable components are designed to:
- make the integration process easier and faster
- reduce the amount of development resources necessary for integration
Developers can integrate by linking to the cloud, or alternatively embedding thecomponent package within the reseller partner�s environment.
Enable Organization settings profile
SUR-4275 and SUR-5263
API calls now include the new isOrganizationProfileEnabled
parameter forenabling and disabling the Organization settings profile. When turned on, all new devices are automatically configured with this profile when added; when turned off, devices that are newly added to the organization do not get the configuration from this profile.
To toggle the profile on and off, use the new boolean parameter for the patchOrganization
API call. In addition, the getOrganization
call response now includes the current value for the parameter. The parameter default is enabled.
Note
When the Organization settings profile is enabled and users configure settings using a combination of single, bulk and this profile, each device isconfigured based on its most recent updates, regardless of method.
Fixed items
Issue ID | Issue summary | Resolution |
---|---|---|
SUR-5370 | The virtual event didn't create. The second generated virtual event with the same time in request: 200 with "eventId": null | Virtual events are now created correctly. |
Documentation updates
https://developer.surfsight.net/developer-portal/components/reusable-intro/ | ||
https://developer.surfsight.net/developer-portal/components/calibrate-adas/ | ||
https://developer.surfsight.net/developer-portal/components/calibrate-adas/ |
E12-13 July 2022
New features and enhancements
Enter and exit standby events
SUR-4711
Two new events, Entering standby and Exiting standby, are now available as text notifications, without video or a snapshot attached. GPS information is included in these events.
These events are triggered when a dashcam that is connected to constant power enters or wakes up from standby mode.
Users can configure this setting for single devices, in bulk and from the Organization level using the 'devices/{imei}/events' API endpoint.
Fixed items
Issue ID | Issue name | Resolution |
---|---|---|
SUR-5101 | Specific IMEIs return a server error to obtain event configuration | Event settings are correctly retrieved for all devices with the GET /devices/event-config API call. |
SUR-5262 | Error code issue for the device setting API | When users successfully change driver position with the POST organizations/{orgId}/device-settings call, the correct response code is now returned. |
SUR-4947 | Error code issue for supervisors trying to add devices | When supervisor users add devices to an organization successfully with the POST organization/devices API call, the correct response code is now returned. |
SUR-5107 | Missing header in the response created CORS error on downloading video files for events | When downloading event files with the POST devices/{imei}/events API call, the response correctly contains the control header. |
Documentation updates
Document title | Description of change | Developer portal URL |
---|---|---|
Calibrate road-facing ADAS | Added permissions indication to user guide | https://developer.surfsight.net/developer-portal/components/calibrate-adas/ |
API reference | Updated info for Standby events | https://developer.surfsight.net/openapi/surfsight/tag/Events/ |
E11 June 2022
New features and enhancements
Speed profile
Trips now include speed profiles as part of their metadata. Speed profiles can be retrieved as part of the API /devices/{imei}/gps
call, which now includes the following new parameters:
postedSpeed
- when available, the general speed limit for most vehicles that is posted at the specific geographical point, in meters per second.postedSpeedTrailer
- when available, the speed limit for trailers that is posted at the specific geographical point, in meters per second.postedSpeedhvg
- when available, the speed limit for heavy goods vehicles that is posted at the specific geographical point, in meters per second. , displaying a line graph of:- vehicle driving speed
Throughout the course of every active trip, the dashcam uploads the GPS location to the cloud every five (5) seconds. When posted speed limit is available for the recorded GPS point, the vehicle driving speed and the posted speed limit are also stored with the trip at that GPS point, in addition to the latitude, longitude and other trip-related data.
Managers can leverage this data to review a driver's driving behavior, analyze trends, and enforce organizational policies.
Note
This is the first phase of the implementation of the speed profile. In the future, we will develop more speed-related features and include additional databases for improved accuracy.
Documentation updates
Document title | Description of change | Knowledge base URL | |
---|---|---|---|
Telemetry => Retrieve GPS data | Added speed profile parameters and descriptions | https://developer.surfsight.net/openapi/surfsight/operation/getDeviceGps/ |
E10 May 2022
New features and enhancements
Retrieve drivers via organization
As part of the newly released driver service, the 'GET /drivers/org={org}' call enables reseller partners and organization administrators to easily retrieve a specific driver using the organization ID. Users with multi-partner tokens can also use this to find drivers in different organizations.
New parameter in data usage API call
The 'GET /v2/devices/imei/data-usage' call now returns a billingDayOfMonth parameter. This makes it easier for reseller partners and fleet managers to keep track of monthly data billing cycles.
Fixed items
The following table lists the items that we fixed for this release:
Issue ID | Problem | Resolution |
---|---|---|
SUR-4830 | Reseller partners and organization administrators did not receive Possible fatigue events, as these were not being transmitted via webhook. | Users subscribed to event notifications via webhook now receive all event notifications, including Possible fatigue. |
SUR-5153 | The GET /devices/{IMEI}/device-config call did not include driverPosition in the response ("value: left" or "value: right"). | The GET /devices/{IMEI}/device-config call now returns all of the appropriate values, including driverPosition. |
SUR-5162 | The GET /organizations/{orgId}/devices call sometimes returned a disconnected dashcam as "status": "online". | All users are now see the correct status of their dashcam. |
Document change log
The following table lists the documents that were updated and or added to the Developer Portal:
Document title | Description of change | URL |
---|---|---|
API reference => Drivers => Get drivers | New call: retrieve a list of drivers by organization ID | https://developer.surfsight.net/openapi/surfsight/operation/getDrivers/ |
API reference => Devices => Get data usage | New parameter (billingDayOfMonth) | https://developer.surfsight.net/openapi/surfsight/operation/getDeviceDataUsage/ |
E9 May 2022
New features and enhancements
Driver service endpoint
The Surfsight driver service is a set of new features (and enhancements to previous soft launches) that allow fleets with multiple drivers who often share the same vehicles, to associate trip data and events to the relevant driver. Integration with the Driver API endpoint enables:
Driver calls can be accessed via https://api-prod.surfsight.net/v2/drivers. With this endpoint, organization administrators can:
- Create new drivers in an existing organization
- Assign a driver to a dashcam prior to a trip, and retroactively (for a selected time period)
- Un-assign a driver from a dashcam
- Request the driver metadata in response to existing calls to retrieve trips or events
- Retrieve the driving history of a specific dashcam, driver, or vehicle from a specified time range
- Edit drivers for a specified organization
- Delete drivers for a specified organization
E8 May 2022
Features
Partners managing all devices
In an organization with devices from multiple reseller partners, reseller partners can now make calls that include any of those devices.
This makes it easier for multiple reseller partners who work on devices for a single organization to assist fleet managers in managing that entire organization.
Shared access to an existing organization
The exclusivePartnerOnly
parameter is now included in the PATCH /organizations/{orgId}
call. This enables reseller partners to enable or disable shared access to an existing organization, making it easier to update organizations as the needs of a fleet manager evolve.
When disabling shared access, reseller partners must first remove all devices from the reseller partner that will no longer be part of that organization.
Fixes
Problem | Resolution |
---|---|
Multiple users were repeatedly receiving the "SD card may be fragmented or corrupt. Camera is not recording video" message as a false alarm. | Users are no longer receiving this false alarm. |
Some users were receiving live videos and video recordings for de-activated devices. | API requests to the media server for de-activated devices no longer return videos or recordings. In such cases, error 423 is now, correctly, returned instead. |
When attempting to retrieve a live stream through the sample application on the Developer Portal, a retry webRTC was missing from the sample code. Users were receiving a 404 error message with no possibility of retrying. | The retry webRTC is now working in the sample code. Attempts to retrieve a live stream automatically retry until the live stream is retrieved. |
Reseller partners could manage external users of an organization, even though they did not own the data and should not have been able to give those users access. | Reseller partners can no longer add or remove external users from the Partner Portal or API. This is to protect the data owned by fleet managers. Fleet managers can still manage external users from the Surfsight Portal. |
E7 April 2022
Features
Factory reset call
The new POST /devices/{imei}/factory-reset
call enables partners and organization administrators to reset a device to its factory settings. If the device is offline, it is reset when it comes back online.
Organization profiles
Organization administrators and supervisors can now create organization profiles for organizations with devices from multiple partners with the following calls:
POST /organizations/{orgId}/device-settings
POST /organizations/{orgId}/event-settings
POST /devices/{orgId}/webhook-settings
New standby events
Two new events, standbyEnter
and standbyExit
, are now available as text notifications, without video or a snapshot attached.
These events are triggered when a device that is connected to constant power enters or wakes up from standby mode.
New external users call
The new POST /organizations/orgId/external-users
call enables organization administrators to add and remove admin users from a different organization. These admin users can then make API calls for your organization and add external integrations.
Fixes
Problem | Resolution |
---|---|
If users were not signed in and clicked on an event link from an event notification email, they would not be directed to the correct event once they signed in. | If users are not signed in and click on an event link from an event notification email, they are directed to the correct event once they sign in. |
E6 April 2022
Features
Additional parameter returned in virtual event call
The eventId
parameter is now returned in the POST /devices/{imei}/virtual-event
call. Use this parameter to:
- update the event severity
- add comments
- delete the event
More alarm actions
You can now change the status of an alarm from read to unread and closed to open in the POST /alarms/{alarmId}/actions
.
Improved terminology
The terminology for the active status of a dashcam has been improved. Previously it was Activated, and is now Active.
Fixes
Problem | Resolution |
---|---|
When receiving an email notification of an event, forgot password emails were sometimes sent instead of event notification emails. | The correct emails are now sent. |
E5 March 2022
Features
Default webhook settings for an organization
A new POST /organizations/{orgId}/webhook-settings
call assigns webhook destination URLs. This call sets the destination URL for the event and GPS webhooks for an entire organization.
For the event webhook, set the destination URL with webhookEventsAddress
, and for the GPS webhook, with webhookGpsAddress
.
You can assign up to three destination URLs for each type of webhook.
Additional filter and sort parameters when retrieving events
New optional query parameters have been added to the GET /devices/{imei}/events
call. These parameters include:
- filtering by
eventType
- return specific event types - filtering by
speed
- return events that occurred at or above a specific speed - sorting by
eventType
- sort results by the event type - sorting by
fileType
- sort results by the file type (video, snapshot, text) - sorting by
order
- sort results from the most recent to least recent (descending) or least recent to most recent (ascending)
E4 March 2022
Features
Default event settings for an organization
A new POST /organizations/{orgId}/event-settings
call enables you to configure the default event settings for an entire
organization. The newly configured settings then apply to both new devices added to the organization, and to previously
existing devices in the organization.
The following roles can make this call:
- partners
- sub-partners
- administrators
- supervisors
List groups to which users are associated
A new groups
parameter is now returned in the GET /organizations/{orgId}/users
call. This parameter lists any groups
the user is part of, including the id
and name
of each one.
Increase in number of geofences
The number of geofences you can set with the PUT /devices/{imei}/geofences
call is now 99. Previously, only 19
geofences could be set.
Fixes
Problem | Resolution |
---|---|
After an event was deleted, the event file link still showed video of the event. | Once an event is deleted, video of the event is deleted as well and can no longer be viewed. |
E3 February 2022
Features
Default settings for an organization
The new PUT /organizations/orgId/defaultSettings
call enables partners and organization admins to set default settings
for an organization's devices. These settings apply to all current devices and any devices added to the organization in
the future.
Unsubscribe from email notifications
Users can now unsubscribe from email notifications with the DELETE /{imei}/notification-recipients/{email}
call. They
can unsubscribe from all notifications, or only from those for a particular event.
E2 February 2022
Features
Organization profile - device settings
The new PUT /organizations/orgId/defaultSettings
call enables partners and organization admins to set default settings
for an organization's devices. These settings apply to all current devices and any devices added to the organization in
the future.
Mixed fleets solution
The POST /organization
call has a new parameter, exlusivePartnerOnly
. When a partner enables fleet managers to
add dashcams from other (multiple) partners to a new organization.
New Possible fatigue event
A new event, Possible fatigue, can now be set in the PUT /devices/{imei}/event-config
and
PUT /devices/event-config
calls.
Possible fatigue events are triggered when a distracted driving event occurs and the driver has already been driving for more than the configured number of daily driving hours.
Users can configure the drivingDuration
parameter to indicate the amount of driving time in one day before the first
Possible fatigue event is triggered. By default, drivingDuration
is set to eight hours. Valid values are between
four and twenty hours.
New parameters for time and distance
The GET /me
call now returns two additional parameters:
- measurement - the measurement units used in the Surfsight Portal. The units can be either US/imperial or metric.
- timeFormat - the time format used in the Surfsight Portal. The format can be either 24 hours or AM/PM.
E1 January 2022
Features
Webhooks improved delivery
If a webhook is not delivered due to your server being down, Surfsight now tries sending it again up to six times. The final attempt takes place about 24 hours after the original failed delivery.
E25 & E26 January 2022
Features
Updated retrieve snapshot call
Users can now make the GET /devices/{imei}/cameras/{cameraId}/snapshot
call with a timestamp in the query string to
retrieve a snapshot from an earlier time.
Additionally, metadata is now returned with the call. This metadata includes:
- timestamp
- latitude
- longitude
- speed
New call to retrieve events by organization
A new POST /organizations/{orgId}/events
call enables partners to retrieve a list of events by organization. This
expands the available search capability, which previously only allowed retrieving events by individual device.
New call to add recipients for email notifications in bulk
A new POST /devices/events/{eventType}/notification-recipients
call enables admins and supervisors to add recipients
for email notifications of an event in bulk.
Pagination
The GET devices/{imei}/events
and GET /organizations/{orgId}/devices
calls now have optional parameters to assist
with pagination. Pagination helps to divide a large amount of data and present it in a more understandable manner.
The parameters include:
- limit - the maximum number of results to retrieve
- offset - the number of results to omit
The pagination parameters are returned in the response as metadata. In addition to the limit and offset, the count (the total number of results) is returned as well.
New role parameter
There is now a role
parameter returned in the GET /me
call. The roles are:
- Administrator
- Supervisor
- User
- Restricted
For more information on the different roles, go here.
E24 December 2021
Features
New parameter to set recording retention time
The PATCH /organizations/{orgId}
call now includes the deviceRetentionMinutes
parameter. This parameter enables
admins and supervisors to set and update the recording retention times for all the devices of an organization. The
recording retention time is the amount of time that recordings are kept on the SD card.
Fixes
Problem | Resolution |
---|---|
When an API call was made with an expired token, a 401 error message was returned. | When an API call is made with an expired token, a 504 Gateway Time-out error is now returned. |
E23 November 2021
Features
New endpoint to retreive safety score
The new GET /devices/{IMEI}/score
call enables users to receive the safety score of any device. The safety score
calculates how many events have occurred in a certain time range while taking into account the total distance traveled
during that time.
Speed data in virtual events
When creating a virtual event, the speed from the most recent GPS location is included. If there is no GPS data, the speed is shown as null.
Filter trips by minimum distance
Users can now set a minimum trip length parameter, minimumDistance
, to filter their trips in
the GET /devices/{imei}/trips
call. Trips shorter than the value set in this parameter no longer appear in the
list of trips retreived.
E22 November 2021
Features
New endpoint to delete groups
The new DELETE /organizations/{orgId}/groups
call enables administrators and supervisors to delete groups by their groupID
.
New endpoints to manage users
Three new API calls have been created to help manage users:
- The
GET /organizationUsers/{organizationId}
call enables administrators, supervisors, and users to retrieve a list of the users associated with a specific organization. - The
POST /userPermissions/{id}/{organizationId}
call enables administrators to edit the role and group access permissions of a specific user. - The
DELETE /users/{id}
call enables administrators to delete a specific user.
New endpoint to update regional settings of users
The new PUT /users/{userId}/update-settings
call enables administrators and supervisors to update the regional settings of a user. These settings include the measurement units and time format the user views in the Surfsight Cloud.
New endpoint to update group names
The new PUT /organizations/{orgId}/groups
call enables administrators and supervisors to update the names of groups associated with a specific organization.
New endpoint to retreive list of recipients of event notifications
The new GET /devices/{imei}/notification-recipients
call enables administrators, supervisors, and users to retrieve a list of the email recipients for event notifications.
E21 October 2021
Features
New access to webhook API requests
Both partners and partner contacts can now perform webhook API requests.
New virtual event flow
There is a new flow for virtual events. When a virtual event is received, the timestamp for the requested files takes into
account the new durationSeconds
parameter.
Fixes
Problem | Resolution |
---|---|
The GET /devices/{imei}/cameras/{cameraId}/snapshot request returned the wrong error code when a nonexistent IMEI was entered. |
When an invalid IMEI is entered for the GET /devices/{imei}/cameras/{cameraId}/snapshot , the request now returns a 404 "Not Found" error message. |
The use of request GET /devices/{imei}/cameras/{cameraId}/snapshot , was returning 500 "Internal Server Error" for cases where the snapshot resource was unavailable. |
The request now returns a 404 "Not Found" error message if the snapshot resource is unavailable. |
E20 October 2021
Features
New group parameter
When creating a user with the POST /organizations/{orgId}/users
request, you can now specify which groups the user will
have access to by using the optional groupIds parameter. If groups are not specified, the user will have access to
all groups.
Fixes
Problem | Resolution |
---|---|
API requests made while Surfsight deployed a new release were timed out. | API requests that are now made while Surfsight deploys new releases successfully go through and are not timed out. Additionally, Surfsight now actively monitors for API requests that get timed out. |
In some cases of a corrupt or fragmented SD card, the alarm would not go off. | This has been fixed, and alarms are now consistently going off when necessary. |
E19 October 2021
Features
New endpoint to receive white label details
The new GET /white-label-information/{whiteLabelDomainAddress}
request enables reseller partners to receive white label portal details. These details include:
- the images used in the portal
- the logo and favicon used in the portal
- the name and domain address of the portal
- the privacy policy and EULA of the portal
- the sender address for emails sent from the portal to users
- the color theme of the portal
- Latitide and longitude included in virtual event
When creating a virtual event, the latitude and longitude from the most recent GPS location are included. If there is no GPS data, the latitude and longitude are equal to -1.
C18 September 2021
Features
Alarms added to the device health endpoint
Device alarms are now returned in the GET /device-health
call. This makes alarms more visible, enabling you to take action quicker.
Fixes
Problem | Resolution |
---|---|
When two events occurred at the same time, if one was deleted then the media files that were shared by both were deleted. | When two events occur at the same time, if one is deleted then the media files that are shared by both are no longer deleted. |
When an event occurred, the email notification sent did not include the device name. | When an event occurs, the email notification sent now includes the device name. |
C17 August 2021
Features
Recording health update
When a device is removed from an organization, the Recording Health status of that device reverts to 'not tested'.
C16 August 2021
Fixes
Problem | Resolution |
---|---|
When a device subscribed to a list of webhooks, if one of the webhooks in the list had an invalid address, then the device no longer sent notifications to any of the webhooks in the rest of the list. | When a device subscribes to a list of webhooks, notifications will always be sent to all webhooks with valid addresses. |
Virtual events sent to a webhook were sent twice, once with the data from one camera (the road-facing camera) and once with the data from two cameras (the road-facing and in-cabin cameras). | Virtual events sent to a webhook are sent once, with the data from all relevant cameras included. |
C15 August 2021
Fixes
Problem | Resolution |
---|---|
The metadata information was missing from virtual events that were in the GET /devices/{imei}/events call response. |
Metadata is now included for any virtual events in the GET /devices/{imei}/events call response. |
C14 July 2021
Features
New metadata endpoint
Reseller partners can now receive a device's metadata with the GET /devices/{imei}
call. This enables reseller partners to view a device's details, such as the organization and group it belongs to and its IMEI number.
New operational statistics endpoint
Reseller partners can now receive the operational statistics of their devices and organizations with the GET /partners/operational-statistics
call. This enables reseller partners to view statistics about their
devices and organizations, such as the number of activated devices and the number of alarms associated with their organizations in the past few weeks or months.
Updated devices endpoint
The GET /organizations/{orgId}/devices
call now returns the vehicle type in addition to its other parameters. The vehicle type affects the sensitivity at which events are triggered.
Updated organization endpoint
The name parameter in the PATCH /organizations/{orgId}
call is no longer required. You can update other organization parameters without entering or updating the organization name.
Fixes
Problem | Resolution |
---|---|
The number of events in the GET /devices/{imei}/trips call response were incorrect. Events were counted that should not have been included. |
The number of events in the GET /devices/{imei}/trips call response is now correct. Only events that should be included are in the response. |
C13 June 2021
Features
New data usage endpoint
You can now receive the data usage of a device with the GET /devices/{imei}/data-usage
request. The following is included in the response:
- mobileTx - The total data transmitted from the device, in bytes
- mobileRx - The total data received by the device, in bytes
- liveStreamingUsage - The amount of data used from live video streaming, in bytes
- eventsUsage - The amount of data used from uploading video events, in bytes
- liveStreamUsageMilli - The amount of time spent watching live video streaming, in milliseconds
- recordStreamUsageMilli - The amount of time spent watching recordings, in milliseconds
- recordStreamingUsage - The amount of data used from streaming recordings, in bytes
- recordingsUploadUsage - The amount of data used from uploading recordings, in bytes
- usageEventsTodayDay - The number of video events that have occurred today
- usageEventsTodayMonth - The number of video events that have occurred this month
New wake up endpoint
You can now wake up a device with the POST /devices/{imei}/wakeup
request. Devices can only be woken up when in standby mode.
Fixes
Problem | Resolution |
---|---|
When trying to add the imei number of a device that doesn't belong to you, the wrong response was returned. |
A 404 response code is now returned with the message 'not found: The device imei you entered is invalid. Check the imei number and try again'. |
When using the POST /devices/{imei}/virtual-event request, a 200 success response was returned even if no recordings were found. |
A 404 response code is now returned with the message 'not found: No recordings were found in the requested time range. Change the range and try again'. |
C12 June 2021
Features
New snapshot endpoint
You can now receive a snapshot from a specific camera with the GET /devices/{imei}/cameras/{cameraId}/snapshot
request.
New auxiliary camera endpoint
You can update an auxiliary camera name with the PATCH /devices/{imei}/cameras
request.
Updated organization endpoint
When a reseller partner makes the GET /organizations/{orgId}
request it now returns the organization's SSO secret in addition to its other parameters.
If the organization does not yet have an SSO secret, one is created during the request.
C11 June 2021
Features
New GPS endpoint
The GET /devices/{imei}/gps
call now returns the altitude in addition to other GPS parameters.
Fixes
Adding devices in bulk
Adding devices in bulk through the API has been fixed. Organization admins can now add devices in bulk through the API v1 and v2.