# Devices

Devices represent the physical devices that can be connected to the cloud. Adding devices requires access to a physical device unless that device is a cellular device. Adding devices is done through the use of Certificate Request Tokens, which are put into the device. Devices will use the Certificate Request Tokens to add themsevles to a cloud account associated with the token.

Cell devices can be added to an account beforehand in order to activate the device's sim card. Once the sim card is actiavated, the cell device can finish connecting using a Certificate Request Token.

# get devices info

Get a summary of device usage statistics for a given account with a break down of how many device seats are allocated to your account and child accounts, and which of those seats have devices that are connected and active.

# GET /v1/accounts/{AccountId}/devices/info

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device info

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/info" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "max":33,
    "used":3,
    "connected":1,
    "disconnected":2,
    "cell":1,
    "logRetentionID":2,
    "childAccountsCount":1,
    "childAccountsMax":56,
    "childAccountsUsed":2,
    "childAccountsConnected":1,
    "childAccountsDisconnected":1,
    "childAccountCell":0,
    "totalMax":89,
    "totalUsed":5,
    "totalConnected":2,
    "totalDisconnected":3,
    "totalCell":1
}

# get devices

Gets a comprehensive list of all devices in the account with AccountId and in all child accounts. Some fields are specific to cell compatible devices only and may be blank.

# GET /v1/accounts/{AccountId}/devices

# Parameters

Name	Type	Description
AccountId	int	id of account requesting devices

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices" \
-H "Authorization: Bearer {authToken}"

# Response

[{
    "account": {...},
    "device_id": 45612344,
    "account_id": 7852,
    "account_name": "foobarbaz",
    "serial_number": "00GKYN03A426",
    "modelNumber_id": 5,
    "revision": "0.000000",
    "connection_interval": 120,
    "name": "FooBar",
    "connected": 0,
    "last_connect": "2019-08-28 16:46:30",
    "last_disconnect": "2020-07-31 18:18:16",
    "created_at": "2019-08-11T16:57:53.000000Z",
    "updated_at": "2020-07-11T17:07:45.000000Z",
    "iccid": null,
    "air_vantage_uid": null,
    "activated": 0,
    "activation_operation_id": null,
    "model_number": {
        "id": 52,
        "model_number": "X-410",
        "link": "https:\/\/www.controlbyweb.com\/"
    },
}, {
    "account": {...},
    "device_id": 354563273,
    "account_id": 7852,
    "account_name": "FooBarBaz",
    "serial_number": "000DGDH010",
    "modelNumber_id": 57,
    "revision": "2.575300",
    "connection_interval": 1860,
    "name": "FooBars",
    "connected": 1,
    "last_connect": "2019-09-09 14:11:41",
    "last_disconnect": "2020-08-09 06:40:11",
    "created_at": "2019-08-11T17:04:32.000000Z",
    "updated_at": "2020-04-11T17:45:00.000000Z",
    "iccid": null,
    "air_vantage_uid": null,
    "activated": 0,
    "activation_operation_id": null,
    "model_number": {
        "id": 52,
        "model_number": "X-410",
        "link": "https:\/\/www.controlbyweb.com\/"
    },
}]

# get cell devices

Gets a comprehensive list of all cell compatible devices in the account with AccountId and in all child accounts.

# GET /v1/accounts/{AccountId}/devices/cell

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device cell

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/cell" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "9": {
        "account": {...},
        "account_name": "FooBarBaz"
        "device_id": 23356899,
        "account_id": 7852,
        "serial_number": "000ASDFA01F",
        "modelNumber_id": 52,
        "revision": "2.575700",
        "connection_interval": 1860,
        "name": "Foobar",
        "connected": 1,
        "last_connect": "2019-09-12 22:18:17",
        "last_disconnect": "2020-08-11 22:18:17",
        "created_at": "2019-08-12T18:11:18.000000Z",
        "updated_at": "2020-12-12T18:12:06.000000Z",
        "iccid": "89332123456789098759",
        "air_vantage_uid": "37e09f95bf634568251c0389cfa22b74",
        "activated": 1,
        "activation_operation_id": "",
        "model_number": {
            "id": 52,
            "model_number": "X-410",
            "link": "https:\/\/www.controlbyweb.com\/"
        },
    },
    "10": {
        "account": {...},
        "account_name": "FooBarBaz"
        "device_id": 2712358430,
        "account_id": 7852,
        "serial_number": "000CC815682401",
        "modelNumber_id": 52,
        "revision": "2.575600",
        "connection_interval": 1860,
        "name": "FooBars",
        "connected": 0,
        "last_connect": "2020-10-08 10:36:30",
        "last_disconnect": "2020-12-08 22:02:41",
        "created_at": "2020-03-03T16:14:28.000000Z",
        "updated_at": "2020-10-27T18:40:19.000000Z",
        "iccid": "893324013548268775",
        "air_vantage_uid": "c9fb48354864e378f5135g35s8b12f85",
        "activated": 1,
        "activation_operation_id": "",
        "model_number": {
            "id": 52,
            "model_number": "X-410",
            "link": "https:\/\/www.controlbyweb.com\/"
        },
    }
}

