Sub Account API Documentation
Encoding.com XML API Guide
Fields values
UserID — an unique user identifier. Can be taken from user's page.
UserKey — user's key string. Creates automatically when user created and can be changed by user.
Action – the action to be performed.
— AddSubUser — add new sub user. Sub accounts are only a way of a master account to track encoding bandwidth individually among sub accounts, they have not other access to create encoding jobs on their own or access control panel. To implement this actions you should recieve permission by administrator.
— AddTrialUser — add new Trial user. To implement this actions you should recieve permission by administrator.
— UpdateSubUser — replace information about existing user's data.
— DeleteSubUser — delete specified sub user.
— GetUserInfo — return information about selected user.
— GetSubUsers — return list of all users and all its data.
— GetASM — return average system metric information of selected user.
— GetStorageSpace — return storage space information of selected user.
— GetBandwidthStat — return used encoding traffic of selected user.
— GetBandwidthStatGroupDate - return encoding traffic of selected user. The traffic will be grouped by existing's dates.
action_user_id — an unique identifier of user. This field must be specified for the following actions: UpdateSubUser, DeleteSubUser, GetUserInfo, GetASM, GetStorageSpace, GetBandwidthStat, GetBandwidthStatGroupDate.
user_data — this data include the registration information (require), and the contact information(optional) about user. This field must be specified for the following actions: AddSubUser,AddTrialUser,UpdateSubUser.
Below you can see the require registration fields:
— for sub users - login, email, password.
— for Trial users - login, email, password, phone, first_name, last_name, company.
The optional contact data may be following :
phone, first_name, last_name, company, city, zip, country, state, addres
date_from, date_to — this field may be specified for the GetBandwidthStat and GetBandwidthStatGroupDate actions when you intend to recieve bandwidth's statistic specified interval. The date must be in format: YYYY-MM-DD.
XML formats for user's API request
AddTrialUser action
<?xml version="1.0"?> <query> <!-- Main fields --> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>addTrialUser</action> <user_data> <email>[Email]</email> <login>[Login]</login> <password>[Password]</password> <first_name>[FirstName]</first_name> <last_name>[LastName]</last_name> <phone>[Phone]</phone> </user_data> </query>
AddSubUser action
<?xml version="1.0"?> <query> <!-- Main fields --> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>AddSubUser</action> <user_data> <email>[Email]</email> <login>[Login]</login> <password>[Password]</password> <first_name>[FirstName]</first_name> <last_name>[LastName]</last_name> <phone>[Phone]</phone> </user_data> </query>
UpdateUser action
<?xml version="1.0"?> <query> <!-- Main fields --> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>UpdateSubUser</action> <action_user_id>[ActionUserID]</action_user_id> <user_data> <email>[New email]</email> <phone>[New phone]</phone> </user_data> </query>
DeleteUser action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>DeleteSubUser</action> <action_user_id>[ActionUserID]</action_user_id> </query>
GetUserInfo action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>GetUserInfo</action> <action_user_id>[ActionUserID]</action_user_id> </query>
GetSubUsers action
<?xml version="1.0"?>
<query>
<!-- Main fields -->
<userid>[UserID]</userid>
<userkey>[UserKey]</userkey>
<action>getsubusers</action>
</query>
GetASM action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>GetASM</action> <action_user_id>[ActionUserID]</action_user_id> </query>
GetStorageSpace action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>GetStorageSpace</action> <action_user_id>[ActionUserID]</action_user_id> </query>
GetBandwidthStat action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>GetBandwidthStat</action> <action_user_id>[ActionUserID]</action_user_id> <date_from>[YYYY-MM-DD]</date_from> <date_to>[YYYY-MM-DD]</date_to> </query>
Parameters description:
"date_to" and "date_from" the optional fields. You should use it if you intend to recieve bandwidth statistic into specified date interval.
GetBandwidthStatGroupDate action
<?xml version="1.0"?> <query> <userid>[UserID]</userid> <userkey>[UserKey]</userkey> <action>GetBandwidthStatGroupDate</action> <action_user_id>[ActionUserID]</action_user_id> <date_from>[YYYY-MM-DD]</date_from> <date_to>[YYYY-MM-DD]</date_to> </query>
Parameters description:
"date_to" and "date_from" the optional fields. You should use it if you intend to recieve bandwidth statistic into specified date interval.
Server Response XML format
The response for API request can vary depending on action:
AddTrialUser action
<?xml version="1.0"?>
<response>
<action>addtrialuser</action>
<status>Success</status>
<result>
<plan>Trial 1 GB</plan>
<user_id>1839</user_id>
<user_key>f851cae31d705c08a157b8f32f3cc121</user_key>
<message>The new trial user has been created</message>
</result>
</response>
AddSubUser action
<?xml version="1.0"?>
<response>
<action>addsubuser</action>
<status>Success</status>
<result>
<plan>[Plan]</plan>
<user_id>1840</user_id>
<user_key>38772a155045fc49a4b9f6d24efee4e6</user_key>
<message>The new sub user has been created</message>
</result>
</response>
UpdateUser action
<?xml version="1.0"?>
<response>
<action>updatesubuser</action>
<status>Success</status>
<result>
<user_id>1800</user_id>
<message>The user data was updated</message>
<email>[New Email]</email>
<country>[New Country]</country>
</result>
</response>
DeleteSubUser action
<?xml version="1.0"?> <response> <action>deletesubuser</action> <status>Success</status> </response>
GetUserInfo action
<?xml version="1.0"?>
<response>
<action>getuserinfo</action>
<status>Success</status>
<result>
<user_id>1800</user_id>
<ID>1800</ID>
<Login>[Login]</Login>
<FirstName>[FirstName]</FirstName>
<LastName>[LastName]</LastName>
<Email>[Email]</Email>
<UserKey>[UserKey]</UserKey>
<Country>[Country]</Country>
<Phone>[Phone]</Phone>
<Status>[Status]</Status>
</result>
</response>
GetSubUsers action
<?xml version="1.0"?>
<response>
<action>getsubusers</action>
<status>Success</status>
<result>
<user_id>6</user_id>
<user_0>
<ID>[UserID]</ID>
<Login>[Login]</Login>
<FirstName>[FirstName]</FirstName>
<LastName>[LastName]</LastName>
<Email>[Email]</Email>
<UserKey>[UserKey]</UserKey>
<Country>[Country]</Country>
<Phone>[Phone]</Phone>
<Status>[Status]</Status>
</user_0>
<user_1>
<ID>[UserID]</ID>
<Login>[Login]</Login>
<FirstName>[FirstName]</FirstName>
<LastName>[LastName]</LastName>
<Email>[Email]</Email>
<UserKey>[UserKey]</UserKey>
<Country>[Country]</Country>
<Phone>[Phone]</Phone>
<Status>[Status]</Status>
</user_1>
...
</result>
</response>
GetASM action
<?xml version="1.0"?>
<response>
<action>getasm</action>
<status>Success</status>
<result>
<user_id>[UserID]</user_id>
<encoding_success_rate>
<percentage>100</percentage>
</encoding_success_rate>
<queue_time>
<second>[average queue time in this month]</second>
</queue_time>
<processing_time>
<second>[average processing time in this month]</second>
</processing_time>
<connection_speed>
<kbs>[average connection speed]</kbs>
</connection_speed>
<encoding_bandwidth>
<gb>[average amount of encoding bandwidth]</gb>
</encoding_bandwidth>
</result>
</response>
GetStorageSpace action
<?xml version="1.0"?>
<response>
<action>getstoragespace</action>
<status>Success</status>
<result>
<user_id>[UserID]</user_id>
<gb>[Storage Space]</gb>
</result>
</response>
GetBandwidthStat action
<?xml version="1.0"?>
<response>
<action>getbandwidthstat</action>
<status>Success</status>
<result>
<user_id>[UserID]</user_id>
<date_from>[Date from]</date_from>
<date_to>[Date to]</date_to>
<in>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</in>
<out>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</out>
<turbo>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</turbo>
</result>
</response>
GetBandwidthStatGroupDate action
<?xml version="1.0"?>
<response>
<action>getbandwidthstatgroupdate</action>
<status>Success</status>
<result>
<user_id>[userID]</user_id>
<date_[date1]>
<in>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</in>
<out>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</out>
</date_[date1]>
<date_[date2]>
<in>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</in>
<out>
<bytes>[amount in bytes]</bytes>
<gb>[amount in gigabytes]</gb>
</out>
</date_[date2]>
...
</result>
</response>
Error Messages
Error Messages appears in the response if the action was failed.
Common Errors
No XML — No XML query provided in the request.
Wrong XML — The XML query provided in the request is not well-formed
Wrong query format — The XML does not contain <query> root element
Invalid action — The Action parameter is empty or has not in the list of allowed actions
Authentication Errors
Wrong User ID or Key — The user ID/userkey pair was not found
Add/Update sub users validation Errors
You have not permission for create trial user — You can not create any trial users.
You have not permission for create sub user — You can not create any sub users.
You have not permission to manage this user — You can manage only users who had been created by you.
action_user_id : This user not found - User having id which you set is not exist in our datebase.
action_user_id : This field is require - action_user_id is require for input if you manage sub user.
