Manage devices

Use this section to add/update/delete new sites(devices).

Introduction

Data related to devices/sites is owned and managed by the device-service. The terms site and devices can be used interchangeably. A device can either represent a single device or a site depending on the use case. However hereafter only the term device will be used.

Querying devices

find all devices by companyId

GET https://talos-app.io/api/device-service/devices/search/findByCompanyId

Use this endpoint to find all devices by their company ID.

Query Parameters

Name	Type	Description
companyId	string	The company Id of your evalink talos account. Found at: https://talos-app.io/en/company-admin/integrations/api-tokens.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API Token.

200

{
    "_embedded": {
        "devices": [
            {
                "id": "8a81e9ad7541955f0175f970a6c67839",
                "companyId": "c32cdafb-2c69-4946-9f3d-a3944f8310a6",
                "evalinkDeviceId": "Escape Oddity.",
                "health": "UNKNOWN",
                "source": "TALOS",
                "sourceUrl": null,
                "idFromSource": null,
                "communicationProtocol": "EVALINK",
                "active": true,
                "activateDate": null,
                "activateAlarm": null,
                "deactivateDate": null,
                "deactivateAlarm": null,
                "testMode": false,
                "testModeFrom": null,
                "testModeUntil": null,
                "deviceGroupId": null,
                "deviceGroupName": null,
                "customerNumber": null,
                "customerCompany": null,
                "customerFirstName": null,
                "customerLastName": null,
                "customerPhone": null,
                "customerEmail": null,
                "customerZip": null,
                "customerCity": null,
                "customerStreet": null,
                "installerCompany": null,
                "installerFirstName": null,
                "installerLastName": null,
                "installerEmail": null,
                "installerPhone": null,
                "ignoreAlarmCodes": null,
                "rejectAlarmCodes": null,
                "attributes": [],
                "tags": []
            },
            {
                "id": "8a81bdba740ca2dd017410f31511010d",
                "companyId": "c32cdafb-2c69-4946-9f3d-a3944f8310a6",
                "evalinkDeviceId": "Spaces",
                "health": "EMPTY",
                "source": "TALOS",
                "sourceUrl": null,
                "idFromSource": null,
                "communicationProtocol": "EVALINK",
                "active": true,
                "activateDate": null,
                "activateAlarm": null,
                "deactivateDate": null,
                "deactivateAlarm": null,
                "testMode": false,
                "testModeFrom": null,
                "testModeUntil": null,
                "deviceGroupId": null,
                "deviceGroupName": null,
                "customerNumber": null,
                "customerCompany": "Sitasys AG",
                "customerFirstName": "Alice",
                "customerLastName": "Mazzone",
                "customerPhone": "[phone]",
                "customerEmail": "[e-mail]",
                "customerZip": "1204",
                "customerCity": "Geneva",
                "customerStreet": "Quai de l'Ile 13",
                "installerCompany": "Sitasys AG",
                "installerFirstName": "Lukas",
                "installerLastName": "Kaiser",
                "installerEmail": "[e-mail]",
                "installerPhone": "[phone]",
                "ignoreAlarmCodes": null,
                "rejectAlarmCodes": null,
                "attributes": [],
                "tags": []
            }
        ]
    }
}

find the device by groupId

GET https://talos-app.io/api/device-service/devices/search/findByDeviceGroupId?:deviceGroupId

Use this endpoint to find the device via the device group ID.

Query Parameters

Name	Type	Description
deviceGroupId	string	The relevant device group ID.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API Token.

200

{
  "_embedded": {
    "persistentEntityResources": [
      null
    ]
  },
  "_links": {}
}

list a specific device

GET https://talos-app.io/api/device-service/devices/:id

Use this endpoint to retrieve the data of a single specific device.

Path Parameters

Name	Type	Description
id	string	The required device ID.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API Token.

200

{
    "id": "8a81ed3874648ebc01746d8de7f20257",
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "evalinkDeviceId": "1000142",
    "health": "EMPTY",
    "source": "TALOS",
    "sourceUrl": null,
    "idFromSource": null,
    "communicationProtocol": "EVALINK",
    "active": true,
    "activateDate": null,
    "activateAlarm": null,
    "deactivateDate": null,
    "deactivateAlarm": null,
    "testMode": false,
    "testModeFrom": null,
    "testModeUntil": null,
    "deviceGroupId": null,
    "deviceGroupName": null,
    "customerNumber": null,
    "customerCompany": "Sitasys AG",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerPhone": "[phone]",
    "customerEmail": "[e-mail]",
    "customerZip": "4513",
    "customerCity": "Langendorf",
    "customerStreet": "Industriestrasse 6",
    "installerCompany": "Sitasys AG",
    "installerFirstName": "John",
    "installerLastName": "Doe",
    "installerEmail": "[e-mail]",
    "installerPhone": "[phone]",
    "ignoreAlarmCodes": "Motion",
    "rejectAlarmCodes": null,
    "attributes": [],
    "tags": []
}

