Surfsight API changelog

C9 September 2024

Developer Portal Documentation Enhancements

Documentation clarifications for endpoints

SUR-7833

The following content was updated:

Update email recipient settings

Add device to webhook subscription

Update default device settings

Update default event settings

Set user permissions

Bulk add devices - partners only

Event configuration

SUR-7838

The following endpoints were updated:

PUT/devices/{imei}/event-config

PUT/devices/event-config

POST/organizations/{orgId}/event-setting

Breaking Change

Create Drivers and Update Drivers APIs - (Validate the “organizationId ” parameter)

When creating a new driver persona in the Organization, (POST/drivers and PATCH/drivers), we will add a validation that the organizationId exists and belongs to the partner who is performing the operation. This will allow you to only create a driver persona who is in your organization.

Breaking Change

Virtual event - Validate Parameters

We will be implementing more stringent parameter validation on the virtual-event endpoint. By ensuring that all input data adheres to pre-defined criteria, we will only create events with valid parameters. You will receive an error message when attempting to enter invalid parameters.

Breaking Change

Create/Update organization - (post/organizations): Change the default for isOrganizationProfileEnabled to FALSE

At the present time, newly created organizations are automatically enabled for the “Organization Profile” feature.

To provide greater user autonomy, we will change the default setting of isOrganizationProfileEnabled to FALSE. This will allow users to opt-in to the Organization Profile feature if they choose.

Fixed items

Issue ID Issue summary Resolution
SUR-8159 The Data Usage Limit was reached earlier than expected due to Live Streaming, Live Recording, and/or events To address this issue, we adjusted the data usage thresholds for live streaming, live recording, and events. These changes should allow for longer usage periods without exceeding the data limit.
SUR-7968 Incorrect IMEI Updates in Bulk Configure Events Settings. This issue has been identified and resolved. The API now correctly updates the IMEIs for the specified organizationId, even when groupId is not provided.
SUR-7973 Create driver API fails with "BadRequestError" message when optional parameter "organizationId" is not provided To clarify the API requirements, the developer portal will be updated to explicitly note that the following parameters are mandatory when using a partner token:organizationId in query parameters organizationId in the data object of the request body
SUR-8155 The billing Status API returns the wrong response structure. After correcting the issue, the response payload for​/devices/{imei}/billing-status became (data property object as expected)

Known issues

Issue ID Problem
KB issue At kb.surfsight.net some tables are poorly formatted and may cause difficulty in reading them. We're currently working on overhauling our knowledge base and planning this fix as part of the changes. In the interim, partner resellers can refer to these PDFs in case they need a different format for better legibility.
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.

C8 September 2024

Developer Portal Documentation Enhancements

GET/audit-logs

SUR-7753

With this documentation enhancement, we updated the GET/audit logs with a recommendation to use pagination in the query paramters. This prevents timeouts when retrieving large amounts of data.

Webhook Upgrade

SUR-7997

With this documentation enhancement, we deleted three parameters which were no longer relevant: "postedSpeed", "postedSpeedHgv", and "postedSpeedTrailor".

Bulk & Amp; Org Event Settings

SUR-7989

In this enhancement, we added the line as follows: "Available for AI-12 devices with firmware 3.14 or higher."

Breaking Change

V2 Create/Update API endpoints - Validate user access level

SUR-7503

Due to a more stringent validation process, the viewer role, which can be assigned to users in the Partner Portal, only has access to limited functions across all platforms.

Breaking Change

Add event type validation for "accon"&"accoff“ events

SUR-7613

The events accOff and accOn are available as text only, without snapshots or videos.

C7 August 2024

New features and enhancements

Increase video protection through watermarks

SUR-7271

Our solution empowers partners and end-customers with greater protection of the video. It allows embedding customizable watermarks on captured videos and snapshots.

Use the cloud service to provide time zone updates

SUR-6977

Some cellular providers do not provide Daylight Savings Time updates, so we developed our own service for this.

Increased data security with an enhanced encryption mechanism

SUR-7376

We upgraded the level of data security by hardening the encryption mechanism on the device side with more robust encryption algorithms.

Hotspot control

SUR-7308

You can now remotely designate a dashcam as a hotspot. Your security posture is enhanced by controlling the enablement of dashcam as a hotspot.

Increase data reliability by consolidating data communication points

SUR-7473

There is now a new option to consolidate domains used in media links.

Retrieve all partner devices with a new API Endpoint

SUR-7611

You can increase efficiency and save time by retrieving all partner organization's devices with a new API Endpoint, Retrieve partner devices (GET/partners/ devices).

Fixed items

Issue ID Issue summary Resolution
SUR-7492 No webhook sent when a virtual event is created with the "none" mediaType. We now send webhooks for a virtual event even when there are no media files.
SUR-7775 Retrieve device data usage V2 endpoint – missing request ID from reply. We added "reauestId". The results now include "requestID".

Known issues

Issue ID Problem
KB issue At kb.surfsight.net some tables are poorly formatted and may cause difficulty in reading them. We're currently working on overhauling our knowledge base and planning this fix as part of the changes. In the interim, partner resellers can refer to these PDFs in case they need a different format for better legibility.
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.

C6 July 2024

New features and enhancements

Added subscription ID updates to audit logs

SUR-7525

When a device subscription ID is updated the action is recorded in the audit log. The subscription ID relates to whether or not a device will update firmware automatically when available. The response to theGET /audit-logs API call now includes the following additional information:

  • The message "Device subscription id update"
  • The reason, or source, for the update
  • When the subscription was updated
  • The user who initiated the update
  • The previous and new subscription ID values. A value of 10 or above means firmware updates are not made automatically

Endpoint documentation updates to clarify endpoint functionality

SUR-7487

API call descriptions have been updated to clarify their functions. The following notes have been added where applicable:

  • Note: PUT calls update data entirely. Any data not mentioned in the call, will be deleted.
  • Note: POST calls create new data, and do not affect existing data.
  • Note: PATCH calls update data partially. Any data not mentioned in the call, will be kept as is.

New systemMessages parameter for notification of removed devices

SUR-7337

A new systemMessges webhook type, deviceRemoved, has been added to enable a webhook notification when a device is removed from a partner's inventory. The new system messages webhook is available in the POST /organizations/{orgId}/webhook-settings, PUT /organizations/{orgId}/webhooks, POST /organizations/{orgId}/webhooks, and GET /organizations/{orgId}/webhooks API calls.

Fixed items

Issue ID Issue summary Resolution
SUR-7527 In some cases, when a virtual event was created when the dashcam first wakes up, the media for virtual events was not displayed and an error message was received. Virtual events are created when the dashcam first wakes up and the media is added when it is ready.
SUR-7656 The field partnerId was added to the webhook payload resulting in an error message when the webhook system message type deviceStatus was sent. The additional field in the webhook payload was removed so that the webhook notifications work as expected.

