UserMedia API Manual

By
Manual

Icecat users have the ability to upload media assets to Icecat endpoints using the UserMedia feature. This manual provides instructions on uploading videos via the UserMedia API and presenting them via Icecat LIVE.

Swagger schema: https://api.icecat.biz/#/UserMedia

1. Initial Setup

All requests are sent to https://bo.icecat.biz/restful/v3/ and SessionType is always Rest.While it is possible to reach API with your programming language or terminal tools like curl and wGet, I would recommend using tools like Insomnia or Postman to work with our data as the requests can be complicated.

2. Authorization

You need to have either a brand or shop type account to use UserMedia API. To initiate data transmission, you must authenticate yourself with the API by obtaining a session key. This session key is required for subsequent requests to ensure proper API authentication. Please, follow point 1.3 from the PUSH API manual.

3. UserMedia API Endpoints

3.1. POST – Add UserMedia Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Headers:

Content-Type: multipart/form-data

Multipart data:

'Title=My Title'
'LanguageIds=10,1,2'
SourceLink=http://example.com/FunnyElephant.mp4
ProviderUserId=99999

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: multipart/form-data' \
  --header 'accept: application/json' \
  --form 'Title=My Title' \
  --form 'LanguageIds=10,1,2' \
  --form SourceLink=http://example.com/FunnyElephant.mp4 \
  --form ProviderUserId=99999

Variables:

_.accessKey Access key
TitleVideo title
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
SourceLinkLink to your video. Allowed formats: 3gp, avi, flv, m4v, mkv, mov, mp4, mpg, ogg, vob, wmv, webm.
ProviderUserIdID of your Icecat account, contact support@icecat.biz to get yours.

Success response 201:

{
    "Data": {
   	 "VideoId": 33232080
    }
}

3.2. GET – Receive Video Data by VideoId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
  "Data": {
	"VideoId": 99999,
	"Title": "My Title",
	"Link": "https://example.icecat.biz//",
	"LanguageIds": [
  	2,
  	3,
  	10
	],
	"ProviderUserId": 303033,
	"Status": "Done",
	"PreviewImageLink": "https://example.icecat.biz//",
	"PreviewImageLinkTmp": "https://example.icecat.biz//",
	"PreviewThumbLink": "https://example.icecat.biz//",
	"PreviewThumbLinkTmp": "https://example.icecat.biz//",
	"Accesses": [],
	"AgeRatings": []
  }
}

Response is constructed from links to your UserMedia on Icecat servers and additional data.

VideoIdVideo ID
TitleVideo title
LinkLink to the video
LanguageIdsIDs for your languages. Comma-separated. Refer here: Locales & Language Code Table
ProviderUserIdVideo owner’s ID
StatusVideo upload status
PreviewImageLinkLink to video image preview
PreviewImageLinkTmpTemporary link to video image preview
PreviewThumbLinkLink to video image preview in thumbnail format
PreviewThumbLinkTmpTemporary link to video image preview in thumbnail format
AccessesUsers are allowed to update your video
AgeRatingsAge Ratings activated for your videos

3.3. PATCH – Update Title for Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&Sess
ionType=Rest

Body:

{
    "Title": "My new Title"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
	"Title": "My new title"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200:

{
    "Data": {}
}

3.4. DELETE – Delete Video By ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.

Success response 200: Returns an ID of the deleted Video.

{
    "Data": {
   	 "VideoId": 332079
    }
}

3.5. GET – Receive all UserMedia Videos

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key

Success response 200: Method returns all Videos stored on Icecat.

4. Languages

Please check the IDs for Icecat Languages here: Locales & Language Code

4.1. POST – Add language to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "LanguageId": 3
}'

Body:

{
  "LanguageId": 3
}

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200: Returns ID of activated languages.

{
    "Data": {
   	 "LanguageId": 3
    }
}

4.2. GET – Receive Video Data with Language by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=Languages' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Success response 200:

{
    "Data": {
   	 "VideoId": 0,
   	 "Title": "",
   	 "Link": "",
   	 "LanguageIds": [
   		 2,
   		 3,
   		 10
   	 ],
   	 "ProviderUserId": 0,
   	 "Status": "Done",
   	 "PreviewImageLink": "",
   	 "PreviewImageLinkTmp": "",
   	 "PreviewThumbLink": "",
   	 "PreviewThumbLinkTmp": "",
   	 "Accesses": [],
   	 "AgeRatings": []
    },
    "Metadata": {
   	 "Languages": [
   		 {
   			 "LanguageId": 2,
   			 "ShortCode": "NL"
   		 },
   		 {
   			 "LanguageId": 3,
   			 "ShortCode": "FR"
   		 },
   		 {
   			 "LanguageId": 10,
   			 "ShortCode": "BR"
   		 }
   	 ]
    }
}

