Events API (ENG)

Events API (ENG)

Introduction

This API is used query Events

API PATH

/api/events

GET UPCOMING EVENTS

This API returns a list of events from the specified time-range.

Parameters:
Name
Type
Requirement
Description
action
String
Mandatory
Specifies the action for the API call.
token
String
Mandatory
Generated token needed to access the API, see information on how to generate a token below.
organizationId
Number
Mandatory
Suite Organization ID
languageId
String
Mandatory
Specifies the language identifier used when fetching Event information. Defaults to 'en_US' if not provided.
from
Number
Mandatory
Beginning date to fetch events from. Time in milliseconds from the UNIX Epoch.
to
Number
Mandatory
End date to fetch events until. Time in milliseconds from the UNIX Epoch.
filter
String
Optional
Supported value: 'eventcode'. If provided, the API will only list Events that have an event code linked to them.
eventCode
String
Optional
If provided, the API will only return the Event(s) that has the specified event code linked to it.

Token generation
A token consists of 42 character long hex value. The value has two different parts:
  1. Version [8 bits / 2 chars] - current version
  2. Current time [32 bits / 8 chars] - current timestamp in number of seconds since UNIX Epoch
  3. Signature [128 bits / 32 chars] - the MD5 hash of (organizationId + ":" + from + ":" + to + ":" + languageId + ":" + Current time + ":" + Secret), where '+' is a string concatenation
Secret: A secret key that is only present on the client creating the token and the server verifying the token that is Organization specific.
Example:
Version: "01"
organizationId: 13509
from: 1617224400000
to: 1619816399000
languageId: 'en_US'
Current time: 1622091600000 (27.05.2021 05:00:00 UTC) -> '60af2750'
Secret: 'secret'
Signature: MD5('13509:1617224400000:1619816399000:en_US:60af2750:secret') -> '8477d4aeee1c7589f7a94b28a936466e'
Generated token: '0160af27508477d4aeee1c7589f7a94b28a936466e'
(note: the above URL is using example values and thus does not actually work)

An invalid call to this API will always result in a JSON response with the following structure (Note that the HTTP status code of the response is still 200):
  1. {
  2. "status": "error",
  3. "message": "reason for error"
  4. }
And the following is a sample of a successful API call:
  1. {
        "status": "ok",
        "events": [
            {
                "endTimePublicMs": 0,
                "largeImageId": "",
                "recordings": [
                    {
                        "assetId": 1002628,
                        "publishEndMs": 1598523804000,
                        "publishStartMs": 1558555201000,
                        "publishStart": "Wed May 22 20:00:01 GMT 2019",
                        "publishEnd": "Thu Aug 27 10:23:24 GMT 2020"
                    }
                ],
                "durationPublic": 0,
                "smallImageId": "",
                "type": 5,
                "endTime": "Thu May 23 00:47:43 GMT 2019",
                "startTime": "Wed May 22 20:00:00 GMT 2019",
                "mediumImageId": "",
                "startTimeMs": 1558555200847,
                "duration": 17263,
                "startTimePublicMs": 0,
                "eventId": 1002632,
                "serviceId": 56810,
                "endTimeMs": 1558572463847,
                "description": "",
                "publicName": "Test Event",
                "defaultEmbedUrl": "https://suiterc.icareus.com/web/tvanywhere-demo/player/embed/event/view?eventId=1002632%22,
                "name": "Test Event",
                "eventCode": "event-code"
            }
        ],
        "organizationId": 13509
    }


Get Events

Path:
/api/events

Query Parameters

Name
Type
Requirement
Description
organizationId
Number
Mandatory
Suite Organization ID
action
String
Mandatory
Value should be: getEvents
version
String
Mandatory
Value should be: 02
from
Number
Optional
Time in milliseconds since the UNIX Epoch. Only events that have a start time after this date will be returned.
to
Number
Optional
Time in milliseconds since the UNIX Epoch. Only events that have a start time before this date will be returned.
categoryIds
String
Optional
Comma separated list of Event Category IDs, only events from provided categories will be returned.
includeSubCategories   
Boolean
Optional
If 'true' and a list of category IDs is provided with the 'categoryIds' parameter, events from the specified categories' sub-categories will also be returned.
getSubOrganizationEvents
Boolean
Optional
If True, the API will return events from the specified organization's sub-organizations as well.
begin
Number
Optional
Limits the number of results fetched. For example if 'begin=0' and 'end=1' only the first result from the resultset is returned.
end
Number
Optional
Limites the number of results fetched. For example if 'begin=0' and 'end=1' only the first result from the resultset is returned.