Documentation updates

Document title Description of change Developer portal URL
Webhooks deviceRemoved system message webhook type added https://developer.surfsight.net/developer-portal/webhooks/
Add device to webhook subscription

Replace webhooks subscription device

Update device webhooks settings

Retrieve organization webhooks
deviceRemoved system message webhook type added https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook/

https://developer.surfsight.net/openapi/surfsight/operation/putOrganizationWebhooks/

https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhookSettings/

https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationWebhooks/

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.

C5 June 2, 2024

New features and enhancements

New endpoint to make partial updates to webhook configurations

SUR-7480

The new endpoint PATCH organizations/{orgId}/webhook-settings updates only the webhook settings that are configured in the call. Any webhook settings not configured in the call, remain as they are.

New parameter to assign accessLevel to a partner user

SUR-7502

In the POST /partners/{partnerId}/contacts API endpoint, a new parameter is available to assign access level to a partner contact. Options for access level include viewer, editor and editorWithoutMediaAccess. This parameter is optional, with the default being editor. For more information about user access levels, see Users.

New parameters added to privacy device settings to restrict event creation and live streaming video

In endpoints for device configurations and settings, under the existing privacy object, two new optional parameters have been added.

  • SUR-7481

    allEventsEnabled - When set to false, all events, audio, and visual alerts will not be created. If virtual events are triggered while the event is enabled, but the privacy settings disable it, an error code will be returned. When set to true all events, audio, and visual alerts are created according to device and event configuration.

    :::info Note

    In privacy configurations, if allEventsEnabled is set to true, but a camera parameter is set to false, the camera parameter will prevent event or media, according to the configuration.

    Additionally, if allEventsEnabled is set to false, but mvaiEnabled is set to true, MV+AI events are not created.

    :::

  • SUR-6980

    liveStreamEnabled - When set to false, viewing live streaming videos from the device is not possible. This occurs even if the liveVideo parameter is enabled. When set to true, live streaming video is allowed according to device configuration.

Improvements to descriptions for device brightness

SUR-7478

In API calls related to device settings, information was added to brightness parameter to describe the screen brightness setting. Screen brightness for a device is set using a linear scale from 0 to 255.

Improvements to descriptions for the GET/audit-logs API call

SUR-7320

In GET/audit-logs API call, information was added to parameter descriptions to clarify which details of users and actions are recorded in the audit log.

Enable using the device as a hotspot by API

SUR-7308

Within the hotSpot object in device configuration API calls, a new parameter, hotspotEnabled, allows users to enable or disable the ability of the device to act as a mobile hotspot. This is available for AI-12 devices only.

Devices cannot downgrade firmware to before firmware version 3.12.25

SUR-7077

Due to enhanced security features deployed as part of firmware version 3.12.25, devices that have been upgraded to firmware versions higher than 3.12.25 cannot downgrade the firmware version to one that is lower than 3.12.25.

API service changes

This change may impact your use of the API service.

Different PIN numbers are necessary for driver and admin PINS

SUR-6715

The same PIN number cannot be assigned to both a driver and an admin PIN in an organization. Until now trying to configure the same PIN number was rejected and a 200 code was returned. Now, if the same PIN number is assigned to both a driver and an admin PIN, the operation fails, and an error code is returned.

This applies whether the request to assign the same number is made in one, or multiple API calls using the following API endpoints:

  • PUT /devices/{imei}/device-config
  • PUT /devices/device-config
  • POST /organizations/{orgId}/device-settings

Fixed items

Issue ID Issue summary Resolution
SUR-6736 Virtual events were created with media files from auxiliary cameras that were not connected, which resulted in missing media. A check was created to only use media files from connected.
SUR-6999 When a driver is assigned to a device via API, it was not recorded as an event. When a driver is assigned to a device via API, it is recorded as an event.
SUR-7159 In some cases, geofence events were configured as media events, even though they are text only.

In some cases, powerDisconnnectAlarm was configured for audio alerts, even though this is not supported.
The database was updated with valid configurations for geofence and powerDisconnnectAlarm.
SUR-7332 The response to the POST/devices/bulk-data-usage API call sometimes returned the information for the mobileTx parameter in the wrong format. The response to the POST/devices/bulk-data-usage API call returns the information for the mobileTx parameter in the correct format.
SUR-7344 Sending the POST /organizations/{orgId}/webhooks API call deletes configurations that are not updated with the call. This is by design for this POST API call. A new API call PATCH organizations/{orgId}/webhook-settings allows for partial updates to webhook configurations.
SUR-7411 In some cases, media was not available for virtual events from auxiliary camera media. A retry mechanism has been implemented with auxiliary cameras to maximize the chance of successful upload of event media.
SUR-7416 The React component to calibrate road-facing ADAS did not work on Apple. A deprecated library used by the component was replaced by an updated library, and the component is now functioning as expected.
SUR-7426 A partner user contact that was created via API could be created without an assigned access level, and could not be modified in the Partner Portal. In the POST /partners/{partnerId}/contacts API endpoint, a new paramater is available to assign access levels to a partner contact.
SUR-7432 In some cases, the audit log was missing records of a new user creation. New users are recorded in the audit log.
SUR-7454 In some cases, event videos were different lengths of time when retrieved from the in-cabin-facing lens and the road-facing lens. Event videos are the same amount of time when retrieved from the in-cabin-facing and the road-facing.
SUR-7506 In some cases virtual event snapshots were not available in the media file link that was sent. The media file is sent with the link for virtual events.
SUR-7598 In some cases, the API calls PUT /devices/{imei}/event-config and GET /devices/{imei}/event-config returned a 500 error. The API calls PUT /devices/{imei}/event-config and GET /devices/{imei}/event-config perform as expected.

Documentation updates

Document title Description of change Developer portal URL
Update device settings

Retrieve device settings

Bulk configure devices

Update default device settings

Updated parameters and documentation https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/putDeviceConfig/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceConfig/

https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/putBulkDeviceConfig/

https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/postOrganizationDeviceSettings/
Retrieve organization audit logs Improved parameter documentation. https://developer.surfsight.net/openapi/surfsight/operation/getAuditLogs/
Update device webhooks settings New API call for partial webhook configurations https://developer.surfsight.net/openapi/surfsight/operation/patchtOrganizationWebhook/
Create partner contact New parameter and description https://developer.surfsight.net/openapi/surfsight/operation/postPartnerContacts/

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.

C4 May 2024

New features and enhancements

New user without access to media

SUR-7176

A new user access level has been created to allow users to view information without access to media. This user level, Editor without media access, can be assigned in the Partner Portal.

New parameter for ADAS calibration status

