Prizma offers an REST API for those who wish to build applications that serve personalized Prizma videos. Details for this REST API are provided below.

In order for Prizma to continuously improve recommendations automatically and in real time, it is paramount that usage information be sent via the /events-api call described below.

Before getting started with the REST API, you must have a partner ID. If you don't have one already, get in touch with us here.

Prizma supports a number of different endpoints to get recommendations depending on the use case. Please connect with the Prizma Support team if you have any questions.

This documentation assumes all requests are made client side.

GET /videosForVideoContext

parameter required description
partner_id yes The partner ID provided by the Prizma team
urlnoURL of the page for web and mobile web
title yes The title of the video that has just been played
description yes The description of the video that has just been played
user_id yes A unique user ID. This can be:
  • an application-specific user ID
  • a unique device ID if the user is logged out
  • a cookie ID if requested by a webpage
user_type no The type of ID based on the options listed above:
  • cookie
  • device
  • app
session_id no An identifier unique to the current user session (browser tab, app instantiation, etc)
prizma_id no The Prizma video ID if the video has been previously recommended by Prizma
num no Number of videos to return. Defaults to 10. Max:30

GET /videosForArticleContext

parameter required description
partner_id yes The partner ID provided by the Prizma team
url yes The URL of the article on the web or mobile web
title yes The title of the video that has just been played
description yes The description of the video that has just been played
user_id yes A unique user ID. This can be:
  • an application-specific user ID
  • a unique device ID if the user is logged out
  • a cookie ID if requested by a webpage
user_type no The type of ID based on the options listed above:
  • cookie
  • device
  • app
session_id no An identifier unique to the current user session (browser tab, app instantiation, etc)
num no Number of videos to return. Defaults to 10. Max:30

JSON Response

{
  "num": N, // The number of videos returned in the response
  "partner_id": partner_id,
  “results”: [  // A list of recommended videos
    {
      “prizma_id”: “...”, // The ID of the first recommended video
      "title": "...", // The title of the video
      "all_thumbnails": [  // All associated thumbnails with the video
      ]
      "prizma_data": {
          "experimentid": "...",
          ...
      },
      "partner_data": { // Data provided by the partner in the video feed needed to render to video if present.
           "content_id": "..."
        },   
    },
  
   ....
   ]
}
Event name Sent
UnitVisible Sent when recommendations are ready and viewable by the user for a single unit
VideoPlayStarted Sent when the current video starts playing
VideoPlayCompleted Sent when the current video finishes playing
VideoProgress Sent every 5 seconds during video playback after video start. Events would be sent at t=0, t=5, t=10, t=15, etc., until the video ends.
name required description
event_name yes The event type. See above
partner_id yes The partner ID provided by Prizma
urlnoURL for web and mobile web implementations
endpoint yes Endpoint used to get video recommendations
user_id yes The user ID used to request video recommendations
user_type no The user type corresponding to the user ID
session_id no An ID unique to the current user session. This would be set when the user opens the app, and would change when the user leaves the app and returns.
title no The title of the current article of video used to request recommendations
prizma_id no The video ID if a video has been loaded into the player or has been selected by the user.
video_parent_id no If the current video was triggered from a previous video recommended by Prizma the previous Prizma video ID
unit_video_list yes Ordered list of recommended videos available to the user in the unit. Each list item is an object of the form {“video_id”: “...”}.
prizma_data yes Data provided by prizma in the JSON response. Used to run A/B tests and more.
name required description type
event_name yes The event type. See event types below. string
partner_id yes The partner ID provided by Prizma string
urlnoURL for web and mobile web string
endpoint yes The endpoint used to get video recommendations (either "videosForVideoContext" or "videosForArticleContext") string
prizma_id yes ID of the currently playing video if it was returned by a recommdnation endpoint string
user_id yes The user ID used to request video recommendations string
user_type no The type of identifier used in identifying the user (either "cookie" or "device") enum{"cookie", "device"}
session_id no An ID unique to the current user session. For example, in a mobile app, this would be set when the user opens the app and would change when the user quits the app and returns. string
parent_prizma_id no If the current video was triggered from End Slate, the prizma ID of the previous video string
video_autoplay no Whether the video play started without user action boolean
unit_video_list no List of recommended videos in the "unit" that the user picked the current video from. See definition of unit above. Each list item is an object of the form {“prizma_id”: “...”}. Array<{prizma_id: string}>
video_position no If multiple videos were recommended to the user, the index of this video in that list, starting at 1. number
video_duration no The length of the current video in seconds as a float. number
video_elapsed see description The seek position of the current playing video in seconds as a float. Required for VideoProgress events. number
has_preroll no Boolean which indicates whether a preroll was placed in front of the video boolean
prizma_data yes Data provided by prizma in the JSON response. Used to run A/B tests and more. Object