Success Response

HTTP Status Code: 200
A successful response will always be a JSON object that contains the key "status": "ok
Successful response will contain a JSON object that includes an "events" array.
NOTE: Data in the below example JSON might not be valid at the time you're reading this. This is just indicative of the format of the JSON object.
  1. {
  2.   "status": "ok",
  3.   "events": [
  4.     {
  5.       "isMultiroom": true,
  6.       "embedUrl": "https://events.icareus.com/player/embed/event/view?eventId=3412901",
  7.       "defaultLanguage": "en_US",
  8.       "thumbnailImage": "https://suiterc.icareus.com/image/image_gallery?img_id=3412903",
  9.       "startTime": 1631178000000,
  10.       "eventTheme": 0,
  11.       "duration": 18000,
  12.       "eventLanguages": [
  13.         "en_US",
  14.         "sv_SE"
  15.       ],
  16.       "eventId": 3412901,
  17.       "serviceId": 0,
  18.       "publicName": {
  19.         "en_US": "Test Event 2 Eng Public",
  20.         "sv_SE": "Test Event 2 Swe Public"
  21.       },
  22.       "description": {
  23.         "en_US": "<p>Test Event 2 Eng</p>\n",
  24.         "sv_SE": "<p>Test Event 2 Swe</p>"
  25.       },
  26.       "name": {
  27.         "en_US": "Test Event 2 Eng",
  28.         "sv_SE": "Test Event 2 Swe"
  29.       },
  30.       "gdpr": {
  31.         "privacyPolicy": {
  32.           "en_US": "<p><br />\nPrivacy policy</p>"
  33.         },
  34.         "copyright": {
  35.           "en_US": "Copyright"
  36.         },
  37.         "termsOfService": {
  38.           "en_US": "<p>Terms of service</p>"
  39.         }
  40.       },
  41.       "categories": [
  42.         {
  43.           "name": "Category 2",
  44.           "categoryId": 3430801,
  45.           "sortNumber": 1
  46.         }
  47.       ],
  48.       "rooms": [
  49.         {
  50.           "service_id": 3410406,
  51.           "duration": 18000,
  52.           "event_theme": 3410802,
  53.           "thumbnail_image": "https://suiterc.icareus.com/image/image_gallery?img_id=3413006",
  54.           "description": {
  55.             "en_US": "<p>Test Event 2 Room 2 Eng</p>"
  56.           },
  57.           "embed_url": "https://events.icareus.com/player/embed/event/view?eventId=3412901&roomId=3413004",
  58.           "name": {
  59.             "en_US": "Test Event 2 Room 2 Eng"
  60.           },
  61.           "start_time": 1631178000000,
  62.           "public_name": {
  63.             "en_US": "Test Event 2 Room 2 Eng Public"
  64.           },
  65.           "room_id": 3413004
  66.         },
  67.         {
  68.           "service_id": 3410350,
  69.           "duration": 18000,
  70.           "event_theme": 3410801,
  71.           "thumbnail_image": "https://suiterc.icareus.com/image/image_gallery?img_id=3413002",
  72.           "description": {
  73.             "en_US": "<p>Test Event 2 Room 1 Eng</p>\n",
  74.             "sv_SE": "<p>Test Event 2 Room 1 Swe</p>"
  75.           },
  76.           "embed_url": "https://events.icareus.com/player/embed/event/view?eventId=3412901&roomId=3412905",
  77.           "name": {
  78.             "en_US": "Test Event 2 Room 1 Eng",
  79.             "sv_SE": "Test Event 2 Room 1 Swe"
  80.           },
  81.           "start_time": 1631178000000,
  82.           "public_name": {
  83.             "en_US": "Test Event 2 Room 1 Eng Public",
  84.             "sv_SE": "Test Event 2 Room 1 Swe Public"
  85.           },
  86.           "room_id": 3412905
  87.         }
  88.       ]
  89.     }
  90.   ]
  91. }

