From Mogulus

The Mogulus Account Management API allows client applications to manage user and channels belonging to a given affiliate. The client application can access Account Management API in a platform-independent, language-independent way. Mogulus Account Managemenet API is a web application running on Http Server supporting both Get and Post methods.

Contents 1 Audience 2 Prerequisites 3 Categories 4 Languages 5 Countries 6 Timezones 7 Ratings 8 Users 8.1 Create User 8.2 Update User Details 8.3 Get User Details 8.4 Delete User 8.5 Change Password 8.6 Generate Password 9 Channels 9.1 Create Channel 9.2 Update Channel Details 9.3 Get Channel Details 9.4 Get Channel Live Status 10 Response Codes

Audience

---

This document is intended for programmers who want to write client applications that can access Mogulus Account Management. The document provides examples of the supported operations using raw HTTP and XML, along with explanations

Prerequisites

---

Obtaining Affiliate Id and Key from Mogulus

In order to query the Mogulus API you need to obtain a Mogulus API Affiliate ID and Application Key. Please request by sending an email to info@mogulus.com providing as much details on your project as possible. Affiliate API Keys can configured by Mogulus to filter a specific set of channels, or even to provide a private channel group.

Required Knowledge and skills

1. XML

2. Basic understanding of REST

3. Any programming language.

Categories

---

The API provides a method getCategories to retrieve the list of Mogulus categories as an XML. The category ID returned in the XML can be used to set the channel category in the Channel Management API.

Parameter	Allowed values	Description
method	getCategories	The name of the operation. In this case getCategories
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.

e.g To retrieve the list of Mogulus categories one should form the Http Query expression like

GET

    
  http://account.api.mogulus.com/account?method=getCategories
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned will be similar to the following XML snippet

       <response status="200">
          <categories>
	     <category id="18" name="Art and Creativity" />
	     <category id="1" name="Auto and Vehicles" />
             ......
         </categories>
       </response>

Languages

---

The API provides a method getLanguages to retrieve the list of languages as an XML. The language ID returned in the XML can be used to set the channel language in the Channel Management API.

Parameter	Allowed values	Description
method	getLanguages	The name of the operation. In this case getLanguages
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.

e.g To retrieve the list of Mogulus languages one should form the Http Query expression like

GET

    
  http://account.api.mogulus.com/account?method=getLanguages&
  affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned will be similar to the following XML snippet

       <response status="200">
          <languages>
	     <language id="1" iso="en" name="English" />
	     <language id="2" iso="bn" name="Bengali" />
             ......
         </languages>
       </response>

Countries

---

The API provides a method getCountries to retrieve the list of countries as an XML. The country ID returned in the XML can be used to set the channel country in the Channel Management API.

Parameter	Allowed values	Description
method	getCountries	The name of the operation. In this case getCountries
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.

e.g To retrieve the list of countries one should form the Http Query expression like

GET

    
  http://account.api.mogulus.com/account?method=getCountries&
  affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned will be similar to the following XML snippet

       <response status="200">
          <countries>
	     <country id="3" iso="AF" name="Afghanistan" iso3="AFG" />
             <country id="6" iso="AL" name="Albania" iso3="ALB" />
             ......
         </countries>
       </response>

Timezones

---

The API provides a method getTimeZones to retrieve the list of time zones as an XML. The country ID returned in the XML can be used to set the channel time zone in the Channel Management API.

Parameter	Allowed values	Description
method	getTimeZones	The name of the operation. In this case getTimeZones
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.

e.g To retrieve the list of time zones one should form the Http Query expression like

GET

    
  http://account.api.mogulus.com/account?method=getTimeZones&
  affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned will be similar to the following XML snippet

       <response status="200">
          <timezones>
	     <timezone id="1" location="International Date Line West" 
               offset="(GMT-12:00)" />
             <timezone id="2" location="Midway Island" offset="(GMT-11:00)" />
             ......
         </timezones>
       </response>

Ratings

---

The API provides a method getRatings to retrieve the list of channel ratings as an XML. The rating ID returned in the XML can be used to set the channel rating in the Channel Management API.

Parameter	Allowed values	Description
method	getRatings	The name of the operation. In this case getRatings
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.

e.g To retrieve the list of time zones one should form the Http Query expression like

GET

    
  http://account.api.mogulus.com/account?method=getRatings&
  affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned will be similar to the following XML snippet

       <response status="200">
          <ratings>
	     <rating id="1" name="G" description="General Audiences" />
             <rating id="2" name="PG" description="Parental Guidance Suggested" />
             ......
         </ratings>
       </response>