SUR-6338

In the GET/device-health API call, the new parameter adasCalibrationCompleted returns the status of ADAS calibration for devices in an organization. Response 1 is for calibrated devices, and null is for non-calibrated devices.

Retrieve auxiliary camera connectivity status in health report

SUR-7223

The API call GET/device-health now returns auxiliary camera connectivity status information in a new object, auxiliaryCameras.

{
    "data": [
        {
            "imei": "Aragorn's car",
            "status": 1,
            "name": "357660101000198",
            "organizationId": 17,
            "partnerId": 1,
            "lastConnectedAt": "2024-04-16T11:12:25.422Z",
            "lastRecordingUpdatedAt": "2024-04-16T10:56:41.000Z",
            "lastRecordingHealth": true,
            "subscriptionId": null,
            "calibrationCompleted": true,
            "auxNum": null,
            "dataUsageReceivedAt": "2024-04-16T10:56:49.000Z",
            "lastSwitchedToRecordingUnhealthyAt": "2023-09-03T17:36:11.000Z",
            "auxiliaryCameras": [
                {
                    "id": 51,
                    "lastConnectedAt": "2024-04-16T10:58:05.000Z"
                },
                {
                    "id": 52,
                    "lastConnectedAt": "2024-04-16T09:42:51.000Z"
                }
            ],
            "sdCardFreeSpace": "12510240KB",
            "sdCardTotalSpace": "124821728KB",
            "adasCalibrationCompleted": false
        }
    ],
    "metadata": {
        "count": 1
    },
    "requestId": "28b13b4d-2423-4f4c-83f0-282eae3e9995"
}

Updates to API reference documentation to clarify webhook configurations

SUR-7074

Changes were made to the API reference documentation for the PUT/organizations/{orgId}/webhooks and POST/organizations/{orgId}/webhooks API calls, to clarify webhook configurations for specific webhook updates. For more information, see: Replace webhooks subscription devices and Add device to webhook subscription.

Partners can review all actions performed on their devices in the audit log

SUR-7151

Partners can retrieve information about all changes to their devices that are made through an API call or the Surfsight Portal. Until today partners only retrieved actions done with their own token, going forward partners can see actions by all users.

The API call GET/audit-logs has been updated to filter and return information for the following new parameters:

  • entity - ID of the entity that was changed
  • entityType - type of entity that was changed, whether a device, an organization, a partner, or a user
  • entityPartnerID - the partner the entity is associated with
  • entityOrganizationID - the organization the entity is associated with

Device configuration changes made in the Partner Portal are added to the audit log

SUR-7156

All device configuration changes performed in the Partner Portal are recorded to the audit log. These changes as well as the user who was logged in to the Partner Portal at the time of the changes are returned with the API call GET/audit-logs.

Audit log records user information for changes

SUR-7318

Partners can retrieve information about the user that performed changes recorded in the audit log. The API call GET/audit-logs now returns the userId for any action. Since the same userId can be assigned to a partner or user, a new parameter, userType, allows partners to filter the results based on the desired user type, whether partner or user.

Fixed items

Issue ID Issue summary Resolution
SUR-7263 laneWeaving and tailgating events were sometimes triggered even if the Advance Driver Assistance System (ADAS) wasn't calibrated. laneWeaving and tailgating events are not triggered unless the Advance Driver Assistance System (ADAS) is calibrated. Documentation about these events have been updated to state clearly that ADAS must be calibrated correctly to trigger these events.
SUR-7184 In some cases, event media for virtual events was not displayed and an error message was received. A retry mechanism has been implemented to maximize the chance of successful upload of event media.
SUR-6915 In the following API calls, requests using a partner token for the call require the organizationIdto be specified. However, this parameter wasn't listed in the documentation. The API calls are POST/drivers/devices, GET/driving-history, and DELETE/drivers/devices. The organizationId parameter is listed in the API documentation.

Documentation updates

Document title Description of change Developer portal URL
Retrieve health reports Updates to API call parameters. https://developer.surfsight.net/openapi/surfsight/operation/getDevicesHealth/
Replace webhooks subscription devices

Add device to webhook subscription
Updates to API call documentation. https://developer.surfsight.net/openapi/surfsight/operation/putOrganizationWebhooks/

https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook
Retrieve organization audit logs Updates to API call parameters and documentation. https://developer.surfsight.net/openapi/surfsight/operation/getAuditLogs/
Assign drivers to devices

Delete drivers

Retrieve driving history
The organizationId parameter was added for calls that use a partner token. https://developer.surfsight.net/openapi/surfsight/operation/associationDriversToDevices/

https://developer.surfsight.net/openapi/surfsight/operation/deleteDrivers/

https://developer.surfsight.net/openapi/surfsight/operation/getDrivingHistory/

C3 March 31, 2024

New features and enhancements

New API endpoint to retrieve WiFi password

SUR-7078

A new randomized Wifi password is automatically generated when a hotspot is enabled for the first time on a device. A new API call, POST /devices/wifi-password has been created to retrieve this password.

This increases security when auxiliary cameras are connected to the AI-12 dashcam. Only partners are able to use this call to retrieve the new password. Available only in devices with firmware version 3.12.202 or above.

Changes to the device billing status are recorded in the audit log

SUR-7126

Changes to the device billings status initiated in the Partner Portal are recorded in the audit log.

Device and event configuration changes to be added to the audit log

SUR-6991

Device and event configuration changes made through the Surfsight Portal are now available in the audit log, under the same user information used to log into the Surfsight Portal.

Group column added to the health report CSV attachment

SUR-6953

In the Devices Health area, when a health report is downloaded, there is a column listing the group a device is a associated with.

Event name added to the subject line of event and alert notification emails

SUR-6456

In event and alert notification emails, the type of event is now listed in the subject line of the email.

Fixed items

Issue ID Issue summary Resolution
SUR-7272 In some cases, Driver Check-In didn't check in drivers as expected. Driver Check-In checks in drivers as expected.
SUR-7096 Requests to create a virtual event video failed when a full ten second video was unavailable. When creating a virtual event, whatever part of the recording that is available for the virtual event is used for the virtual event video.
SUR-7087 In some cases, after deactivation, connected devices continued to record video and trigger virtual events. Only activated devices record video and trigger events.
SUR-7059 Some virtual events that request a video return a snapshot. Virtual events that request a video return a video.
SUR-5893 In some cases, event media for virtual events was not displayed and an error message was received. A retry mechanism has been implemented to maximize the chance of successful upload of event media.

Documentation updates

Document title Description of change Developer portal URL
New API endpoint New WiFi password endpoint POST /devices/wifi-password https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/postDeviceWifiPassword/

C2 March 2024

New features and enhancements

New API endpoints to set and retrieve device billing status