403

{
    "error": "access_denied",
    "error_description": "Access is denied"
}

404

{
    "timestamp": 1606733683036,
    "status": 404,
    "error": "Not Found",
    "message": "Device 8a81ed3874648ebc01746d8de7f20258 not found",
    "path": "/devices/8a81ed3874648ebc01746d8de7f20258"
}

Create/Update/Delete Devices

create a device

POST https://talos-app.io/api/device-service/devices

Use this endpoint to create a new site (device).

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API-Token.

Request Body

Name	Type	Description
customerCountry	string	The country of the customer.
customerEmail	string	The email of the customer.
customerPhone	string	The phone number of the customer.
customerStreet	string	The street of the customer.
customerCity	string	The city of the customer.
customerZip	string	The zip code of the customer.
customerFirstName	string	The First Name of the customer.
customerLastName	string	The Last Name of the customer.
customerCompany	string	The customer's company name.
companyId	string	The Company ID, as it is displayed on the evalink talos Web Interface.
evalinkDeviceId	string	The evalink device ID, and it needs to be unique.

200

{
    "id": "8a81afab762e324c01764eb5863c21d0",
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "evalinkDeviceId": "customId",
    "health": "UNKNOWN",
    "source": "TALOS",
    "sourceUrl": null,
    "idFromSource": null,
    "communicationProtocol": null,
    "active": true,
    "activateDate": null,
    "activateAlarm": null,
    "deactivateDate": null,
    "deactivateAlarm": null,
    "testMode": false,
    "testModeFrom": null,
    "testModeUntil": null,
    "deviceGroupId": null,
    "deviceGroupName": null,
    "customerNumber": null,
    "customerCompany": "Sitasys AG",
    "customerCountry": "Switzerland",
    "customerFirstName": "Lukas",
    "customerLastName": "Kaiser",
    "customerPhone": "[phone]",
    "customerEmail": "[e-mail]",
    "customerZip": "4513",
    "customerCity": "Langendorf",
    "customerStreet": "Industriestrasse 6",
    "installerCompany": null,
    "installerFirstName": null,
    "installerLastName": null,
    "installerEmail": null,
    "installerPhone": null,
    "ignoreAlarmCodes": null,
    "rejectAlarmCodes": null,
    "attributes": [],
    "tags": []
}

Example:

{
    "id": null,
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "evalinkDeviceId": "customId",
    "active": true,
    "testMode": false,
    "customerCompany": "Sitasys AG",
    "customerFirstName": "Lukas",
    "customerLastName": "Kaiser",
    "customerPhone": "[phone]",
    "customerEmail": "[e-mail]",
    "customerZip": "4513",
    "customerCity": "Langendorf",
    "customerStreet": "Industriestrasse 6",
    "installerCompany": null,
    "installerFirstName": null,
    "installerLastName": null,
    "installerEmail": null,
    "installerPhone": null
}

update a device

PATCH https://talos-app.io/api/device-service/devices/:id

Use this endpoint to update a specific device.

Path Parameters

Name	Type	Description
id	string	The required device ID.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
  "activateAlarm": "string",
  "activateDate": 0,
  "active": true,
  "attributes": [
    {
      "name": "string",
      "public": true,
      "value": "string"
    }
  ],
  "companyId": "string",
  "customerCity": "string",
  "customerCompany": "string",
  "customerEmail": "string",
  "customerFirstName": "string",
  "customerLastName": "string",
  "customerNumber": "string",
  "customerPhone": "string",
  "customerStreet": "string",
  "customerZip": "string",
  "deactivateAlarm": "string",
  "deactivateDate": 0,
  "deviceGroupId": "string",
  "deviceGroupName": "string",
  "evalinkDeviceId": "string",
  "health": "EMPTY",
  "id": "string",
  "ignoreAlarmCodes": "string",
  "installerCompany": "string",
  "installerEmail": "string",
  "installerFirstName": "string",
  "installerLastName": "string",
  "installerPhone": "string",
  "links": {
    "empty": true
  },
  "rejectAlarmCodes": "string",
  "source": "EVALINK_LIVE",
  "tags": [
    {
      "assignedAt": 0,
      "assignedById": "string",
      "assignedByName": "string",
      "color": "string",
      "id": "string",
      "name": "string"
    }
  ],
  "testMode": true,
  "testModeFrom": 0,
  "testModeUntil": 0
}