Users

---

Create User

The method createUser can be used to create a Mogulus user. The user thus created will have a Mogulus account which he or she can use to login to Mogulus and create his or her own channels.

Parameter	Allowed values	Description
method	createUser	The name of the operation. In this case createUser
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
password		A valid password (min 6 and max 40 characters without period character).
userXML		XML containing the user data like user name, email etc. The XML format is explained below

This method supports both HTTP POST and GET. However it is better to use HTTP POST method for this operation simply because the length of the userXML could be large.

e.g To create a user with a user name benhomer, the userXML would be as mentioned below

       <user>
          <username>benhomer</username>          
          <firstName>Ben</firstName>
          <lastName>Homer</lastName>
          <email>ben.homer@benhomer.com</email>
          <city>New York</city>
          <countryId>223</countryId>
          <postcode>NY1011</postcode>
          <gender>M</gender>
          <dob>1989-09-16</dob>
          <website>www.benhomer.com</website>
          <occupation>IT</occupation>
          <description>Keenly interested in Mogulus</description>
          <jobTitle>Homer</jobTitle>
          <company>Ben Homer Inc</company>
       </user>

The following fields are mandatory in the userXML

• username
• firstName
• lastName
• email

username should have minimum of 4 and maximum of 40 characters without any non english character

countryId - This is id attribute of the country item returned by getCategories method mentioned above. The default country id is 223 (US)

dob - Should strictly be in the format YYYY-MM-DD

Hence the bare minimal userXML format would be as mentioned below

       <user>
          <username>benhomer</username>          
          <firstName>Ben</firstName>
          <lastName>Homer</lastName>
          <email>ben.homer@benhomer.com</email>
       </user>

GET The following would be the HTTP Request to create a user via GET

    
  http://account.api.mogulus.com/account?method=createUser
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &userXML=<user><username>benhomer</username><firstName>Ben</firstName>
  <lastName>Homer</lastName><email>ben.homer@benhomer.com</email></user>
  &password=<<your password>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus. And replace <<your password>> with a valid password

In case of successful user creation, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>user created successfully</message>
       </response>

In case of successful user creation, a mail is sent to the user's email id to confirm the user account creation.

Update User Details

The method updateUserDetails can be used to update the details of the user.

Parameter	Allowed values	Description
method	updateUserDetails	The name of the operation. In this case updateUserDetails
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
userXML		XML containing the user data like user name, email etc. The XML format is explained below

This method supports both HTTP POST and GET. However it is better to use HTTP POST method for this operation simply because the length of the userXML could be large.

e.g To update the details of the user with a user name benhomer, the userXML would be as mentioned below. where username is used as the identifier.

       <user>
          <username>benhomer</username>          
          <firstName>Ben</firstName>
          <lastName>Homer</lastName>
          <email>ben.homer@benhomer.com</email>
          <city>New York</city>
          <countryId>223</countryId>
          <postcode>NY1011</postcode>
          <gender>M</gender>
          <dob>1989-09-16</dob>
          <website>www.benhomer.com</website>
          <occupation>IT</occupation>
          <description>Keenly interested in Mogulus</description>
          <jobTitle>Homer</jobTitle>
          <company>Ben Homer Inc</company>
       </user>

The following fields are mandatory in the userXML

• username

username - should have minimum of 4 and maximum of 40 characters without any non english character

countryId - This is id attribute of the country item returned by getContries method mentioned above. The default country id is 223 (US)

dob - Should strictly be in the format YYYY-MM-DD

Hence the bare minimal userXML format would be as mentioned below

       <user>
          <username>benhomer</username>
          <website>www.newblog.com</website>
          <occupation>Marketing</occupation>          
       </user>

GET The following would be the HTTP Request to update user details via GET

    
  http://account.api.mogulus.com/account?method=updateUserDetails
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &userXML=<user><username>benhomer</username><occupation>Marketing</occupation> 
  <website>www.newblog.com</website></user> 

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

In case of successful user creation, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>user details updated successfully</message>
       </response>

Get User Details

The method getUserDetails can be used to retrieve the information about the user as an XML belonging into the specified affiliate.

Parameter	Allowed values	Description
method	getUserDetails	The name of the operation. In this case getUserDetails
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
username		The username of the user

This method supports both HTTP POST and GET.

e.g To retrieve the details of user with username benhomer