4.3. DELETE – Remove Language from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Languages/{{ _.languageID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideoID, received in p. 3.1.
LanguageIdIDs of the languages for your video. Locales & Language Code

Success response 200:

{
    "Data": {}
}

5. Accesses

With accesses you can assign users to edit your UserMedia. You can only allow shop users to get access to your videos.

5.1. POST – Add an access for Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/332080/Accesses?AccessKey={{ _.accessKey }}&SessionType=Rest' \
  --data '{
  "AuthorizedUserId": {{_.userID}},
  "UserReference": "My-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.userIDID of a shop user you would like to grant access to. Please contact support@icecat.biz.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 201:

{
    "Data": {
   	 "AccessId": 0,
   	 "AuthorizedUserId": 0,
   	 "UserReference": "My-team-lead"
    }
}

5.2. PATCH – Update UserReference by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Body:

{
    "UserReference": "My-ex-team-lead"
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{ _.accessId }}?AccessKey={{ _.accessKey }}&SessionType=Rest' \
	--data '{
	"UserReference": "My-ex-team-lead"
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.
UserReferenceShort description for your access. Please do not use white-spaces.

Success response 200:

{
    "Data": {
   	 "AccessId": 9060198,
   	 "AuthorizedUserId": 110865,
   	 "UserReference": "My-ex-team-lead"
    }
}

5.3. DELETE – Remove Access by AccessId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}/Accesses/{{_.accessId}}?AccessKey={{ _.accessKey }}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.accessIdAccess ID, received in p. 5.1.

Success response 200:

{
    "Data": {}
}

6. Age Ratings

Age Ratings are additional labels to mark which audience the video is available for. They display minimum age requirements for the content.

6.1. GET – Receive Age Ratings Dictionary

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings

Example:

curl --request GET \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{_.videoID}}?AccessKey={{_.accessKey}}&SessionType=Rest&Metadata%5B%5D=AgeRatings'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
Metadata[]Metadata you want to receive. Can be Languages or Age Ratings.

Response returns all information about each Age Rating provider.

AgeRatingIdID of the Age Rating provider.
AgeRatingAge Rating provider name.
AgeRatingValuesEach provider has its own system of ratings and this array contains all possible values.
AgeRatingDescriptorsDescription of content that appears in video which can affect Age Rating.

6.2. POST – Add Age Rating to Video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
	2
  ]
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '	{
  "AgeRatingId": 1,
  "AgeRatingValueId": 2,
  "AgeRatingDescriptorIds": [
    2
  ]
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
AgeRatingId, AgeRatingValueId, AgeRatingDescriptorIdsRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
   	 "AgeRatingId": 1
    }
}

6.3. PATCH – Update AgeRatingValue by AgeRatingId

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingValueId": 3
}

Example:

curl --request PATCH \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --header 'Content-Type: application/json' \
  --data '{
  "AgeRatingValueId": 3
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingValueIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response:

{
    "Data": {}
}

6.4. DELETE – Remove Age Rating from video by ID

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingId }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

7. Age Ratings Descriptors

AgeRatingDescriptor is a label that shows additional information about provocative content that is not suited for minors. For example, “Drugs” or “Sex” are the descriptors in PEGI rating.

7.1. POST – Add Age Rating Descriptor to Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest

Body:

{
  "AgeRatingDescriptorId": 7
}

Example:

curl --request POST \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors?AccessKey={{_.accessKey}}&SessionType=Rest' \
  --data '{
  "AgeRatingDescriptorId": 7
}'

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, AgeRatingDescriptorIdRefer to Age Ratings Dictionary, received in p.6.1.

Success response 201:

{
    "Data": {
   	 "AgeRatingDescriptorId": 7
    }
}

7.2. DELETE – Remove Age Descriptor from Video

Path:

https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest

Example:

curl --request DELETE \
  --url 'https://bo.icecat.biz/restful/v3/UserMedia/Videos/{{ _.videoID }}/AgeRatings/{{ _.ageRatingID }}/Descriptors/{{ _.ageRatingDescriptorID }}?AccessKey={{_.accessKey}}&SessionType=Rest' \

Variables:

_.accessKeyUser access key
_.videoIdVideo ID, received in p. 3.1.
_.ageRatingId, _.ageRatingDescriptorIDRefer to Age Ratings Dictionary, received in p.6.1.

Success response 200:

{
    "Data": {}
}

8. Errors

Error codeError messageResolution
400Some of the parameters are not valid or were not inputted. See returned message for detailsCheck your input method.
400HTTP method GET is not described in the swagger schema.Change HTTP method to HTTPS.
401Your AccessKey is not valid any moreRenew your AccessKey with Session/ endpoint.
403You are not assigned to this content!Check the Video accesses with UserMedia/Videos/{{_.videoID}} endpoint.
500This should never happen!Report such cases to support@icecat.biz

9. UserMedia API with Icecat LIVE JS AP

To retrieve videos uploaded through the UserMedia API using Icecat LIVE JS API, you will need to include two essential parameters in your request code:

UserReferenceUser references code. This is a user identifier that helps to search loaded video into the Icecat system.
ProviderIdUser identifier of the owner of an uploaded video in Icecat system (the same as ProviderUserId).

These two parameters are required for showing the user’s videos into live html.

Age gating is activated by default, however it is possible to disable it by adding videoAgeGatingDisabled: true parameter. Please see an example below.

9.1. Granular call + UserMedia

Videos uploaded via UserMedia API can be requested via Granular call to be included among other containers. For this you need to include a ‘videos’ container to the call, UserReference and ProviderId are also required. The request works with any identifier combinations, Smart call and Multilingual request. Please refer to the Granular Call manual for more info.

Granular call with UserMedia API parameters – Brand + MPN:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

The same request with Age gating disabled:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="сontainer1"></div>
    <div id="сontainer2"></div>
    <script>
      window.addEventListener('liveload', function () {
        IcecatLive.getDatasheet(
          {
            gallery: '#сontainer1',
            videos: '#сontainer2',
          },
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
 	videoAgeGatingDisabled: true,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>

9.2. Icecat Live API for Granular call of UserMedia API with only media assets

Users can request videos uploaded via UserMedia API exclusively without requesting any specific product or data containers using Icecat Live. ProviderId and UserReference parameters are required.

<!DOCTYPE html>
<html>

<head></head>

<body>
  <div id="сontainer"></div>
  <script>
	window.addEventListener('liveload', function () {
  	IcecatLive.getUnlinkedVideos(
    	'#сontainer',
    	{
      	shopname: 'shop_user',
      	UserReference: 'user_code',
      	ProviderId: 1,
    	},
    	'en'
  	);
	});
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
</body>

</html>

9.3. Icecat Live API for Regular call of UserMedia API

The Regular call of datasheet + UserMedia API parameters – Brand + MPN (can also be used with Icecat ID based, EAN-based calls, and Smart call):

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="container"></div>
    <script>
      window.addEventListener('liveload', function () {
        window.IcecatLive.getDatasheet(
          '#container',
          {
            Brand: 'Philips',
            PartCode: 'DS8900/10',
            UserName: 'shop_user',
            UserReference: 'user_code',
            ProviderId: 1,
          },
          'en'
        );
      });
    </script>
    <script src="https://live.icecat.biz/js/live-current-2.js" async></script>
  </body>
</html>
Icecat xml

Open Catalog Interface (OCI): Manual for Open Icecat XML and Full Icecat XML

This document describes the Icecat XML method of Icecat's Open Catalog Inte...
 November 3, 2019
Manual

Manual for Icecat Live: Real-Time Product Data in Your App

Icecat Live is a (free) service that enables you to insert real-time produc...
 June 10, 2022
Manual for Icecat CSV Interface

Manual for Icecat CSV Interface

This document describes the manual for Icecat CSV interface (Comma-Separate...
 September 28, 2016
 October 4, 2018
LIVE JS

How to Create a Button that Opens Video in a Modal Window

Recently, our Icecat Live JavaScript interface was updated with two new fun...
 November 3, 2021
Addons plugins

Icecat Add-Ons Overview. NEW: Red Technology

Icecat has a huge list of integration partners, making it easy for clients ...
 October 27, 2023
Manual

Manual for Open Icecat JSON Product Requests

JSON (JavaScript Object Notation) is an increasingly popular means of trans...
 September 17, 2018
 January 20, 2020
New Standard video thumbnail

Autheos video acquisition completed

July 21, Icecat and Autheos jointly a...
 September 7, 2021
Manual

Manual Personalized Interface File and Catalog from Icecat

With Icecat, you can generate personalized or customized CSV or Excel files...
 May 3, 2022