# activate cell device

This will activate the SIM card of the device with the DeviceId. This will also result in a the begining of the charge cycle for the purchased device data plan.

# GET /v1/accounts/{AccountId}/devices/{DeviceId}/activateCell

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/activateCell" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "message": "success"
}

# get cell device activation status

This will check the activation status of a SIM card in a given device with the DeviceId. activated = 0 mean the sim card is not activated. activated = 1 means the sim card has been activated. act_op_id = null means there is not an activation operation currently acitve. act_op_id != null means there is a current activation operation in process. Activation can take several minutes to complete.

# GET /v1/accounts/{AccountId}/devices/{DeviceId}/checkActiveStatus

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device status
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/checkActiveStatus" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "activated": 0, 
    "act_op_id": "123456"
}

# get cell device data usage

Gathers daily cell data usage for a device with the given DeviceId and formats it into an array.

# GET /v1/accounts/{AccountId}/devices/{DeviceId}/dataUsage/

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device data usage
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{deviceId/dataUsage" \
-H "Authorization: Bearer {authToken}"

# Response

{"37e12d95bf6121f9g71c03ceff29b74":{"DATA_ROUNDED_BYTES_TOTAL":[
    {"ts":1601475000000,"v":null},
    {"ts":1852447600000,"v":null},
    {"ts":1381251200000,"v":null},
    {"ts":1296518700000,"v":38742.0}
]}}

# get device data log

Gathers log data for a device with the given DeviceId and returns it as a .csv

# GET /v1/accounts/{AccountId}/devices/{DeviceId}/log

# Parameters

Name	Type	Description
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{deviceId/log" -H "Authorization: Bearer {authToken}"

# Response

,result,table,_start,_stop,_time,_value,_field,_measurement,customName,deviceID,units,valid
,_result,0,2020-06-15T07:19:00.946348357Z,2020-09-14T15:19:00.946348357Z,2020-08-12T19:47:00Z,24.7,value,vin,Vin,2365098699,V,1
,_result,0,2020-06-15T07:19:00.946348357Z,2020-09-14T15:19:00.946348357Z,2020-08-12T20:47:00Z,24.8,value,vin,Vin,2365098699,V,1
,_result,0,2020-06-15T07:19:00.946348357Z,2020-09-14T15:19:00.946348357Z,2020-08-12T21:47:00Z,24.7,value,vin,Vin,2365098699,V,1

# add cell device

Adds a cell device (cannot add non cell device) to the cloud, without connecting it. This allows for the SIM card to then be activated and allow for remote connection of the device afterwards. The serial_number and the cell_id must be a serial_number and cell_id of the same device. Cell devices do not take up a device seat but will generate their own seat when added.

# POST accounts/{AccountId}/devices

# Parameters

Name	Type	Description
AccountId	int	id of account to which you will add a device
cell_id	string	cell_id of the cell device to be added to the cloud
device_name	string	name of cell device to be added to the cloud
serial_number	string	serial number of the cell device to be added to the cloud

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices" \
-H "Authorization: Bearer {authToken}" \
-d "cell_id={cell_id}" \
-d "device_name={device_name}"
-d "serial_number={serial_number}"

# Response

{
    "message": "success",
    "device": {
        "account_id": 7852,
        "activated": 1,
        "activation_operation_id": "",
        "air_vantage_uid": "1347acb431880f551c6f5e535a159f5",
        "created_at": "2017-1-17T23:15:36.000000Z",
        "device_id": 26123456751,
        "device_seat_id": 3275,
        "iccid": "0094738567812763245",
        "modelNumber_id": 46,
        "name": "dev1",
        "serial_number": "000CC8000000",
        "updated_at": "2021-10-1T23:15:36.000000Z",
    }
}

# get device access link

Get a token for access to a devices webpages.

# POST /v1/accounts/{AccountId}/devices/AccessLink

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device accessLink
DeviceId	int	id of the device to be requested

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/AccessLink" \
-H "Authorization: Bearer {authToken}" \
-d "url=devices/{DeviceId}/index.html"

# Response

{
    "message": "success",
    "token": "n8IdAjg0hOqJZ19WumwW1IA2s1dfh51sdf9h156sdf51jt6575Hw8X34vUsu3RITLO3s1jd81k68t86asfe86rJuUe7tU7Ec"
}

# get device

Returns information about the device with DeviceId. Many fields may be blank if device is not a cell device.

# GET /v1/accounts/{AccountId}/devices/{DeviceId}

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}" \
-H "Authorization: Bearer {authToken}"

# Response

{   
    "device_id": 2712358430,
    "account_id": 7852,
    "serial_number": "000CC815682401",
    "modelNumber_id": 52,
    "revision": "2.575600",
    "connection_interval": 1860,
    "name": "FooBars",
    "connected": 0,
    "last_connect": "2020-10-08 10:36:30",
    "last_disconnect": "2020-12-08 22:02:41",
    "created_at": "2020-03-03T16:14:28.000000Z",
    "updated_at": "2020-10-27T18:40:19.000000Z",
    "iccid": "893324013548268775",
    "air_vantage_uid": "c9fb48354864e378f5135g35s8b12f85",
    "data_plan": "10MB",
    "activated": 1,
    "activation_operation_id": "",
    "model_number": {
        "id": 52,
        "model_number": "X-410",
        "link": "https:\/\/www.controlbyweb.com\/"
    },
    "tags": []
}

# update device

Manage and change settings of a device. Cannot change fields such as serial_number and cell_id.

# POST /v1/accounts/{AccountId}/devices/{DeviceId}

# Parameters

Name	Type	Description
AccountId	int	id of account updating device
DeviceId	int	id of the device to be requested
name	string	the new name of the device to be set to the device selected for edit
control_password	string	the new device control password to be set to the device selected for edit
setup_password	string	the new device setup password to be set to the device selected for edit

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}" \
-H "Authorization: Bearer {authToken}" \
-d "name={name}" \
-d "control_password={control_password}"
-d "setup_password={setup_password}"