GET The following would be the HTTP Request to create a user via GET

     
  http://account.api.mogulus.com/account?method=getUserDetails
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &username=<<username>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.And <<username>> with the username of the user to delete

The response returned would look like

     
<response status="200">
	<user>
		<username>benhomer</username>
		<firstName>Ben</firstName>
		<lastName>Homer</lastName>
		<email>ben.homer@benhomer.com</email>
		<city></city>
		<countryId>223</countryId>
		<postcode></postcode>
		<gender></gender>
		<dob></dob>
		<website>www.newblog.com</website>
		<occupation>Marketing</occupation>
		<description></description>
		<jobTitle></jobTitle>
		<company></company>
	</user>
</response>

Delete User

The method deleteUser can be used to delete a user.

Parameter	Allowed values	Description
method	deleteUser	The name of the operation. In this case deleteUser
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
username		The username of the user

This method supports both HTTP POST and GET.

GET The following would be the HTTP Request to update user details via GET

    
  http://account.api.mogulus.com/account?method=deleteUser
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &username=<<username>> 

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus. And <<username>> with the username of the user to delete

In case of successful user deletion, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>user deleted successfully</message>
       </response>

Change Password

The method changePassword can be used to change the password for a user.

Parameter	Allowed values	Description
method	changePassword	The name of the operation. In this case changePassword
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
username		The username of the user
currentPassword		The existing password.
newPassword		(min 6 and max 40 characters without period character).

This method supports both HTTP POST and GET.

GET The following would be the HTTP Request to update user details via GET

    
  http://account.api.mogulus.com/account?method=changePassword
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &username=<<username>>&currentPassword=<<current password>>
  &newPassword=<<new password>> 

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus. And <<username>> by the username of the user and <<current password>> by the existing password and <<new password>> by the new password to set. .

In case of successful change of password, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>Password changed succesffully</message>
       </response>

Generate Password

The method generatePassword can be used to generate a new random password for the user. The newly generated random password is emailed to the user .

Parameter	Allowed values	Description
method	generatePassword	The name of the operation. In this case generatePassword
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
username		The username of the user
email		The user's email id which is in the mogulus records.

This method supports both HTTP POST and GET.

GET The following would be the HTTP Request to update user details via GET

    
  http://account.api.mogulus.com/account?method=generatePassword
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &username=<<username>>&email=<<email id>>
  &newPassword=<<new password>> 

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus. And <<username>> by the username of the user and <<email id>> by the user's email id which is in the mogulus records .

In case of successful generation of new password, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>New password generated and mailed successfully</message>
       </response>

Channels

---

Create Channel

The method createChannel can be used to create a new channel.

Parameter	Allowed values	Description
method	createChannel	The name of the operation. In this case createChannel
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
username		The username of the owner of the channel.
channelXML		XML containing the channel data like shortName, fullName etc. The XML format is explained below

This method supports both HTTP POST and GET. However it is better to use HTTP POST method for this operation simply because the length of the userXML could be large.

e.g To create a channel with a name benchannel, the channelXML would be as mentioned below

      <channel>	
		<shortName>benchannel</shortName>
		<fullName>ben entertainment</fullName>
		<description>Ben's entertaining channel</description>
		<tags>Anything can come here</tags>
		<ratingId>1</ratingId>	
		<timezoneId>1</timezoneId>
		<languageId>12</languageId>	
		<logoUrl></logoUrl>
		<categoryId>1</categoryId>		
		<countryId>223</countryId>	
	</channel>

The following field(s) are mandatory in the channelXML to create a channel

• shortName
• fullName
• categoryId

shortName - This is considered as the name of the channel

countryId - This is id attribute of the country item returned by getCountries method mentioned above. The default value is 223 (United States).

categoryId - This is id attribute of the categoryitem returned by getCategories method mentioned above.

languageId - This is id attribute of the language item returned by getLanguages method mentioned above. The default value is 1 (English).

timezoneId - This is id attribute of the timezoneitem returned by getTimeZones method mentioned above. The default value is 19 (Eastern Time (US & Canada)).

ratingId - This is id attribute of the ratingitem returned by getRatings method mentioned above. The default value is 1 (General Audiences).

Hence the bare minimal userXML format would be as mentioned below

       <channel>
          <shortName>benchannel</shortName>		
       </channel>

GET The following would be the HTTP Request to create a user via GET

    
  http://account.api.mogulus.com/account?method=createChannel
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &channelXML=<channel><shortName>benchannel</shortName><fullName>ben   
  entertainment</fullName><description>Ben's entertaining    
  channel</description></channel>
  &username=<<your username>>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus. And replace <<your username>> with the username of the channel owner