SUR-5993

Note

Changing the billing status may result in additional fees. For more information see an upcoming article about billing in the Developer Portal, or contact your partner success manager.

Users with partner level permission can set devices' billing status with the API calls PUT /devices/{imei}/billing-status/{billingStatus}for individual devices and PUT /devices/billing-status/{billingStatus} for devices in bulk.

To retrieve billing status information for individual devices or devices in an organization use the new API calls GET /devices/{imei}/billing-status or GET /organizations/{orgId}/devices/billing-status, respectively.

Partners can subscribe to the new system message webhook, deviceBillingStatus, for notification of billing status changes for each device.

Changes to billing statuses do not affect device data or a device's organization association.

Automated billing for auxiliary cameras and related updates by API call or webhook

SUR-6661

If a factory reset is performed from a device, the data profile configuration will be restored from the saved cloud configuration. Data usage itself will be reset and not sent again from the cloud.

New API endpoint to request all event file links in an array

SUR-6970

The new GET/devices/{imei}/event-file-links API call returns an array of media file links. Optional parameters include filetype to filter by video or snapshot, and cameraId. If cameraId is left blank all files are returned by default.

Copy
Copied
{
    "data": {
        "urls": [
            {
                "cameraId": 1,
                "url": "http://s3bucket.aws.com/abcdefg"
            },
            {
                "cameraId": 2,
                "error": "Requested file was either not found or uploaded yet"
            },
            {
                "cameraId": 52,
                "error": "Camera does not exist"
            }
        ]
    }
}

Deprecated endpoint DELETE /organization/{orgId} to be removed

SUR-6418

The API call DELETE /organization/{orgId} is being removed. The API call DELETE /organizations/{orgId} was previously added to the Developer Portal to replace it. Adding the s at the end of the organization keeps the call consistent with other Organizations API calls.

The DELETE /organization/{orgId} will be removed with the deployment on March 3, 2024. Users should use the DELETE /organizations/{orgId} API call to avoid problems with their integration.

This change may impact your use of the API service.

Documentation updated to reflect password requirements

SUR-6927

Password-related endpoint descriptions were updated to reflect validated password requirements which necessitate at least eight characters per password, including one upper-case letter, one lower-case letter, and one number. Possible characters include letters, numbers, and special characters. Updated endpoints are listed in the Documentation updates, below.

Audit log additions to help track configuration changes

The following bulk actions have been added to the audit log to keep track of details regarding each action. Single updates are already logged. For more information, see Audit logs.

  • Bulk updates
  • Factory reset
  • Device name change
  • Assign or remove a device from a sub-partner
  • Updated SD card recording retention time

Fixed items

Issue ID Issue summary Resolution
SUR-6133 The event type activated was listed in the enum and accepted in the following API calls PUT/devices/{imei}/event-config, PUT/devices/event-config, POST/organizations/{orgId}/event-settings, and POST/organizations/{orgId}/events. The event type activated is invalid and is no longer accepted in the following API calls: UT/devices/{imei}/event-config, PUT/devices/event-config, POST/organizations/{orgId}/event-settings, and POST/organizations/{orgId}/events. Using the event type activated returns an error message. The correct event type to use is deviceActivation.

These changes may impact your use of the API service.
SUR-7070 General distracted driver beeps were triggered instead of specific beep messages. Specific distracted driving beeps are triggered as applicable.

Documentation updates

Document title Description of change Developer portal URL
Authenticate users
Reset password
User-Initiated Password Change
Create user
Create partner contact
Updated password description https://developer.surfsight.net/openapi/surfsight/operation/postAuthenticate/
https://developer.surfsight.net/openapi/surfsight/operation/postResetPassword/
https://developer.surfsight.net/openapi/surfsight/operation/postChangePassword/
https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationUsers/
https://developer.surfsight.net/openapi/surfsight/operation/postPartnerContacts/
Webhooks Updated new webhook types for system message notifications https://developer.surfsight.net/developer-portal/webhooks/
Billing status New billing status article. https://developer.surfsight.net/developer-portal/billing-status/

C1 February 2024

New features and enhancements

Auxiliary camera information added to the GET /devices/{imei}/telemetry response

SUR-5931

Telemetry information has been added to the GET devices/{imei}/telemetry API response in the new auxCameras parameter. Information is retrieved for all connected auxiliary cameras. The following is an example of the telemetry response:

Copy
Copied
{
  "data": {
    "firmwareVersion": "3.9.53",
    "deviceModel": "AI-12",
    "lastSeenOnline": "2020-01-01T14:48:00.000Z",
    "simNetworkType": "4G",
    "simOperator": "Cellcom IL",
    "simState": "ready",
    "simNumber": "12345678",
    "calibrationCompleted": true,
    "sdCardInserted": true,
    "sdCardCapacityBytes": 127817449472,
    "sdCardFreeBytes": 46724284416,
    "adasCalibrationReady": true,
    "adasCalibrationCompleted": true,
    "wifiEnabled": true,
    "wifiConnected": true,
    "wifiSignalLevel": "-50",
    "auxCameras": [{"camera_id":52,"model":"C6F0SeZ3N0PcL2","fw_version":"V11.1.22.6.3-20200313","ip_address":"http://192.168.43.165","state":"connected","sd_status":"Ready","sd_free_space":"1866176 KB","sd_total_space":"62352448 KB"},{"camera_id":51,"model":"C6F0SeZ3N0PcL2","fw_version":"V11.1.22.6.3-20200313","ip_address":"http://192.168.43.69","state":"connected","sd_status":"Ready","sd_free_space":"3030112 KB","sd_total_space":"62352448 KB"}]
  }
}

New metadata parameters added to the GET /device-config API call response

SUR-6215

The parameters source, status, and time attributes have been added as metadata to the response of the GET /device-config API call.

  • The source parameter states whether the data was retrieved from the device, or if the data was taken from the cloud. If the device is offline, data is retrieved from the last configuration in cloud.
  • The status parameter states whether the device is online, offline, or in standby mode.
  • The time parameter states when the data was retrieved. If the device is online, the time listed is when the data is retrieved from the device. If the device is offline, the time listed is the last configuration in the cloud.
Copy
Copied
 },
  "metadata":{
    source:"cloud/device",
    status:"online/offline/standby",
    time: "2022-02-16T07:14:00.000Z // ISO format, in UTC
  }
}

Parameter added to the GET /organizations/{orgId}/webhooks API call to filter by IMEI number

SUR-6557

When requesting organization webhooks with the GET /organizations/{orgId}/webhooks API, partners can use the new optional parameter, imei, to filter by device IMEI number and retrieve only the webhooks for that device. If this parameter is not included in the API call, the response will include all devices, as usual.

New parameters added to the GET /device-health API call response