Error Response

HTTP Status Code: 200
Error response will contain a JSON object where "status" is set to "error".
  1. {
  2.     "status": "error",
  3.     "message": "some information about what went wrong"
  4. }


Get Event

Path:
/api/events

Query Parameters

Name
Type
Requirement
Description
organizationId
Number
Mandatory
Suite Organization ID
action
String
Mandatory
Value should be: getEvent
eventId
Number
Mandatory
ID of the Event to fetch

Success Response

HTTP Status Code: 200
A successful response will always be a JSON object that contains the key "status": "ok
Successful response will contain a JSON object that includes an "event" object.
  1. {
  2.     "status": "ok",
  3.     "event": {
  4.         "isMultiroom": true,
  5.         "embedUrl": "https://events.icareus.com/player/embed/event/view?eventId=3412901",
  6.         "defaultLanguage": "en_US",
  7.         "thumbnailImage": "https://suiterc.icareus.com/image/image_gallery?img_id=3412903",
  8.         "startTime": 1631178000000,
  9.         "eventTheme": 0,
  10.         "duration": 18000,
  11.         "eventLanguages": [
  12.             "en_US",
  13.             "sv_SE"
  14.         ],
  15.         "eventId": 3412901,
  16.         "serviceId": 0,
  17.         "publicName": {
  18.             "en_US": "Test Event 2 Eng Public",
  19.             "sv_SE": "Test Event 2 Swe Public"
  20.         },
  21.         "description": {
  22.             "en_US": "<p>Test Event 2 Eng</p>\n",
  23.             "sv_SE": "<p>Test Event 2 Swe</p>"
  24.         },
  25.         "name": {
  26.             "en_US": "Test Event 2 Eng",
  27.             "sv_SE": "Test Event 2 Swe"
  28.         },
  29.         "gdpr": {
  30.             "privacyPolicy": {
  31.                 "en_US": "<p><br />\nPrivacy policy</p>"
  32.             },
  33.             "copyright": {
  34.                 "en_US": "Copyright"
  35.             },
  36.             "termsOfService": {
  37.                 "en_US": "<p>Terms of service</p>"
  38.             }
  39.         },
  40.         "categories": [
  41.             {
  42.                 "name": "Category 2",
  43.                 "categoryId": 3430801,
  44.                 "sortNumber": 1
  45.             }
  46.         ],
  47.         "rooms": [
  48.             {
  49.                 "service_id": 3410406,
  50.                 "duration": 18000,
  51.                 "event_theme": 3410802,
  52.                 "thumbnail_image": "https://suiterc.icareus.com/image/image_gallery?img_id=3413006",
  53.                 "description": {
  54.                     "en_US": "<p>Test Event 2 Room 2 Eng</p>"
  55.                 },
  56.                 "embed_url": "https://events.icareus.com/player/embed/event/view?eventId=3412901&roomId=3413004",
  57.                 "name": {
  58.                     "en_US": "Test Event 2 Room 2 Eng"
  59.                 },
  60.                 "start_time": 1631178000000,
  61.                 "public_name": {
  62.                     "en_US": "Test Event 2 Room 2 Eng Public"
  63.                 },
  64.                 "room_id": 3413004
  65.             },
  66.             {
  67.                 "service_id": 3410350,
  68.                 "duration": 18000,
  69.                 "event_theme": 3410801,
  70.                 "thumbnail_image": "https://suiterc.icareus.com/image/image_gallery?img_id=3413002",
  71.                 "description": {
  72.                     "en_US": "<p>Test Event 2 Room 1 Eng</p>\n",
  73.                     "sv_SE": "<p>Test Event 2 Room 1 Swe</p>"
  74.                 },
  75.                 "embed_url": "https://events.icareus.com/player/embed/event/view?eventId=3412901&roomId=3412905",
  76.                 "name": {
  77.                     "en_US": "Test Event 2 Room 1 Eng",
  78.                     "sv_SE": "Test Event 2 Room 1 Swe"
  79.                 },
  80.                 "start_time": 1631178000000,
  81.                 "public_name": {
  82.                     "en_US": "Test Event 2 Room 1 Eng Public",
  83.                     "sv_SE": "Test Event 2 Room 1 Swe Public"
  84.                 },
  85.                 "room_id": 3412905
  86.             }
  87.         ]
  88.     }
  89. }

