Data Partner Enrichment API Integration

Integration Overview

Step 1: Receiving Video Data for Enrichment Processing

IRIS.TV will send asset meta data to contracted contextual data partners for processing. Meta Data for Video Content, Asset Content will be identified for Data Partners using the enrichment_id.

Videos will be sent via an HTTP Post with a JSON body.

Source URL, Billing ID, Enrichment ID are used as asset identifiers; the combination(s) help refine what the asset processing options are.

Video metadata can include:

- enrichment_id (unique identifier)
- billing_id (publisher identifier)
- source_url
  - file types can be mp4 or m3u8
  - if no URL exists, this will be sent as a null
    source_url (urls are unique video identifiers)
- Series Title
- Show Title
- Description
- Length (seconds)
- Source Keywords

- Thumbnail URL

- Closed Caption URL
  - .txt,
  - .vtt, or
  - .srt

Data completeness may vary by publisher and feed; enrichment processing must support null values and empty fields.

NOTE: Bolded fields are included on all new data as of this document and going forward.

JSON video asset metadata sample:

{
  "source_url" : "https://demo.client.com/2020/02/11/1696087107539/18066_5-f1bce056_444291_5192.mp4",
  "title" : "Red Sox in Wild Card Race",
  "description" : "After a 15 game winning streak, the Red Sox are in AL Wild Card Race.",
  "length_secs" : 136,
  "thumbnail_url" : "https://demo.client.com/2020/02/10/18066_5_video_640x360-e44050dc.jpg",
  "source_keywords" : 
  [
   "Red Sox",
   "Boston",
   "MLB",
   "American League",
   "AL",
   "Sports"
  ],
  "billing_id" : 111,
  "closed_caption_url" : "https://demo.client.com/2020/02/10/18066_5-e13346aa.vtt"
}

Step 2: Sending Contextual Segments to IRIS.TV

Contextual data partners will send segments for each video to IRIS.TV to be stored and activated via IRIS.TV’s ad server integrations:

Unique Identifier: the enrichment_id

Data partners can now enrich an asset using the enrichment_id or source_url paired the billing_id.

Why are we migrating to the enrichment_id from the source_url?

Moving away from source_url to enrichment_id as the unique identifier enables IRIS.TV enabled Data Partners to quickly identify and access assets regardless of publisher CDNs, or CMS.

Data segments are sent via an HTTP Post to IRIS.TV with a JSON body.

Sample curl statement for billing_id + enrichment_id

curl -H "Content-Type: application/json" \
  --request POST \
  --data \

 '{
      "secret":"iris.tv will provide your secret key-it goes here.",
      "enrichment_id": "return the assets enrichment_id as it was received" 
      "billing_id":111, 
      "segments":["ab_segment_1","ab_segment_2"]

   }' \ 

https://fertilizer.iris.tv/iris_<your_company_name>_notifications

billing_id must be sent as an integer, NOT as a string.

Sample curl statement for billing_id + source_url

curl -H "Content-Type: application/json" \
  --request POST \
  --data \

 '{
      "secret":"iris.tv will provide your secret key-it goes here.",
      "url": "https://sample.asset.com.mp4" 
      "billing_id":111, 
      "segments":["ab_segment_1","ab_segment_2"]

   }' \ 

https://fertilizer.iris.tv/iris_<your_company_name>_notifications

Resending Segmentation for Existing Assets

Data partners can re-enrich an asset using the enrichment_id or source_url paired the billing_id.

Re-enriched assets will overwrite the initial segments with the newest segments.

Contextual Segment(s) Activation

IRIS.TV stores contextual data partners segments as 3^rd party meta-data on each video's asset record in the IRIS.TV system.

When a video is viewed IRIS.TV will send contextual data partner segments to the publisher's ad call in the form of a key value pair (KVP Segment ID).

Data Partner Enrichment Health and Ad calls may be monitored using the IRIS.TV platform