Requesting an User list
support, ws.webtv, api, users, list
GET vars specific to this request:
Var | Value | Description |
go | users | The API section |
do | list | The API action |
Resulting Request URL:
The resulting request URL would be similar to this (don't forget to append the required info: key, timestamp, salt and signature):
https://....../api.php?go=users&do=list&{required information}
The following list filters are available by using POST vars.
TIP: You can use several filters at the same time.
Var | Value | Description |
fields | (string) "field1,field2,..." | Specify the fields to be included in the result. "*" = all fields (default). "field1, field2, field2" = subset of the fields [Recommended] - separated by comma. Available fields: id, status, access_level, login, password, alias, img_social, img_thumbnail, img_icon, avatar_display, name, surname, email, birthdate, address, country, telephone, web, social_page_facebook, social_page_googleplus, social_page_twitter, social_page_linkedin, social_page_flickr, social_page_tuenti, social_page_vkontakte, social_page_other, notes, activation_key, reg_timestamp, reg_useragent, reg_ip, last_login, session_id, session_time, general_cvp_expiration, profile_page_privacy, profile_page_about, profile_page_show_country, profile_page_show_web, profile_page_show_social, cms_access, date_lastmod, company, vat, postal_code, gender, last_ip, last_ip_update, reg_referer, img_player_logo, img_player_logo_url |
Paging options: |
||
resultsPerPageFilter | (int) n | Number of results per page |
current_page | (int) n | The number of the current page |
paging | (int) 0/1 | To enable/disable paging |
limit | (int) n | Results limit (only if resultsPerPageFilter is not specified and paging=0) |
Frequently used filters: |
||
statusFilter | (mixed) status | List Users that match the specified status. Available options: "any", 1 (active), 0 (inactive), 2 (pending verification), 11 (active session, logged in), 12 (inactive session, logged out), 13 (auto log out period) |
sortByFilter | (string) "option" | Sort the list. Available options: "reg_timestamp" (default), "email", "login", "alias", "id" |
idFilter | (string) "ID1,ID2,..." | List Users whose ID matches the specified ones (separated by comma). |
Access Level filters filters: |
||
accessLevelFilter | (int) access level | List Users whose access level is equal to the specified |
accessLevelFilterLowerThan | (int) access level | List Users whose access level is equal or lower than the specified Access levels: 0 = Webmaster 1 = Administrator 2 = Author 3 = Contributor 4,5 = Subscriber |
Search filters: |
||
search | (string) "term" | Term to search. Search is performed on login + alias + email fields. |
User Group filters - Since WS.WebTV 3.1 (R50) |
||
userGroupFilter | (mixed) "User Group ID" | Available options: "any", -1 (Orphaned - Users which are not associated with any Group) or User Group ID (Integer higher than 0) |
If the request was successful, you'll receive a response containing:
• list_total_found: The total amount of items found in the WebTV which matched the criteria (for paging purpose).
• list_total: The number of items in the returned list. This will normally match the limit or resultsPerPageFilter values.
• list: The item list.
Example:
{ "list_total_found" : "16" , "list_total" : 5, "list" : [{ "alias" : "Elisa" , "email" : "elisa@emaildomain.ext" , "id" : "77" , "login" : "elisita" , "url" : "http:\/\/......\/index.php\/portal\/user\/77\/elisita\/" }, { "alias" : "Mari" , "email" : "mari@emaildomain.ext" , "id" : "68" , "login" : "marian" , "url" : "http:\/\/......\/index.php\/portal\/user\/68\/marian\/" }, { "alias" : "Ralph" , "email" : "ralph@emaildomain.ext" , "id" : "33" , "login" : "ralph2000" , "url" : "http:\/\/......\/index.php\/portal\/user\/33\/ralph2000\/" }, { "alias" : "John" , "email" : "john@emaildomain.ext" , "id" : "32" , "login" : "johnny" , "url" : "http:\/\/......\/index.php\/portal\/user\/32\/johnny\/" }, { "alias" : "Allice" , "email" : "allice@emaildomain.ext" , "id" : "31" , "login" : "allice" , "url" : "http:\/\/......\/index.php\/portal\/user\/31\/allice\/" } } |
If the request failed (for example, if the Credential does not have permission to GET), you'll receive a response like the following:
{ "error" : "REQUEST_ERROR" , "error_long" : "Permission error: GET" } |
Possible Error Messages
Besides the general errors, this request can return the following errors:
• REQUEST_ERROR | No Users were found
Preparing GET and POST data.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | // The GET vars $GET_VARS = array ( "go" => "users" , "do" => "list" ); // The POST vars $POST_VARS = array ( "fields" => "id,email,alias,login" , // Include only id, email, alias and login "paging" => 1, // Allow paging "resultsPerPageFilter" => 5, // Return 5 results per page "current_page" => 1, // Return the page No. 1 "statusFilter" => "any" // Include Users with any status ); |
Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | // Collect the API Base URL and Credential info $API_KEY_ID = "1b323a1cb879fd4e66530fbad07a32ee" ; $API_SHARED_SECRET = "MWIzMjNhMWNiODc5ZmQ0ZTY2NTMwZmJhZDA3YTMyZWViOTQ3MDJiOGM2ZTU2NjE3" ; // keep this safe!!! // Generating salt and timestamp $salt = md5(mt_rand()); $timestamp = time(); $signature = base64_encode (hash_hmac( 'sha256' , $salt . $timestamp , $API_SHARED_SECRET , true)); // Generating the validation signature // - Default method: using base64_encode(hash_hmac(...)) $signature = base64_encode (hash_hmac( 'sha256' , $salt . $timestamp , $API_SHARED_SECRET , true)); // comment this line if using the next method // - Simplified method - available since v60: using md5(). // This method requires the variable $API_SIGNATURE_GENERATION_MODE = 1; in the config/Config.inc.php file. // $signature = md5($salt."-".$timestamp."-".$API_SHARED_SECRET); // you must "uncomment" this line when using the simplified method // Append the timestamp, salt, key and signature to the GET vars $GET_VARS [ "timestamp" ] = $timestamp ; // UTC timestamp $GET_VARS [ "salt" ] = $salt ; $GET_VARS [ "key" ] = $API_KEY_ID ; // The API Key ID: This is public and is used by the API to identify the application; $GET_VARS [ "signature" ] = $signature ; // Create the request URL. Please note that if you do not use PHP buit in function // to create the HTTP query then don't forget to URL encode the values $REQUEST_URL = $API_URL . "?" .http_build_query( $GET_VARS ); // The previous will build an URL like .../api.php?go=api_subject&do=api_action&etc... // Create a new cURL resource and set the appropriate options $ch = curl_init(); curl_setopt( $ch , CURLOPT_URL, $REQUEST_URL ); curl_setopt( $ch , CURLOPT_POST, true); curl_setopt( $ch , CURLOPT_RETURNTRANSFER, true); curl_setopt( $ch , CURLOPT_HEADER, false); curl_setopt( $ch , CURLOPT_POSTFIELDS, $POST_VARS ); // If your PHP host does not have a valid SSL certificate, you will need to turn off SSL // Certificate Verification. This is dangerous (!), and should only be done temporarily // until a valid certificate has been installed curl_setopt( $ch , CURLOPT_SSL_VERIFYHOST, false); // Turns off verification of the SSL certificate. curl_setopt( $ch , CURLOPT_SSL_VERIFYPEER, false); // Turns off verification of the SSL certificate. // Sending the request to the API $response = curl_exec( $ch ); // Processing the response if (! $response ) { echo 'API call failed' ; } else { print_r(json_decode( $response ,true)); } |