Error Response

HTTP Status Code: 200
Error response will contain a JSON object where "status" is set to "error".
  1. {
  2.     "status": "error",
  3.     "message": "some information about what went wrong"
  4. }

Get Event Categories

Path:
/api/events

Query Parameters


Name
Type
Requirement
Description
organizationId
Number
Mandatory
Suite Organization ID
action
String
Mandatory
Value should be: getCategories

Success Response

HTTP Status Code: 200
A successful response will always be a JSON object that contains the key "status": "ok
Successful response will contain a JSON object that includes an "categories" array.
  1. {
  2.   "status": "ok",
  3.   "categories": [
  4.     {
  5.       "subCategories": [
  6.         {
  7.           "subCategories": [
  8.             {
  9.               "subCategories": [],
  10.               "name": "Cat 1 Sub 1 Sub 1",
  11.               "categoryId": 3430706,
  12.               "sortNumber": 0
  13.             }
  14.           ],
  15.           "name": "Cat 1 Sub 1",
  16.           "categoryId": 3430704,
  17.           "sortNumber": 0
  18.         },
  19.         {
  20.           "subCategories": [],
  21.           "name": "Cat 1 Sub 2",
  22.           "categoryId": 3430705,
  23.           "sortNumber": 1
  24.         }
  25.       ],
  26.       "name": "Category 1",
  27.       "categoryId": 3430703,
  28.       "sortNumber": 0
  29.     },
  30.     {
  31.       "subCategories": [],
  32.       "name": "Category 2",
  33.       "categoryId": 3430801,
  34.       "sortNumber": 1
  35.     }
  36.   ]
  37. }

Error Response

HTTP Status Code: 200
Error response will contain a JSON object where "status" is set to "error".
  1. {
  2.     "status": "error",
  3.     "message": "some information about what went wrong"
  4. }

Get Event Category

Path:
/api/events

Query Parameters

Name
Type
Requirement
Description
organizationId
Number
Mandatory
Suite Organization ID
action
String
Mandatory
Value should be: getCategory
categoryId
Number
Mandatory
ID of the Category to fetch

Success Response

HTTP Status Code: 200
A successful response will always be a JSON object that contains the key "status": "ok
Successful response will contain a JSON object that includes a "category" array object.
  1. {
  2.     "category": {
  3.         "subCategories": [
  4.             {
  5.                 "subCategories": [
  6.                     {
  7.                         "subCategories": [],
  8.                         "name": "Cat 1 Sub 1 Sub 1",
  9.                         "categoryId": 3430706,
  10.                         "sortNumber": 0
  11.                     }
  12.                 ],
  13.                 "name": "Cat 1 Sub 1",
  14.                 "categoryId": 3430704,
  15.                 "sortNumber": 0
  16.             },
  17.             {
  18.                 "subCategories": [],
  19.                 "name": "Cat 1 Sub 2",
  20.                 "categoryId": 3430705,
  21.                 "sortNumber": 1
  22.             }
  23.         ],
  24.         "name": "Category 1",
  25.         "categoryId": 3430703,
  26.         "sortNumber": 0
  27.     },
  28.     "status": "ok"
  29. }

Error Response

HTTP Status Code: 200
Error response will contain a JSON object where "status" is set to "error".
  1. {
  2.     "status": "error",
  3.     "message": "some information about what went wrong"
  4. }

Get Messageboard Admin URL

Authorization