# Response

{
    "message": "success"
}

# delete device

Deletes a device from the cloud and frees a device seat. This will result in the device being disconnected from the cloud. Cell devices will still be tied to an account by SIM card even after deletion for billing purposes.

# DELETE /v1/accounts/{AccountId}/devices/{DeviceId}

# Parameters

Name	Type	Description
AccountId	int	id of account deleting device
DeviceId	int	id of the device to be requested

# Example

curl -X DELETE "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "message": "success"
}

# get device access token

Gets a list of Device Access Tokens (DATs) for a device with DeviceId. Device Access Tokens can be used to generate URLs that directly access the web pages of a device. DATs have expiration timers, or can be created indefinitly. Example: https://controlbyweb.cloud/DAT/xxxyyyzzz/setup.html would access the setup.html page of a device with access token xxxyyyzzz.

# GET /v1/accounts/{AccountId}/devices/{DeviceId}/DAT

# Parameters

Name	Type	Description
AccountId	int	id of account requesting device DAT
DeviceId	int	id of the device to be requested

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/DAT" \
-H "Authorization: Bearer {authToken}"

# Response

[{
    "device_id": 281,
    "token": "wJ0ZP3K4WGW8lywCthF8noaPPbyz516D651dfykxgn3qPWhNkGS61df6h1d5Xn0t7TQqtkwCthF8noaPPbyzzbVsLMRvYDKzsYRm",
    "expires": null,
    "created_at": "2020-09-14T19:39:04.000000Z",
    "updated_at": "2020-09-14T19:39:04.000000Z"
}, {
    "device_id": 177,
    "token": "vK4WGW8lywCthF8lywCthF8no8noaPPbyzzblVEdPbyzzbVsLMRvYlykxgn3qPWhNkGS61BHDnLoaPPbyzzbVsLsdgdtTFu39D6v0",
    "expires": null,
    "created_at": "2020-09-15T14:43:37.000000Z",
    "updated_at": "2020-09-15T14:43:37.000000Z"
}]

# add device access token

Generates a Device Access Token (DAT) for the device with the specified DeviceId that is valid for the duration of time specified (set to 0 to never expire). The DAT can be used as many times as needed until it expires. You may only create up to three DATs for any given device.

# POST /v1/accounts/{AccountId}/devices/{DeviceId}/DAT

# Parameters

Name	Type	Description
AccountId	int	id of account adding device DAT
DeviceId	int	id of the device to be requested
minutesValid	int	minutes that the DAT should remain valid, 0 for infinite

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/DAT" \
-H "Authorization: Bearer {authToken}" \
-d "minutesValid={minutesValid}"

# Response

{
    "message": "success"
}

# update device access token

Edits a Device Access Token (DAT) from the device with the given DeviceId and that correlates to the specified DAT to update the amount of time it will stay valid.

# POST /v1/accounts/{AccountId}/devices/{DeviceId}/DAT/{DAT}

# Parameters

Name	Type	Description
authToken	string	Bearer auth Token recieved from call to get Token
AccountId	int	id of account updating device DAT
DeviceId	int	id of the device to be requested
DAT	string	DAT string that is to be deleted
minutesValid	int	minutes that the DAT should remain valid, 0 for infinite

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/DAT/{DAT}" \
-H "Authorization: Bearer {authToken}" \
-d "minutesValid={minValid}"