In case of successful user creation, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>channel created successfully</message>
       </response>

Update Channel Details

The method updateChannelDetails can be used to update the details of a channel.

Parameter	Allowed values	Description
method	updateChannelDetails	The name of the operation. In this case updateChannelDetails
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
channelXML		XML containing the channel data like user shortName, fullName etc. The XML format is explained below

This method supports both HTTP POST and GET. However it is better to use HTTP POST method for this operation simply because the length of the channelXML could be large.

e.g To update a channel with a name benchannel, the channelXML would be as mentioned below

      <channel>	
		<shortName>benchannel</shortName>
		<fullName>ben entertainment</fullName>
		<description>Ben's entertaining channel</description>
		<tags></tags>
		<ratingId>1</ratingId>	
		<timezoneId>1</timezoneId>
		<languageId>0</languageId>	
		<logoUrl></logoUrl>
		<categoryId>0</categoryId>
		<bannerUrl></bannerUrl>
		<bannerDimension></bannerDimension>
		<playerColor></playerColor>
		<backgroundColor></backgroundColor>
		<countryId>0</countryId>	
	</channel>

The following fields are mandatory in the userXML

• shortName

shortName - This is considered as the name of the channel

countryId - This is id attribute of the country item returned by getCountries method mentioned above.

categoryId - This is id attribute of the categoryitem returned by getCategories method mentioned above.

languageId - This is id attribute of the language item returned by getLanguages method mentioned above.

timezoneId - This is id attribute of the timezoneitem returned by getTimeZones method mentioned above.

ratingId - This is id attribute of the ratingitem returned by getRatings method mentioned above.

Hence the bare minimal userXML format would be as mentioned below

       <channel>
          <shortName>benchannel</shortName>		
       </channel>

GET The following would be the HTTP Request to update user details via GET

    
  http://account.api.mogulus.com/account?method=updateChannelDetails
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &channelXML=<channel><shortName>benchannel</shortName><fullName>ben 
  entertainment</fullName><description>Ben's entertaining  
  channel</description></channel>

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

In case of successful user creation, the response returned will be similar to the following XML snippet

       <response status="200">
           <message>channel details updated successfully</message>
       </response>

Get Channel Details

The method getChannelDetails can be used to retrieve the information about a channel as an XML belonging into the specified affiliate.

Parameter	Allowed values	Description
method	getChannelDetails	The name of the operation. In this case getChannelDetails
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
shortName		The shortName of the channel

This method supports both HTTP POST and GET.

e.g To retrieve the details of channel benchannel

GET The following would be the HTTP Request to create a user via GET

     
  http://account.api.mogulus.com/account?method=getChannelDetails
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &shortName=benchannel

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned would look like

     
<response status="200">
	<channel>
		<shortName>benchannel</shortName>
		<fullName>ben entertainment full</fullName>
		<description>Ben's entertaining channel</description>
		<tags></tags>
		<ratingId>0</ratingId>
		<timezoneId>0</timezoneId>
		<languageId>0</languageId>
		<logoUrl></logoUrl>
		<categoryId>0</categoryId>
		<bannerUrl></bannerUrl>
		<bannerDimension></bannerDimension>
		<playerColor></playerColor>
		<backgroundColor></backgroundColor>
		<countryId>0</countryId>
	</channel>
</response>

Get Channel Live Status

The method isChannelLive can be used to find whether is channel is live or not.

Parameter	Allowed values	Description
method	isChannelLive	The name of the operation. In this case isChannelLive
affiliateId		Affiliate Id provided by Mogulus.
applicationKey		Application key provided by Mogulus.
shortName		The shortName of the channel

This method supports both HTTP POST and GET.

e.g To know the live status of the channel benchannel

GET The following would be the HTTP Request to create a user via GET

     
  http://account.api.mogulus.com/account?method=isChannelLive
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>
  &shortName=benchannel

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Mogulus.

The response returned would look like

     
<response status="200">
	<channel isLive='false'></channel>
</response>

Response Codes

---

Code	Message	Description
200	OK	Invoked operation is executed successfully.
400	Client Error	Client error occurs when the requested url is malformed.
401	Unauthorized client error	Response code 401 is returned when the given affiliateId or the Application key Is invalid. Or The channel of the user requested doesn't exisits
503	Server Error	Server error may occur when the moguls account management server is temporarily down for maintenance.