Category Recommendation API

The following describes how to set up channel or carousel-based video recommendations via the following API route


  1. Ability to request recommendations from specific categories that can be used to populate a carousel or build a channel
  2. Ability for client to send thumbs_up and thumbs_down user interaction updates on videos before an initial video starts
  3. Ability for client to send in a Watch call once a user starts watching a recommended video

Category /watch API Call Query:

A Category /watch Call should be made to request recommendations from a specific category ID.

Parameters - /watch API Call Request:

  • category_id:required [STRING] The BSON ID for the category provided by IRIS.TV.

  • platformrequired [STRING] The name of the publisher

  • numberrequired [INTEGER] The number of recommendations to be returned in the response (max 40)

  • access_tokenrequired [STRING] Token created via OAuth 2 standard

  • user_idrequired [STRING] A unique ID generated to be associated to the individual user

  • client_tokenrequired [STRING] Authentication string associated with each region

  • recs_onlyrequired [BOOLEAN] Set to true

Sample /watch API Call Request:

curl \
category_id=5876c42613a20c0ee9000010 \
&platform=FP \
&number=30 \
&access_token=1d9f05c8b00daddfbffcf5afa8a0691bf6370c0cd9dfc8bc6fb38e13c4474dab \
&user_id=BTORW \

Sample /watch API Call Response:

'success': true,
'next': [
'iris_id': '2140j908',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '241YOFG',
'title': 'Birdman International Trailer',
'release_date': '2014-08-01 18:34:33 UTC'
'iris_id': '51084789cd5f272312231105',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '343YOW',
'title': 'Snow Owl Short Film',
'release_date': '2012-10-22 12:30:58 UTC',
'reviewed': '2013-02-05 23:02:24 UTC',
'iris_id': '539a5ba7f09c3f00172310bb',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '780YOTSDB'',
'title': 'Blue Heron Teaser Trailer',
'release_date': '2014-06-12 20:51:53 UTC'
'iris_id': '53cdc6233459980016231012',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '9019YOPW',
'title': 'Penguin Clip',
'release_date': '2014-07-20 19:51:07 UTC'
'iris_id': '51084760cd5f2723122310a1',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '89YWQMD',
'title': 'Life & Times Trailer',
'release_date': '2012-11-30 05:48:51 UTC',
'reviewed': '2013-09-06 22:35:10 UTC',
'iris_id': '53814f1af1585f0032231014',
'platform': 'Icandenza',
'content_url': '',
'platform_id': '46YDPA',
'title': 'Paleo Diet International Trailer',
'release_date': '2014-05-24 19:33:28 UTC'
'experience': '53ebec0d321d0690858dw5r1'

Response - /watch API Call Request:

  • next: [ARRAY] Recommended assets based on the specified category. See below for asset fields.
  • experience: Unique identifier for the current stream of videos. This value can be ignored.

Video Asset fields:

  • iris_id: [STRING] IRIS.TV’s Reference ID for video

  • platform: [STRING] the name of the publisher

  • content_URL: [STRING] Link to video file on publisher’s CMS (only available if sent in during import process)

platform_id: [STRING] the Reference ID from the publisher’s CMS

  • title: [STRING] Title of video via publisher’s CMS

release_date: [STRING] Date when asset could be recommended (UTC)

  • reviewed: [STRING] Date when asset was reviewed by IRIS.TV staff (UTC)
  • experience: [STRING] Unique identifier for the current stream of videos. Note: a new experience is generated on every watch call.

Error Notifications:

Invalid Access Token

Status Code: 401 Unauthorized IRIS.TV Response: “The access token is no longer valid” Problem: Access Token is invalid or has expired Solution: Create a new access token using OAuth 2

[Documentation for creating access tokens]

Invalid Client Token

Status Code: 401 Unauthorized IRIS.TV Response: “IRIS API: Check your authentication credentials” Problem: Client Token is Incorrect Solution: Double check your client token. If still invalid, contact IRIS.TV support.

No Assets in Next Field

Problem: No assets in library. Solution: Contact IRIS.TV representative and check import schedule.