delete a device

DELETE https://talos-app.io/api/device-servicse/devices/:id

Use this endpoint to permanently delete a single device.

Path Parameters

Name	Type	Description
id	string	The required device ID.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API-Token.

200

Site activation/deactivation

activate a device

POST https://talos-app.io/api/device-service/devices/{id}/activate

Use this endpoint to activate a device.

Path Parameters

Name	Type	Description
id	string	The Id of the device that you want to activate or deactivate.

Query Parameters

Name	Type	Description
subject	string	The subject of the new device.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200 Example Value:

{
    "id": "8a81afab762e324c01764eb5863c21d0",
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "evalinkDeviceId": "customId",
    "health": "UNKNOWN",
    "source": "TALOS",
    "sourceUrl": null,
    "idFromSource": null,
    "communicationProtocol": null,
    "active": true,
    "activateDate": null,
    "activateAlarm": null,
    "deactivateDate": null,
    "deactivateAlarm": null,
    "testMode": false,
    "testModeFrom": null,
    "testModeUntil": null,
    "deviceGroupId": null,
    "deviceGroupName": null,
    "customerNumber": null,
    "customerCompany": "Sitasys AG",
    "customerFirstName": "Lukas",
    "customerLastName": "Kaiser",
    "customerPhone": "[phone]",
    "customerEmail": "[e-mail]",
    "customerZip": "4513",
    "customerCity": "Langendorf",
    "customerStreet": "Industriestrasse 6",
    "installerCompany": null,
    "installerFirstName": null,
    "installerLastName": null,
    "installerEmail": null,
    "installerPhone": null,
    "ignoreAlarmCodes": null,
    "rejectAlarmCodes": null,
    "attributes": [],
    "tags": []
}

deactivate a device

POST https://talos-app.io/api/device-service/devices/{id}/deactivate

Use this endpoint to deactivate a device.

Path Parameters

Name	Type	Description
id	string	The ID of the device that we want to deactivate.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
    "id": "8a81afab762e324c01764eb5863c21d0",
    "companyId": "064646f3-18a2-4298-a28e-6e2883f27407",
    "evalinkDeviceId": "customId",
    "health": "UNKNOWN",
    "source": "TALOS",
    "sourceUrl": null,
    "idFromSource": null,
    "communicationProtocol": null,
    "active": false,
    "activateDate": null,
    "activateAlarm": null,
    "deactivateDate": null,
    "deactivateAlarm": null,
    "testMode": false,
    "testModeFrom": null,
    "testModeUntil": null,
    "deviceGroupId": null,
    "deviceGroupName": null,
    "customerNumber": null,
    "customerCompany": "Sitasys AG",
    "customerFirstName": "Lukas",
    "customerLastName": "Kaiser",
    "customerPhone": "[phone]",
    "customerEmail": "[e-mail]",
    "customerZip": "4513",
    "customerCity": "Langendorf",
    "customerStreet": "Industriestrasse 6",
    "installerCompany": null,
    "installerFirstName": null,
    "installerLastName": null,
    "installerEmail": null,
    "installerPhone": null,
    "ignoreAlarmCodes": null,
    "rejectAlarmCodes": null,
    "attributes": [],
    "tags": []
}

Site sharing

get share links

GET https://talos-app.io/api/device-service/devices/:deviceId/shareLinks

Use this endpoint to list the shared links.

Path Parameters

Name	Type	Description
id	string	The ID of the device you want to share.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
    "_embedded": {
        "deviceShareLinks": [
            {
                "id": "8a81fd00762e31a501764eb92d00XXXX",
                "token": "skffc5GSW17T6xtV81I4KPlwXXXXX",
                "password": null,
                "enabled": true,
                "createdAt": 1607638527232,
                "lastAccessed": null,
                "expiresAt": null,
                "description": "test",
                "shareCodeWords": false,
                "shareFiles": false,
                "shareAlarms": true,
                "shareEventLogs": false,
                "shareWorkflowTemplates": false,
                "shareContacts": false,
                "shareSchedules": false,
                "editContacts": false,
                "updateSchedules": false,
                "orderContactLists": false,
                "changeDeviceStatus": false,
                "changeDeviceTestMode": false
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/device-service/devices/8a81c66d76041f28017623e5db42XXXX/shareLinks"
        }
    }
}

create a shared link

POST https://talos-app.io/api/device-service/devices/:deviceId/shareLinks

It creates a new share link.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to create a shared link for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

under construction

Example:

Test mode

activate specific test mode

POST https://talos-app.io/device-service/devices/:deviceId/test-mode

