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.

Fixed items

Documentation updates

Known issues

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.

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

Documentation updates

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

{
 "data": {
  "receivedAt": "2022-11-17T14:36:04.968Z",
  "mobileTx": 60449320,
  "mobileRx": 118809561,
  "liveStreamingUsage": 0,
  "usageEventsTodayDay": 0,
  "usageEventsTodayMonth": 0,
  "liveStreamUsageMilli": 0,
  "recordStreamUsageMilli": 0,
  "recordStreamingUsage": 0,
  "recordingsUploadUsage": 0,
  "eventsUsage": 0,
  "billingDayOfMonth": 1,
  "mobileProvider": {
    "carrier":"twilio",
    "uniqueName": "Lytx Fleet",
    "dataLimit": 2000,
    "dataUsage":{
      "dataTotal": 100,
      "dataUpload": 90,
      "dataDownload": 10,
      "period":{
        "startTime": "2022-11-01T00:00:00Z",
        "endTime": "2022-11-17T14:36:04.968Z"
        }
      }
    }
  }
}

Documentation updates

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

Documentation updates

E24-25 January 2023

Fixed items

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

Documentation updates

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

Documentation updates

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.

Fixed items

Documentation updates

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

Documentation updates

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.

Documentation updates

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:

Document change log

The following table lists the documents that were updated and or added to the Developer Portal:

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

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

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

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

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

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

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

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

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

C15 August 2021

Fixes

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

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

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.