All requests made to this API with the action "getMessageboardAdminUrl" require a token.
The token should be provided in the headers as:
Authorization: Bearer <token>
The token should either be a valid user token received via the Login API, or a generated token.

Generated Token

A token consists of 40 character long hex value. The value has two different parts:
1. Current time 32 bits / 8 chars - current timestamp in number of seconds since UNIX Epoch
2. Signature 128 bits / 32 chars - the MD5 hash of (organizationId + ":" + eventId + ":" + Current Time + ":" + Secret), where '+' is a string concatenation

Example

Organization ID: 13509
Event ID: 12345
Current Time: 1686560400 (12.06.2023 12:00:00 UTC) -> '6486de90'
Secret: 'secret'
Signature: MD5('13509:12345:6486de90:secret') -> 27a3aaea2e4bac5f5463e036f2c4c0d1
Generated token: 6486de9027a3aaea2e4bac5f5463e036f2c4c0d1

Path

/api/events

Query Parameters

Name
Type
Requirement
Description
action
String
Mandatory
Value should be: getMessageboardAdminUrl
organizationId
Number
Mandatory
Icareus Suite Organization ID
eventId
Number
Mandatory
Icareus Suite Event ID (not event room id)
username
String
Mandatory
Provided username will be displayed in the messageboard when sending messages to a room.

Success Response


HTTP Status Code: 200
A successful response will always be a JSON object that contains the key "status": "ok".
Successful response will contain a "adminUrl" and a "pollsUrl".
  1. {
  2.   "status": "ok",
  3.   "pollsUrl": "https://messages.icareus.com/admin/12423901/polls?token=eyJ1c2VybmFtZSI6IkV2ZW50IEFkbWluIiwidHMiOjE2ODY3MzEwMDU0NTgsImV2ZW50SWQiOjEyNDIzOTAxLCJvcmdhbml6YXRpb25JZCI6MjYzMTYwOX0=.ZDllMjZmY2ViZTQ1MTQ4ZmJjNTY3YmMwMDkzZWExMWIwOTg5ZjQ0YTNjZDRmZGQ4ZTAyMzBlMTJiYmJiMzk2M2NkMmI2MzVjYWQ4ODI1MTYxMWE2NmQ5MDgxMzMwNTUyOTY2MTc1OGFmMmNmMTQxNjNjM2JmMTUzZDBlYjVkYzQ=",
  4.   "adminUrl": "https://messages.icareus.com/admin/12423901?token=eyJ1c2VybmFtZSI6IkV2ZW50IEFkbWluIiwidHMiOjE2ODY3MzEwMDU0NTgsImV2ZW50SWQiOjEyNDIzOTAxLCJvcmdhbml6YXRpb25JZCI6MjYzMTYwOX0=.ZDllMjZmY2ViZTQ1MTQ4ZmJjNTY3YmMwMDkzZWExMWIwOTg5ZjQ0YTNjZDRmZGQ4ZTAyMzBlMTJiYmJiMzk2M2NkMmI2MzVjYWQ4ODI1MTYxMWE2NmQ5MDgxMzMwNTUyOTY2MTc1OGFmMmNmMTQxNjNjM2JmMTUzZDBlYjVkYzQ="
  5. }

Error Response

HTTP Status Code: 200
Error response will contain a JSON object where "status" is set to "error".
  1. {
  2.   "message": "unauthorized",
  3.   "status": "error"
  4. }




    • Related Articles

    • Tapahtuma API (Events) (FIN)

      Johdanto Tätä APIa käytetään tapahtumien hakemiseen API URL /api/events Tulevien tapahtumien haku Tämä API palauttaa tapahtumat tietyltä aikaikkunalta. Parametrit: Nimi Tyyppi Pakollisuus Kuvaus action Teksti Pakollinen Määrittelee kutsun tyypin ...

    • 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. Latest version: 02 API METHODS REGISTER A DEVICE ...

    • 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 ...

    • Event Management API (ENG)

      Event Management API Introduction This API is used to manage Events, and Event Participants. It can be used to create, edit, delete and list Events and Participants. TOKEN All request made to the following API endpoints require a token. The token ...

    • 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 ...