Use this endpoint to activate specific test modes automatically.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to activate a test mode for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
testModeUntil	string	Ending moment of the test mode.
testModeFrom	string	Starting moment of the test mode.
testMode	string	testMode = true.
matchers	array	Find the example below.

200

"matchers": [
    {
      "field": "string",
      "invert": true,
      "matcherLogic": "AND",
      "operator": "string",
      "type": "string",
      "value": "string"
    }
  ]

Zones/users and partitions

get zones/users

GET https://talos-app.io/api/device-service/devices/:id/zones

Use this endpoint to get the zone and users linked to a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to the zone/users for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
    "_embedded": {
        "zones": [
            {
                "id": "8a81fd00762e31a501762e3f7d8b000b",
                "zoneId": "002",
                "zoneName": "John Doe",
                "zoneType": "USER"
            },
            {
                "id": "8a81fd00762e31a501762e3b5fca0009",
                "zoneId": "001",
                "zoneName": "Atrium",
                "zoneType": "ZONE"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/device-service/devices/8a81c66d76041f28017623e5db421ba9/zones"
        }
    }
}

write zones/users

POST https://talos-app.io/api/device-service/devices/:id/zones

Use this endpoint to write the zones and users of a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to write zones and users for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
zones	array	The collection of zone IDs.

200

{
  "id": "string",
  "links": {
    "empty": true
  },
  "zoneId": "string",
  "zoneName": "string",
  "zoneType": "USER"
}

{
        "zones": [
            {
                "zoneId": "002",
                "zoneName": "John Doe",
                "zoneType": "USER"
            },
            {
                "zoneId": "001",
                "zoneName": "Atrium",
                "zoneType": "ZONE"
            }
        ]
}

update zones/users

PATCH https://talos-app.io/api/device-service/devices/:id/zones

Use this endpoint to update the zones and users associated with a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to update the zones and users for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
zones	array	The collection of zone IDs.

200

{
        "zones": [
            {
                "zoneId": "002",
                "zoneName": "John Doe",
                "zoneType": "USER"
            },
            {
                "zoneId": "001",
                "zoneName": "Atrium",
                "zoneType": "ZONE"
            }
        ]
}

get partitions

GET https://talos-app.io/api/device-service/devices/:id/partitions

Use this endpoint to get the partition of a specific device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to get the partition for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
    "_embedded": {
        "partitions": [
            {
                "id": "8a81cd77762e321d01762e4380870007",
                "partitionId": "002",
                "partitionName": "Maintenance Floor"
            },
            {
                "id": "8a81cd77762e321d01762e4380870006",
                "partitionId": "001",
                "partitionName": "Department Store"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://talos-app.io/api/device-service/devices/8a81c66d76041f28017623e5db421ba9/partitions"
        }
    }
}

write partitions

POST https://talos-app.io/api/device-service/devices/:id/partitions

Use this endpoint to write the partitions of a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to write the partition for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
partitions	array	The ID of the partition.

200

{
        "partitions": [
            {
                "partitionId": "003",
                "partitionName": "Maintenance Floor"
            },
            {
                "partitionId": "004",
                "partitionName": "Department Store"
            }
        ]
}

update partitions

PATCH https://talos-app.io/api/device-service/devices/:id/partitions

Use this endpoint to update the partitions of a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to update the partition for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
partitions	array	The ID of the partition you want to update.

200

{
        "partitions": [
            {
                "partitionId": "003",
                "partitionName": "Maintenance Floor"
            },
            {
                "partitionId": "004",
                "partitionName": "Department Store"
            }
        ]
}

Tags

list tags

GET https://talos-app.io/api/device-service/devices/:deviceId/tag

Use this endpoint to list the tags associated with a device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to get the tags for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

200

{
  "_embedded": {
    "tags": [
      {
        "color": "string",
        "companyId": "string",
        "id": "string",
        "name": "string"
      }
    ]
  },
  "_links": {}
}

add tag

POST https://talos-app.io/api/device-service/devices/:deviceId/tag

Use this endpoint to add a tag to your device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to add tags to.

Headers

Name	Type	Description
Authentication	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
tagName	string	The name of the tag you want to add content to.
tagId	string	The ID of the tag you want to add content to.

200

remove tag

POST https://talos-app.io/api/device-service/devices/:deviceId/untag

Use this endpoint to remove the tag from your device.

Path Parameters

Name	Type	Description
deviceId	string	The ID of the device you want to remove a tag for.

Headers

Name	Type	Description
Authorization	string	Use 'Bearer' followed by your API token.

Request Body

Name	Type	Description
tagName	string	The name of the tag you want to remove.
tagId	string	The ID of the tag you want to remove.

200