Devices API (ENG)
INTRODUCTION
Devices API is used to register devices to the server and get device specific information/configurations from the server.
API PATH
/api/devices
It is recommended to use POST request.
API METHODS
REGISTER A DEVICE
REQUEST
Path
/api/devices/register
| Name | Value | Requirement | Info |
|---|---|---|---|
| version | string | Mandatory | Specifies a protocol version number. For example, "01" is a valid value. |
| udid | string | Mandatory | Specifies device unique identifier. |
| organizationId | string | Optional | Specifies organization identifier to add a new device. If organizationId is not defined, it is assumed the device is already registered. The response status will be an error, if the device is not registered. |
| macAddress | string | Optional | Specifies an active network interface MAC address, if available. |
| ipAddress | string | Optional | Specifies an active network interface IP address, if available. |
| serialNumber | string | Optional | Specifies a device serial number, if available. |
| userAgent | string | Optional | Overrides default client's user agent string, if needed. It should contain encoded string. |
RESPONSE
JSON response parameters (Success)
| Name | Info |
|---|---|
| status | request status code - "ok" |
| userOrganizationId | user identifier |
| contentOrganizationId | organization identifier to get video content |
| custom | custom code |
| active | Device status (0=inactive, 1=active) |
| activationDelay | Time(minutes) before client should request device activation (only present when device is inactive) |
| userId | ID of the User to whom this device is paired |
JSON response parameters (Error)
| Name | Info |
|---|---|
| status | request status code - "error" |
| message | request status message |
EXAMPLE
http://127.0.0.1/api/devices/register?udid=AA66FB6D8D93&version=01
{ "contentOrganizationId": 18809, "status": "ok", "userId": 0, "activationDelay": 0, "active": 0, "userOrganizationId": 18809, "master": false, "custom": "12345"} |
GET APPLICATION SCHEDULE FOR A DEVICE
REQUEST
Path
/api/devices/getSchedule
| Name | Value | Requirement | Info |
|---|---|---|---|
| version | string | Mandatory | Specifies a protocol version number. For example, "01" is a valid value. |
| udid | string | Optional | Specifies device unique identifier to select schedule events. DeviceGroupId should be defined, if this parameter is missing. |
| deviceGroupId | string | Mandatory | Specifies device group to select schedule events. Udid should be defined, if this parameter is missing. |
| startDate | string | Optional | Specifies schedule request start time UTC timestamp. Current time will be used, if this parameter is missing. |
| days | string | Optional | Specifies amount of days to select schedule events. Default value is 1 day. |
RESPONSE
JSON response parameters (Success)
| Name | Info |
|---|---|
| status | request status code - "ok" |
| message | JSON array that contains schedule events appUrl: schedule application url start/stop: start and stop event time (UTC milliseconds) startDuration/stopDuration: start and stop event time relative to the current time (in milliseconds). Negative value means the corresponding events is in the past. |
JSON response parameters (Error)
| Name | Info |
|---|---|
| status | request status code - "error" |
| message | request status message |
EXAMPLE
http://127.0.0.1/api/devices/getSchedule?organizationId=153116&version=01&udid=0015FD0117C7&days=2
{ "message": { "items": [ { "stop": 1420758000366, "startDuration": -38764003, "start": 1420686000366, "stopDuration": 33235997 }, { "stop": 1420844400366, "startDuration": 47635997, "start": 1420772400366, "stopDuration": 119635997 } ] }, "status": "ok"} |
CHECK SOFTWARE UPDATES FOR A DEVICE
REQUEST
Path
/api/devices/update
| Name | Value | Requirement | Info |
|---|---|---|---|
| version | string | Mandatory | Specifies a protocol version number. For example, "01" is a valid value. |
| udid | string | Mandatory | Specifies device unique identifier to check the updates. |
| organizationId | string | Mandatory | Specifies organization identifier to check firmware. |
| firmware | string | Mandatory | Specifies current firmware version of the device. |
| appVersion | string | Mandatory | Specifies current application version. |
| appName | string | Mandatory | Specifies the application name. |
RESPONSE
JSON response parameters (Success)
| Name | Info |
|---|---|
| status | request status code - "ok" |
| appName | Application name |
| url | New application package url |
| appVersion | New application version |
JSON response parameters (Error)
| Name | Info |
|---|---|
| status | request status code - "error" |
| message | request status message |
EXAMPLE
ACTIVATE A DEVICE
REQUEST
Path
/api/devices/activate
| Name | Value | Requirement | Info |
|---|---|---|---|
| version | string | Mandatory | Specifies a protocol version number. For example, "01" is a valid value. |
| udid | string | Mandatory | Specifies device unique identifier of the device to activate. |
| organizationId | string | Mandatory | Specifies organization identifier to validate the call. |
RESPONSE
JSON response parameters (Success)
| Name | Info |
|---|---|
| status | request status code - "ok" |
JSON response parameters (Error)
| Name | Info |
|---|---|
| status | request status code - "error" |
| message | request status message |
EXAMPLE
http://127.0.0.1/api/devices/activate?udid=140800160002&version=01&organizationId=13509
{ "status":"ok"} |
PAIR DEVICE WITH A USER
REQUEST
Path
/api/devices/pair
| Name | Value | Requirement | Info |
|---|---|---|---|
| version | string | Mandatory | Specifies a protocol version number. For example, "01" is a valid value. |
| udid | string | Mandatory | Specifies device unique identifier of the device to activate. |
| userId | string | Mandatory | The userId to pair the device with |
| organizationId | string | Mandatory | Specifies organization identifier to validate the call. |
RESPONSE
JSON response parameters (Success)
| Name | Info |
|---|---|
| status | request status code - "ok" |
JSON response parameters (Error)
| Name | Info |
|---|---|
| status | request status code - "error" |
| message | request status message |
EXAMPLE
http://127.0.0.1/api/pair/activate?udid=140800160002&version=01&userId=12345&organizationId=13509
{ "status":"ok"} |
Related Articles
Archive API (ENG)
INTRODUCTION This API is used to manage the content within the Archive, actions like add asset, edit asset and delete asset. All calls must be made by supplying the unique token for your organization. API PATH /api/archive API CALLS ADD ASSET V.2 ...EPG API (ENG)
INTRODUCTION EPG API is used to get the TV program information (EPG data) for linear channels. Note See also Channels API for additional documentation API PATH /api/channels API METHODS GET EPG EVENTS REQUEST Parameters: Requirement Name Description ...Publishing API (ENG)
INTRODUCTION This API is used to query for media assets that are published. The API includes various calls for getting data for published assets in your account. API PATH /api/publishing/ API: VERSION 05 GET ASSETS REQUEST ...Channels API (ENG)
INTRODUCTION Channels API is used to get Linear Channels related metadata from Icareus Suite. API PATH /api/channels/ All API calls are done as GET calls API METHODS GET CHANNELS Name Requirement Description Values action Mandatory Action call to ...Sales, Devices and Vouchers Reports
REPORTS INTRODUCTION AND MAIN FEATURES 1. INTRODUCTION Reports are the core parts running a working and developing video service. Icareus Suite platform tracks both the usage of the videos, channels and sales of your service. In addition, Icareus ...