Documentation

Retrieve User's Badges

From KickApps Documentation

Jump to: navigation, search

Contents

Overview

This method returns a list of published badge's for a given userId and location.


Request URL 

http://api.kickapps.com/rest/user/badges/get/{as}


Request Parameters

Required

  • t - the user token generated via the "Create Token" API call.
  • as - The site Id to search. as is unique for each of the affiliate's sites.
  • user_id – the ID of the user whose badges are being retrieved.


Optional

  • location – A location identifier that corresponds to a page / area within the community. When not provided, all locations are returned. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.
  • callback. String. Optional. The name of your JavaScript callback function.
  • pgNum. The current page number in the search results. For your first call, set pgNum to "1". For subsequent calls, set pgNum to the page you want to display. If not provided, this value is defaulted to 1.
  • pageSize. The number of results to display on each page. Max pageSize is "1000". If not provided, this value is defaulted to 10.

Response

Note: if callback is provided as an optional argument, the results illustrated below will be returned within the callback string provided for execution of a JavaScript function; e.g. callback=”MyCallbackFunc” will return something similar to: 

MyCallbackFunc({…the success or failure response contained in curly braces you see below…});

Success:
{
   "status":1,
   "totSize":100,
   "userId":"1234",
   
   "badges":[
      {
         "location":"XXXX",
         "badgeId":"1",
         "name":"Good Badge",
         "verbosename":"Good Badge, good, good badge",
         "url":"http://www.kickapps.com/image1.png",
         "link":"http://someurlontheweb.com"
      },
      {
         "location":"XXXX",
         "badgeId":"2",
         "name":"Awesome Badge",
         "verbosename":"Awesome Badge, extremely awesome",
         "url":"http://www.kickapps.com/image2.png" ,
         "link":"http://someurlontheweb.com"
      }
   ]
}

Failure:  {"status": -1, "errorId": "123", "error": "Error Message"}


Response Parameters

  • status – 1 on success and -1 on error.
  • totSize – Indicates the total number of badges this user has earned for this location.
  • error – A message indicating the error condition
  • errorId – A numeric reference to the error condition
  • userId – the ID of the user whose badges are being retrieved.
  • location – A location identifier that corresponds to a page / area within the community. For this iteration of the API it is assumed that Client will handle creation of these identifiers in their existing CMS system.
  • badges – The set of all badges for a given userId and location:
  • badgeId – The ID of the badge.
  • name – The Name of the badge.
  • verbosename – The Verbose Name of the badge.
  • url – A URL to the badge's image file.
  • link – A link/url associated with this badge.


Error codes:

  • 1 = invalid token
  • 8 = location cannot be blank
  • 13 = invalid userId
  • 16 = Invalid pgNum
  • 17 = Invalid pageSize
  • 20 = location cannot exceed 64 characters
  • 25 = pageSize cannot exceed 1000
  • 44 = token required

List of Kit Cloud Social API Calls


Note: Occasionally (and without advanced warning) we modify our API calls by adding new parameters in the response payload. Please keep this in mind when designing your strategy for parsing our responses.

Retrieved from "http://www.kickapps.com/documentation/index.php/Retrieve_User%27s_Badges"