Add Badge Requirement

From KickApps Documentation

Contents 1 Overview 2 Request URL 3 Request Parameters 4 Response 5 Response Parameters 6 List of KickApps API Calls

Overview

This method is an admin method that adds badge requirements into the system. A badge requirement consists of a badge (based on badgeId) and an action (based on actionId) and the number of time the action needs to occur in specific areas (aka locations) of the site to receive the badge. A single badge can have multiple requirements, which need to be added into the system with multiple calls to "Add Badge Requirement". Only published requirements should be considered; if the requirement isn’t published, it’s not a requirement to consider when awarding a badge. If a requirement’s published status is changed to false, the accumulated user actions should be re-evaluated to determine if that requirement’s (published = true) badge should be awarded to any of these users.

Note: When a Badge requirement is added, all users need to be reevaluated to determine if any should be awarded the badge based on the requirements creation. A badge that’s been awarded should never be taken away from a user due to a badge requirements change. Possible side affect is that as requirements are being added, but not all have been added, a user will be awarded a badge based on the subset of requirements currently defined (this is addressed by having the badge’s published = false when requirements are being added – to avoid premature evaluation).

Request URL

http://api.kickapps.com/rest/badge/requirement/add/{as}

Request Parameters

Required

• t - the user token generated via the "Create Token" API call. Must be a webmaster / moderator token.
• as - The site Id to search. as is unique for each of the affiliate's sites.
• badgeId – The badge ID of an existing badge in the system.
• actionId - The ID of an existing action in the system.
• 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.
• quantity – Integer from 1-N containing the number of times this action must occur for a user to meet this action’s requirement towards earning this badge.

Optional

• callback. String. Optional. The name of your JavaScript callback function.
• published – Boolean value that indicates whether or not the requirement is active/ published; can be awarded. (true, false - Defaults to false).

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, "added": True, "requirementId":"1234"}

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

Response Parameters

• status – 1 on success and -1 on error.
• error – A message indicating the error condition
• errorId – A numeric reference to the error condition
• requirementId – The ID of the Badge Requirement just added into the system.
• added – Boolean value indicating Badge Requirement was successfully added.

Error codes:

• 1 = invalid token
• 7 = invalid value for published (must be true or false)
• 8 = location cannot be null or blank
• 9 = Invalid badgeId or badgeId missing
• 10 = invalid actionId or actionId missing
• 11 = quantity must be a positive integer or missing
• 12 = published must be set to true or false (Note: This condition is only evaluated when the optional published parameter is provided.)
• 18 = Insufficient user permissions for this operation
• 19 = Invalid requirementId (Note: You can’t edit a requirement that doesn’t exist.)
• 20 = location cannot exceed 64 characters
• 23 = Badge requirement already exists
• 44 = token required

List of KickApps API Calls

API Change Log Create Token Call Social Networking Retrieve Member Profile Add Or Remove Member As Friend Get A Member's Friends, Fans, and "Fan Of" Retrieve User by Facebook Id KickConnect Assign Member Profile Photo Remove Member Profile Photo Member Profile Edit/Update SSO Method Member Register SSO Method Combined Member Sign On and Register SSO Method Member Change Username SSO Method Member Change Email SSO Method OpenAuth Create Message Board Media Sharing Upload Media Retrieve Media Meta Data Edit Media Meta Data Delete Member Media Retrieve Play Page Retrieve Member Media Retrieve Member's Favorite Media Retrieve Related Media Member Favorite Media Check Email Media Add Or Remove Media Flag Add To Or Remove From Favorites Geographic Values for Media Uploads Get Video Thumbnails Set Video Thumbnail Blogging Add Blog Post Edit Blog Post Comments and Rating Add External Media Retrieve External Media Edit External Media Add Group Comment Add Media Comment Add Profile Comment Retrieve Comments Search Comments Edit Comment Edit Group Comment Delete Comment Delete Group Comment Flag Comment Flag Group Comment Rate Media Retrieve Media Ratings Retrieve Media Rated By Member Retrieve Likes By User ID Search Search Media Sets Add Media Set Edit Set Retrieve Set Delete Set Add Media to Set Remove Media from Set Groups Add Group Retrieve Group Page Edit Group Request A Group Add/Remove Media To Group Add/Remove Member To Group Retrieve Member Groups Upload Group Photo Remove Group Photo Polls Creating Polls Using the Tag API’s

Badges Add Badge Edit Badge List Badges Add Action List Actions Add Badge Requirement Edit Badge Requirement List Badge Requirements Add User Action Retrieve User's Badges Retrieve User's Badge Status Retrieve Super Fans Get Super Fan Ranking Set Super Fan Badge Criteria Categories and Tags Add Tags To Media, Members and Groups Remove Tags From Media, Members and Groups Add Admin Tags To Media, Members and Groups Remove Admin Tags From Media, Members and Groups Retrieve Admin Tags Retrieve Tag Count Add Category Edit Category Retrieve Category Delete Category Add Custom Meta Data Remove Custom Meta Data Retrieve Custom Meta Data Member and Media Management Approve Member Reject Member Approve Member Media Reject Member Media Delete Member Media Retrieve Pending Media Retrieve Active Member Count Retrieve Site Settings CRM Connectors KickApps SugarCRM Connector KickApps Salesforce Connector CRM Connectors (COMING SOON!!) IBM Websphere Microsoft Dynamic CRM NetSuite Oracle CRM On Demand Oracle E-Business Suite CRM PeopleSoft Enterprise CRM Oracle Siebel CRM SAP CRM Sugar Professional Maximizer CRM Pegasystems Customer Process Manager

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.