Add single or multiple devices to an organization

Individual devices and groups can be consolidated within a single organization. Once you configure an organization and associate any devices or groups, you can then centrally manage those devices and groups at the organization level.

The rest of this guide shows you how to use the Surfsight API to add a new organization, following these steps:

  1. Authenticate yourself.
  2. Retrieve the organization ID.
  3. Add devices to the organization.
Note

For more information about the different API requests, take a look at our reference guide.

1. Authenticate yourself

Authenticate yourself before making any calls with the Surfsight API. For more details on authentication, see our authentication overview.

2. Retrieve the organization ID

Retrieve the organization ID with the GET /organizations call. If you already know the organization ID, skip this step.

Note

Only partners can make this call.

Copy
Copied
        curl --request GET https://api-prod.surfsight.net/v2/organizations
        --header 'Content-Type: application/json'
        --header 'Authorization: Bearer {token}'

The returned response contains information about your organizations, including the Id of each organization.

Copy
Copied
{
  "data": [
    {
      "name": "Amazing organization",
      "purgeDays": 90,
      "purgeDaysFrontCamera": 90,
      "purgeDaysRearCamera": 90,
      "purgeDaysAuxiliaryCameras": 90,
      "id": 17,
      "partnerId": 1,
      "alarmsCount": 7,
      "liveVideoTimeoutSeconds": 30
    }
  ]
}
Parameter Description Example
name The name of the organization. Amazing organization
purgeDays The amount of time that an organization's data is retained in the cloud before being purged, in days. The default general purge time is 31 days. 90
purgeDaysFrontCamera The amount of time that an organization's road-facing camera data is retained in the cloud before being purged, in days. The default general purge time is 31 days. 90
purgeDaysRearCamera The amount of time that an organization's in-cabin camera data is retained in the cloud before being purged, in days. The default general purge time is 31 days. 90
purgeDaysAuxiliaryCameras The amount of time that an organization's auxiliary camera data is retained in the cloud before being purged, in days. The default general purge time is 31 days. 90
id The ID of the organization. 17
partnerId The ID of the partner. 1
alarmsCount The number of unread alarms associated with the organization. 7
liveVideoTimeoutSeconds The amount of time that live video is streamed, in seconds. 30

3. Add devices to the organization

Add devices to your organizations:

  • for individual devices - with the POST /organizations/{orgId}/devices request

    Copy
    Copied
        curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/devices
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '{

        "imei": "357660101000198",
        "name": "Harry's car",
        "groupId": 32
    }'

  • for multiple devices at once - with the POST /organizations/{orgId}/bulk-devices request

    Copy
    Copied
        curl --request POST https://api-prod.surfsight.net/v2/organizations/{orgId}/bulk-devices
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer {token}'
    --data-raw '[

      {
        "imei": "357660101000198",
        "name": "Harry's car",
        "groupId": 32
      },
      {
        "imei": "357660101000276",
        "name": "Ginny's car",
        "groupId": 26
      }
    ]'
Parameter Description Required Example
orgId The ID of the organization. Yes 12
imei The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box. Yes 357660101000198
name The name assigned to the device. Yes Harry's car
groupId The ID of the group. Include this if you want to add a device to a group. Obtain this from GET /organizations/{orgId}/devices. No 32

A list of accepted and rejected devices by IMEI number is returned.

Copy
Copied
{
    "requestId": "5cc1680d-4508-45c2-b9a5-727eb12b6a40",
    "data": {
        "rejected": [],
        "accepted": [
            {
                "serialNumber": "357660101000198",
                "edgeId": 58146
            },
            {
                "serialNumber": "357660101000276",
                "edgeId": 58147
            }
        ]
    }
}
Parameter Description Example
serialNumber The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box. 357660101000198
edgeId The ID of the device used in v1 of the API. 58147