SUR-6765

The objects calibrationCompleted and auxNum are now returned in the response to theGET /device-health API call.

  • calibrationCompleted describes the acceleration calibration state with responses true for calibrated, and null, for not calibrated.
  • auxNum lists the number of connected auxiliary cameras. If no number is available the response is null.

Increased number of user contacts

SUR-5305

Partners can now create up to 100 users using thePOST /partners/{partnerId}/contacts API call.

Update to the description in the PUT /devices/{imei}/device-config API call

SUR-6799

The description for the recordingEncryption parameter in the PUT /devices/{imei}/device-config call has been updated to clarify the requirements for the recording encryption key.

Updated descriptions about media files for events created at the same time

SUR-6832

The following information was updated in introductory descriptions in several API calls:

If multiple events are generated with the same timestamp, to the second, and the same media type, the media file from the last request is used for all of them. To have different media files for each virtual event, use timestamps that differ by at least a second.

For a list of the updated API descriptions see the Documentation updates below.

New endpoint DELETE /organizations/{orgId} added to replace DELETE /organization/{orgId}

SUR-6885

The API call DELETE /organizations/{orgId} was added to the Developer Portal because the API call DELETE /organization/{orgId}, is being deprecated. The addition of the s at the end of organization keeps the call consistent with other Organizations API calls.

The DELETE /organization/{orgId} will be removed with the deployment on March 4, 2024. Users should use the DELETE /organizations/{orgId} API call to avoid problems with their integration.

Fixed items

Issue ID Issue summary Resolution
SUR-6852 In some cases, when creating a virtual event the webhook notification of a new event was retrieved before the response to the API call POST /devices/{imei}/virtual-event. Responses to POST /devices/{imei}/virtual-event API call, and virtual event webhooks are returned in a timely manner.
SUR-6845 The GPS data associated with some virtual events wasn't accurate and showed incorrect information in some snapshot overlays. The GPS data associated with virtual events is taken from the time of the event.

Documentation updates

Document title Description of change Developer portal URL
Create partner contact Updated documentation for increased number of user contacts. https://developer.surfsight.net/openapi/surfsight/operation/postPartnerContacts/
Delete organizations Added API call DELETE /organizations/{orgId} to replace DELETE /organization/{orgId} at the next sprint deployment. https://developer.surfsight.net/openapi/surfsight/operation/deleteOrganization/
Retrieve organization webhooks Added parameter to filter by IMEI. https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationWebhooks/
Retrieve health reports Added additional parameters. https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/getDevicesHealth/
Retrieve device telemetry data Added new telemetry parameters to sample response. https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/getDeviceTelemetry/
Retrieve event

Retrieve file link

Retrieve list of events

Retrieve organization events

Generate virtual event
Updated descriptions regarding media for events generated at the same time. https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvent/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEventFileLink/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvents/

https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationsEvents/

https://developer.surfsight.net/openapi/surfsight/operation/postVirtualEvent/
Update device settings Updated description of the recording encryption key. https://developer.surfsight.net/openapi/surfsight/operation/putDeviceConfig/

E23-24 January 2024

New features and enhancements

New option to request all media files, or multiple files, for an event with a single API call

SUR-6323

When retrieving media files from either the GET/devices/{imei}/event-file-link or GET/devices/{imei}/cameras/{cameraId}/snapshot API calls, users can now request all the media files, or multiple media files, associated with an event with one API call. Making a request with the parameter cameraId=0 requests files from all cameras, including both in-cabin-facing and road-facing lenses. The cameraIds parameter can be used to specify files from multiple lenses when the parameter cameraId==0.

Partners can choose to receive additional webhook notifications for alarm status

Partners can opt-in to receive additional webhook notifications for alarm status when they enable the subscribeForAlarmUpdates parameter in the following calls: POST/organizations/{orgId}/webhook-settings, POST/organizations/{orgId}/webhooks, and PUT/organizations/{orgId}/webhooks.

By default partners are opted out. When opted out, partners receive webhook notifications for alarm creation only. By opting in, partners receive additional alarm webhook notifications when alarms are closed as well.

New webhook notification for closed alarm status

SUR-6714

If partners have opted in to receive additional webhook notifications about alarm status, they receive additional information in the payload including that an alarm was closed.

When enabled, the GET/organizations/{orgId}/webhooks call returns the following additional information in the payload:

Copy
Copied
{
    "type": "alarms",
    "data": {
        "id": 26588,
        "imei": "357660102684628",
        "name": "357660102684628",
        "organizationId": 100021718,
        "organizationName": "Org&",
        "details": "",
        "alarmDefinitionCode": "133",
        "createdAt": "2023-12-24T11:03:03.000Z",
        "alarmDefinitionId": 1,
        "alarmDefinition": {
            "id": 1,
            "severity": 30,
            "hierarchy": 20,
            "code": "133",
            "name": "SD Card is not mounted, the camera is not recording video",
            "recommendation": "Reboot Camera, if the SD card is still not recognized, try formatting the SD card or replacing it",
            "createdAt": "2020-06-08T11:16:47.000Z"
        },
        "alarmStatus": 0,
        "userId": 1142,
        "userEmail": "joe@surfsight.com"
    }
}
  • alarmStatus=0 for created alarms and 1 for a closed alarm.
  • userId=0 for actions performed by the system, such as an opened alarm, or when an alarm is automatically closed. Auser_id is provided when an alarm is closed manually by a user.
  • userEmail is a string that contains the user email address, or is empty if the action was performed by the system.

New parameters to receive device counts for devices pending activation and locked

SUR-5772

When retrieving information from the GET/partners/operational-statistics call, partners can now retrieve device counts for the parameters pendingActivation and locked, in addition to activated and deactivated currently available. The count for deactivated devices is a combination of the devices that are pending activation and locked.

Webhook ID included in the response to POST/organizations/{orgId}/webhooks call

SUR-6556

When adding a device to a webhook subscription, webhookId is now included in the response to the POST/organizations/{orgId}/webhooks call.

Copy
Copied
{
    "webhookId": 217,
    "requestId": "df5fg-45fgfdsg-45fg-45454"
}

Fixed items

Issue ID Issue summary Resolution
SUR-6644 If two events are created with the same timestamp, in some cases, the mediaAvailability parameter returns incorrect information in the event webhook notification. Event webhook notifications give correct information for the mediaAvailability parameter.
SUR-6693 In some cases, the alarms shown in the Alarms Report, or returned through the API service, do not match those returned in the webhook notification. The alarms shown in the Alarms Report, or returned through the API service, match those returned in the webhook notification.
SUR-6718 An Organization with the same name as a pre-existing Organization could be created. An Organization cannot be created with the same name as a pre-existing Organization.

Documentation updates