# Response

{
    "message": "success"
}

# delete device access token

Deletes a Device Access Token (DAT) from the device with the given DeviceId and that correlates to the specified DAT. The DAT will immediatly become unusable.

# DELETE /v1/accounts/{AccountId}/devices/{DeviceId}/DAT/{DAT}

# Parameters

Name	Type	Description
AccountId	int	id of account deleting device DAT
DeviceId	int	id of the device to be requested
DAT	string	DAT string that is to be deleted

# Example

curl -X DELETE "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/DAT/{DAT}" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "message": "success"
}

# use device seat token

Device Seat Tokens are used to increase the device seat capacity of an account. A device cannot be added unless there is an unoccupied device seat for it to occupy. Device Seat Tokens can be purchased at on our website at ControlByWeb.com.

# POST accounts/{AccountId}/deviceSeatTokens/{DeviceSeatToken}

# Parameters

Name	Type	Description
AccountId	int	id of account applying device seat code
DeviceSeatToken	string	token recieved from device seat order/purchase

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/deviceSeatTokens/{DeviceSeatToken}" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "message": "success"
}

# use data plan token

Data Plan Tokens are used to associate a data plan with a cellular device. A device SIM cannot be activated unless the device has a data plan. Data Plan Tokens can be purchase on our website at ControlByWeb.com.

# POST accounts/{AccountId}/devices/{DeviceId}/dataPlanTokens/{DataPlanToken}

# Parameters

Name	Type	Description
AccountId	int	id of account applying data plan code
DeviceId	int	id of the device to which you are applying the data plan
DataPlanToken	string	token recieved from data plan order/purchase

# Example

curl -X POST "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{DeviceId}/dataPlanTokens/{DataPlanToken}" \
-H "Authorization: Bearer {authToken}"

# Response

{
    "message": "success",
    "data_plan": "10MB"
}

# get device page

Accessing web pages from the device through the cloud. For example:

index.html,
setup.html,
state.json,
state.xml,
customState.json,
customState.xml,
etc

# GET accounts/{AccountId}/devices/{deviceid}/{info}

# Parameters

Name	Type	Description
AccountId	int	id of account associated with the device
DeviceId	int	id of the device containing the wanted page
info	string	page that is wanted from the device, defaults to "index.html" if not provided

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/accounts/{AccountId}/devices/{Id}/{Info?}" \
-H "Authorization: Bearer {authToken}"

# Response

RETURNS REQUESTED PAGE THAT YOU WOULD SEE IF YOU ACCESS IT DIRECTLY FROM THE DEVICE.

# get product list

Returns a list of all ControlByWeb.cloud compatible devices with ids, model numbers, and links to website resourses.

# GET products

# Parameters

Name	Type	Description
authToken	string	Bearer auth Token recieved from call to get Token

# Example

curl -X GET "https://api.controlbyweb.cloud/api/v1/products" \
-H "Authorization: Bearer {authToken}"

# Response

[{
    "id": 26,
    "model_number": "X-600M",
    "link": "http:\/\/www.controlbyweb.com\/x600m\/"
}, {
    "id": 36,
    "model_number": "XW-110",
    "link": "https:\/\/www.controlbyweb.com\/xw110\/"
}, {
    "id": 37,
    "model_number": "XW-111",
    "link": "https:\/\/www.controlbyweb.com\/xw111\/"
}, {
    "id": 42,
    "model_number": "XW-210I",
    "link": "https:\/\/www.controlbyweb.com\/XW-210\/"
}, {
    "id": 43,
    "model_number": "XW-110P",
    "link": "https:\/\/www.controlbyweb.com\/xw110\/"
}, {
    "id": 44,
    "model_number": "XW-111P",
    "link": "https:\/\/www.controlbyweb.com\/xw111\/"
}, {
    "id": 45,
    "model_number": "XW-112",
    "link": "https:\/\/www.controlbyweb.com\/xw112\/"
}, {
    "id": 46,
    "model_number": "X-410",
    "link": "https:\/\/www.controlbyweb.com\/x410"
}, {
    "id": 48,
    "model_number": "X-400",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 49,
    "model_number": "X-420",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 50,
    "model_number": "X-418",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 51,
    "model_number": "X-405",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 52,
    "model_number": "X-430",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 53,
    "model_number": "X-406",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 54,
    "model_number": "X-408",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 55,
    "model_number": "X-404",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 56,
    "model_number": "X-407",
    "link": "https:\/\/www.controlbyweb.com\/"
}, {
    "id": 62,
    "model_number": "X-401",
    "link": "https:\/\/www.controlbyweb.com\/"
}]

#

← Users Certificate Request Tokens →