Document title Description of change Developer portal URL
Webhooks

Update device webhooks settings

Add device to webhook subscription

Replace webhooks subscription devices
Updated Alarms information. https://developer.surfsight.net/developer-portal/webhooks/#webhooks

https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/postOrganizationWebhookSettings/

https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook/

https://developer.surfsight.net/openapi/surfsight/operation/putOrganizationWebhooks/
Download event media

Retrieve file link

Retrieve camera snapshot
Updated parameters and information. https://developer.surfsight.net/developer-portal/guides/events_guide/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEventFileLink/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceCameraSnapshot/
Retrieve partner operational statistics New parameters added. https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/getPartnerOperationalStatistics/
Add device to webhook subscription Response updated. https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook/

E21-22 December 2023

New features and enhancements

Lytx Conceal Service blurs images in media files

The Lytx Conceal Service blurs license plates, as well as faces of drivers, passengers, and passersby on event media files that are stored in the cloud. It is available through the API service only.

This cloud service is available through the optional parameter, conceal=true, in the API call GET/devices/{imei}/event-file-link. The feature can be applied to media that has been generated from all lenses, including the road- and in-cab facing lenses of the dash cam and auxiliary cameras.

As part of the initial release, the Lytx Conceal Service is available only for video clips and snapshots captured as triggered events. Lytx Conceal Service is available for reseller partners connected to the EU cloud.

The blurredMediaAvailability parameter has been added to responses to GET/devices/{imei}/events, GET/devices/{imei}/events/{eventId}, and POST/organizations/{orgId}/events API calls to determine if blurred media is available. Responses true and false indicate that the media is available or not available, respectively.

Furthermore, the new parameter, blurredMediaAvailable, has been added to the events webhook structure to notify partners when media is available for a new event. Responses true and false indicate that the media is available or not available, respectively.

Simulated Alarms capability

SUR-6652

New POST /devices/{imei}/alarm-simulator API call allows users to create simulated alarms. Users may perform all operations on this alarm, as if it was a regular system generated alarm. Metadata in the request can be used to explain what is being tested, and is automatically included as a comment.

Alarm details are available through the GET/alarms, and GET/alarms/{alarmId} API calls.

Clear error message when using invalid code for adminPin or driverPin

SUR-5917

When sending a PUT /device-config API call using 4121 as adminPin or driverPin, a new error message clearly states that this code is not valid in these cases, and to choose another code.

Apply organization profile to settings following firmware version update

SUR-6074

When a firmware version is updated in a device, a new workflow automatically applies the organization settings that are relevant to the new firmware version. This maintains device and event settings as configured prior to the firmware change and adds the supported organization settings for the new version. Updates are recorded in the audit log.

Opt out of the 'mediaAvailable' webhook

SUR-6559

Partners can choose to opt out of the mediaAvailable webhook notification. Opting out removes the mediaAvailable parameter from the Eventwebhook notification, and produces only one webhook per event.

Fixed items

Issue ID Issue summary Resolution
SUR-6104 Documentation for the POST/organizations/{orgId}/bulk-devices API call showed an incorrect response. Documentation for the POST/organizations/{orgId}/bulk-devices API call shows the correct response.
SUR-6430 Some parameters in the GET/device-health API call were not returning expected response. Parameters in the GET/device-health API call return the expected response.

Documentation updates

Document title Description of change Developer portal URL
Add simulated alarm New API reference for Simulated Alarms. https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/postSimulatedAlarm
Create a simulated alarm New use case guide to create Simulated Alarms. https://developer.surfsight.net/developer-portal/guides/create-simulated-alarm/
Alarms New reference document for Alarms. https://developer.surfsight.net/developer-portal/alarms-reference
Bulk add devices Response sample updated. https://developer.surfsight.net/openapi/surfsight/operation/postBulkDevices/
Retrieve file link Updated documentation to include new conceal parameter. https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEventFileLink/
How to use the Lytx Conceal Service API New user guide for Lytx conceal service API https://developer.surfsight.net/developer-portal/guides/conceal-service/
Retrieve organization events

Retrieve event

Retrieve list of events

Webhooks
Updated documentation to include new blurredMediaAvailable parameter. https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationsEvents/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvent/

https://developer.surfsight.net/openapi/surfsight/operation/getDeviceEvents/

https://developer.surfsight.net/developer-portal/webhooks/

E19-20 November 2023

New features and enhancements

Validation of dataType in event configurations

SUR-6292

The following events only allow text for data type, the dataType parameter none. Until now trying to configure the event to snapshot or video was ignored and did not return an error. From now on, the wrong dataType will result in an error code 400 and message.

This applies to the following events for the PUT /devices/event-config, PUT /devices/{imei}/event-config, and POST /organizations/{orgId}/event-settings API calls:

  • accOff
  • accOn
  • geoFence
  • speedLimit

These changes may impact your use of the API service.

Fixed items

Issue ID Issue summary Resolution
SUR-6575 Documentation about Possible Fatigue event was incorrect. Documentation for the Possible Fatigue event contains the correct description of the event.
SUR-6530 In some cases, virtual event requests returned an error message due to a problem with the start and end time calculations. Virtual events are created with the proper start and end time.
SUR-6520 Sometimes there was an extra webhook sent for the mediaAvailable message with the value true for both cameras. Only the necessary webhook status messages are sent out.
SUR-6477 In some cases, the number of GPS webhook notifications were reduced following a service disruption. GPS webhook notifications are received as expected.
SUR-6406 More video events were created than allowed in the data profile. Video events keep to the limit allowed in the data profile.
SUR-6267 In some cases, when a virtual event request was made with the POST /devices/{imei}/virtual-event call, the event wasn't created, but the video was saved to the cloud. When a virtual event request is sent, the event and corresponding video are created and saved to the cloud.
SUR-6223 In some cases, a virtual event request didn't save video from both the in-cabin-facing lens and the road-facing lens, as expected. The virtual event request saves all the recordings as expected.
SUR-6178 If the GET /devices/{imei}/cameras API call was sent while the camera was offline, an error code 500 was returned with an internal server error message. Now if the device is offline, the 417 error code will return with a message that the device is offline.

These changes may impact your use of the API service.
SUR-5811 Responses for the lastSeenOnline parameter were inconsistent across platforms. The responses for lastSeenOnline are consistent across platforms.

Documentation updates

Document title Description of change Developer portal URL
Retrieve events settings

Bulk configure events settings

Set events settings

Update default event settings
Update to possibleFatigue and drivingDuration descriptions https://developer.surfsight.net/openapi/surfsight/operation/getEventConfig/

https://developer.surfsight.net/openapi/surfsight/operation/putBulkEventConfig

https://developer.surfsight.net/openapi/surfsight/operation/putEventConfig/

https://developer.surfsight.net/developer-portal/surfsightapi/reference/operation/postOrganizationEventSettings/

E17-18 October 15, 2023

New features and enhancements

Retrieve mediaFileAvailability parameter in API calls requesting event information

SUR-6419

The mediaFileAvailability parameter has been added to responses to GET/devices/{imei}/events, GET/devices/{imei}/events/{eventId}, and POST/organizations/{orgId}/events API calls to determine if media is available. Responses True and False indicate that the media is available or not available, respectively.

Create a virtual event without media

SUR-6289

A new mediaType option, none has been added to the POST/devices/{imei}/virtual-event API call. Sending none in this parameter, creates the virtual event with no media.

Fixed items

Issue ID Issue summary Resolution
SUR-6374 In some cases, when a virtual event was created with the POST/devices/{imei}/virtual-event API call at the same time as other events, the virtual event did not return as requested. Virtual events are created as detailed in the request for the POST/devices/{imei}/virtual-event API call at all times.
SUR-6365 Documentation for parameters in the POST/devices/{imei}/virtual-event API call did not give information for video quality parameters. Additional information has been added to the POST/devices/{imei}/virtual-event documentation to clarify video quality information.
SUR-6364 In some cases, the response time for GET /device-config API call was 30 seconds or more. The response time for the GET /device-config API call has been shortened.
SUR-6308 The documentation for GET/device-health API call listed values that did not match those returned in the response to the API call. The documentation has been clarified to include a description of the values that are returned in the API call.
SUR-5854 In some cases the GET/devices/{imei}/device-config API call returned a response without values for some parameters. In the GET/devices/{imei}/device-config API call if there is no value for a parameter that parameter is not listed in the response.
Document title Description of change Developer portal URL
Generate virtual event Documentation updated to include more parameter information. https://developer.surfsight.net/openapi/surfsight/operation/postVirtualEvent/
Retrieve health reports Documentation updated to include values returned in the API. https://developer.surfsight.net/openapi/surfsight/operation/getDevicesHealth/

E15-16 October 1, 2023

New features and enhancements

Configure video and snapshot media for standbyEnter and standbyExit events.

SUR-6282

Video and snapshot data types can be configured for Entering standby and Exiting Standby events through the PUT/devices/{imei}/event-config, PUT/devices/event-config, and POST/organizations/{orgId}/event-settings API calls. The three options for dataType are none for text only notifications, video to record a video event, and snapshot to receive a snapshot of the event with timestamp. When a video event is selected, the recording for the standbyEnter event is recorded for ten seconds before the event, and the recording for the standbyExit event is recorded for ten seconds after the event.

New webhook type to receive system notifications.

The new webhook type, systemMessagesWebhook, has been added to the POST /organizations/{orgId}/webhook-settings call. This enables partners to be notified of two new messages:

SUR-5953

The message type dataProfileLimit sends a notification when a configurable data profile limit has been reached. The dataProfileLimit can be configured to send notification when the data usage is between 10% to 100% of the data profile limit. The default is 90%.

Supported data profile limits include: Total bandwidth, Live video minutes per month, Video events per day, Video events per month, and Recording video minutes per month.

If the configured limit is reached, a message is sent to the webhook URL to warn that the configured limit for that data profile has been reached.

SUR-6453

The message type deviceStatus sends a notification with each status change for a device. Updates are sent when a device status changes to offline, online, or standby modes.

The new webhook type is also available in the calls GET /organizations/{orgId}/webhooks, PUT /organizations/{orgId}/webhooks, and POST /organizations/{orgId}/webhooks.

Webhook message when media file is ready

SUR-6322

The new parameter, mediaAvailable, has been added to the events webhook structure to notify partners when media is available for a new event. Responses True and False indicate that the media is available or not available, respectively. If multiple files are involved, such as recordings from both road-facing and in-cabin lenses, or auxiliary cameras, a new message will be sent for each media file when it becomes available.

{
    "type": "event",
    "data": {
        "id": 7306791,
        "serialNumber": "357660101039543",
        "eventType": "cell_phone_use",
        "time": 1634797394,
        "lat": 32.1763837,
        "lon": 34.92067202,
        "alt": 54.01348876953125,
        "speed": 32.580000686645505,
        "other": "",
        "files": [
            {
                "cameraId": 1,
                "file": 1634797394,
                "fileType": "video", 
                "mediaAvailable":true
            },
            {
                "cameraId": 2,
                "file": 1634797394,
                "fileType": "video",
                "mediaAvailable":false
            }
        ]
    }
}

Posted speed data is available by webhook

SUR-6065

Three parameters, postedSpeed, postedSpeedHgv, and postedSpeedTrailer are now sent in the payload of the GPS webhook.

{
  "id": 284785715,
  "serialNumber": "357660101039543",
  "time": 1634716401,
  "lat": 32.16427726,
  "lon": 34.9046395,
  "alt": 64.57598876953125,
  "speed": 1.7200000286102295,
  "postedSpeed": 100,
  "postedSpeedHgv": 100,
  "postedSpeedTrailer": 100,
  "accuracy": 1.2160000801086426
}

More accurate error message for POST/devices/{imei}/virtual-event API call when a device is offline

SUR-6325

When sending POST/devices/{imei}/virtual-event API call, and the time requested is out of retention period, the error message returned states "The time parameter is out of range according to the retention period configured for the device organization.", even when the device is offline, rather than only stating the device is offline.

Fixed items

Issue ID Issue summary Resolution
SUR-6361 When requesting a list of trips with the GET/devices/{imei}/trips API call, some trips were inconsistent with the trips listed in the Surfsight Portal. Trips returned in the GET/devices/{imei}/trips call are consistent with the trips listed in the Surfsight Portal.
SUR-6175 The POST/organizations/{orgId}/events call did not return information with an organization token, it was only available for partner tokens. The POST/organizations/{orgId}/events call returns information with an organization or partner token.
SUR-6155 In rare cases, recordings were available outside the configured retention time. There are no recordings available outside the configured retention time.
SUR-5818 The health report, downloaded as a CSV file, included a column with unnecessary information. The health report, downloaded as a CSV file, only includes the necessary information.

Documentation updates

Document title Description of change Developer portal URL
Set events settings

Bulk configure events settings

Update default event settings

Retrieve events settings

Retrieve organization events
Updated dataType parameters for standbyEnter and standbyExit events https://developer.surfsight.net/openapi/surfsight/operation/putEventConfig/

https://developer.surfsight.net/openapi/surfsight/operation/putBulkEventConfig/

https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationEventSettings/#!path=events&t=request

https://developer.surfsight.net/openapi/surfsight/operation/getEventConfig/

https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationsEvents/
Webhooks Updated to add new webhook parameters. https://developer.surfsight.net/developer-portal/webhooks
Update device webhook settings

Add device to webhook subscription

Retrieve organization webhooks

Updated to add new webhook parameters. https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhookSettings/

https://developer.surfsight.net/openapi/surfsight/operation/postOrganizationWebhook/#!c=200&path=requestId&t=response

https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationWebhooks/

E13-14 August 2023

New features and enhancements

New endpoint to delete organizations from a partner account

SUR-4314

The new API call, DELETE /organization/{orgId}, allows partners to delete organizations they are not using from within their accounts. Only empty organization are able to be deleted.

Documentation updates

Document title Description of change Developer portal URL
Delete organization New endpoint to delete empty organizations. https://developer.surfsight.net/openapi/surfsight/operation/deleteOrganization/

E11-12 July 2023

New features and enhancements

Added validation to POST /virtual-event API call.

SUR-6198

Due to a new more stringent validation process, when using the POST / virtual-event API call, the service will verify that the requested event date is within the organization retention period. If the date is not within this time period, an error will be returned. The error code will be 400 and the error message will be: The time parameter is out of range according to the retention period configured for the device organization.

Set device data profile with new API endpoints

SUR-4658

New endpoints have been added to set device data profiles. Users can configure settings for a single device, in bulk and at the organization level. Only a partner token will be able to set the profile.

  • PUT /devices/{imei}/data-profile/{dataProfileId} to set the device data profile.
  • PUT /devices/data-profile/{dataProfileId} to set data profile for devices in bulk.
  • PUT /organizations/{orgId}/devices/data-profile/{dataProfileId} to sets the data profile for the organization's devices.
  • The parameter dataProfileID is available for retrieving information.

Add rejection reason to POST /organizations/{orgId}/bulk-devices responses

SUR-6105

When attempting to add a device through the POST /organizations/{orgId}/bulk-devices API call, if a device is rejected there are new responses to indicate the reason for the rejection. The following error messages have been added to the responses to POST /organizations/{orgId}/bulk-devices:

  • 1000 - Group not found;
  • 1001 - Device already assigned;
  • 1002 - IMEI not found;
  • 1003 - Device locked;
  • 1004 - Failure in ai-14 authorization.

Added organization actions to Audit log

SUR-5785

The following actions are added to the audit log to keep track of details regarding each action. For more information, see Audit logs.

  • Add organization
  • Update organization
  • Update organization settings
  • Update default device settings
  • Update default event settings
  • Update device webhook settings

Fixed items

Issue ID Issue summary Resolution
SUR-5062 If a user's email address was already added as a and then was added to an organization, no error message appeared. If a user is added as a partner or to an organization, if the same email address is added to one of these again, an error message is received.
SUR-6135 The response sample listed for the GET /organizations/{orgId} API call in the documentation was incorrect. The response sample for GET /organizations/{orgId} is inline with the actual response.
SUR-6142 When using the GET /organizations/{orgId} API call with a partner token the response includes ssoSecret field but this was not reflected in the documentation. Documentation for the GET /organizations/{orgId} reflects the correct response.
SUR-6155 In rare cases, recordings were available outside the configured retention time. There are no recordings available outside the configured retention time.
SUR-6182 For some devices, error 500 is returned from GET/devices/{imei}/device-config API call, when the device is offline. The GET /devices/{imei}/device-config API call returns a 200 code and device settings when device is offline.
SUR-6211 The documentation for the API call GET /organizations/{orgId}/webhooks did not include the webhook ID in the response. The documentation for API call GET /organizations/{orgId}/webhooks includes the webhook ID in the response.

Documentation updates

Document title Description of change Developer portal URL
Retrieve organization details Updated the response samples and documentation. https://developer.surfsight.net/openapi/surfsight/operation/getOrganization/
Bulk add devices Included updated codes. https://developer.surfsight.net/openapi/surfsight/operation/postBulkDevices/
Retrieve organization webhooks Updated response sample. https://developer.surfsight.net/openapi/surfsight/operation/getOrganizationWebhooks/

E9-10 June 2023

New features and enhancements

User IDs are added to all API calls in the audit log API

SUR-5307

Now a user ID will be associated with each API call in the audit log API.

The Recording streaming reusable component has new and enhanced functionality

SUR-5801

We have added new functionality to the recording streaming reusable component, making it more intuitive and easy to operate. Enhancements include:

  • New input allowing users to select a specific time on the timeline, similar to moving the cursor across the timeline. This is configurable using the new time-selection parameter.
  • Trips can be displayed on the timeline. This is configurable using the new trips parameter.
  • Events can now be displayed on the timeline. This is configurable using the new events parameter. Event visualizations include:

    • events displayed on the timeline according to the time they occurred;
    • events displayed with an icon configurable for color, icon, and name, using the new event-config-src parameter;
    • when hovering over the icon, it expands to show the name and timestamp;
    • clicking on the event opens the event media reusable component, if enabled using should-open-event parameter;
    • if there are multiple events and not enough room to display them all, the event will show an icon with a number of events. Clicking this icon opens a dropdown with all the event names and links.

For more information, see Recording timeline component.

Note

Due to a new more stringent validation process, when using the POST / virtual-event API call, the service will verify that the requested event date is within the organization retention period. If the date is not within this time period, an error will be returned. The error code will be 400 and the error message will be: The time parameter is out of range according to the retention period configured for the device organization.

These changes will be released in the next release, scheduled for July 23rd. If you have any questions, please contact your Technical Account Manager.

Fixed items

Issue ID Issue summary Resolution
SUR-6091 In some cases, when possibleFatigue events are disabled they are still triggered and returned as events. When the possibleFatigue event is disabled it is not triggered.
SUR-5979 Some MV+AI events have been duplicated with the same timestamp. MV+AI events are not duplicated.
SUR-5885 Some responses for the lastSeenOnline parameter from GET/organizations/{orgId}/devices are inconsistent. The parameter is returned all the time.
SUR-5711 When some files are downloaded via Retrieve, the normal and high quality recordings display different time stamps. Recordings downloaded on normal quality and high quality display the same time stamps.

Documentation updates

Document title Description of change Developer portal URL
Recording timeline component Documentation updated with new enhancements. https://developer.surfsight.net/developer-portal/components/component-recording-timeline/

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/

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:
{
"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"
        }
      }
    }
  }
}


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

Document title Description of change Developer portal URL
UI components Added all relevant documentation for using our new UI components, including specific details for the Live Video component https://developer.surfsight.net/developer-portal/components/reusable-intro/
React components Previously referred to as UI components, we've updated this section to React components to more accurately reflect usage https://developer.surfsight.net/developer-portal/components/calibrate-adas/
Calibrate road-facing ADAS Added permissions indication to user guide 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.