Add-ons

  2. Home
  4. Docs
  6. Add-ons
  8. BadgeOS REST API

BadgeOS REST API

The BadgeOS Rest API Add-on introduces REST API endpoints to extend interactions between your BadgeOS environment and external applications, using the official WordPress REST API. In this article, we’ll walk you through the instructions you should follow to install and use REST API endpoints with BadgeOS. You can find more information on WordPress Rest API, endpoints, CRUD operations, and authorization on the official  REST API handbook.

Table Of Contents

  1. Install the BadgeOS REST API Add-on
  2. Authorize REST API
  3. Create an API Key
  4. BadgeOS Endpoints
  5. BadgeOS Trigger Parameters

 

1. Install the BadgeOS REST API Add-on

  • Install and Activate the BadgeOS plugin.
  • Install and Activate the BadgeOS REST API Add-on.
  • Navigate to BadgeOS > Settings. A “REST API” tab will appear on the BadgeOS Settings page. Here you will see three options:

Enable BadgeOS API: This option lets you enable or disable API.

Enable API Keys: This lets you enable or disable the API keys. (If enabled, you’ll have to create an API key first in order to make use of it.)

API Endpoint: This lets you configure and customize the API endpoints.

 

2. Authorize REST API

Rest API works with an API key to secure and authorize endpoints. API can work with and without the API key based on the selected Badgeos API Settings. After setting up the authorization key, the endpoints’ URL will include the authorization key at the end of the URL as seen here:

https://yourwebsite.com/wp-json/badgeos-api/awarded-ranks/?apikey=abcd123efgh456ijklm789mjhvg

(In this example “?apikey=abcd123efgh456ijklm789mjhvg” is the authorization key.)

 

3. Create an API Key

After enabling the use of API Keys from the BadgeOS Settings page, follow these instructions:

  • Navigate to BadgeOS > API keys from the WP Dashboard. Click on “Add New”.
  • Add a key title and determine the API Key owner in the user field. 
  • Set the key’s permission. The permission options are:

Read: allows the key to fetch data.

Read/Write: allows the key to fetch data and award and revoke achievements.

Admin Read/Write: allows the key to fetch data and award and revoke achievements, ranks, and point types without the “trigger name” parameters.

  • Set the allowed domain. Leave blank if you don’t want to restrict your key to be accessible from any domain.
  • Leave the API Key as blank and publish the post.
  • When the page is refreshed, your API Key will be present in the API Key field, ready to be copied and used elsewhere.

4. BadgeOS Endpoints

All BadgeOS post types, which include achievements, ranks, and point types, have endpoints. 

The following are Endpoint examples:

  • /wp-json/badgeos-api/get-achievements-types/
  • /wp-json/badgeos-api/get-rank-type-by-id/ (rank type ID)
  • /wp-json/badgeos-api/get-point-type-by-id/ (point type ID)

Note: Endpoints contain “badgeos-api” (set by default) as the base of the API endpoint URL.

Achievement Endpoints

Getting all Achievement Types /wp-json/badgeos-api/get-achievements-types/
Getting Achievement Types By ID /wp-json/badgeos-api/get-achievement-type-by-id/ (achievement type’s ID)
Getting Achievements By ID /wp-json/badgeos-api/get-achievement-by-id/(achievement’s ID)
Getting all Achievements /wp-json/badgeos-api/get-all-achievements
Getting all Awarded Achievements  /wp-json/badgeos-api/awarded-achievements
To Award any Achievement  /wp-json/badgeos-api/award-achievement
To Award any Achievement (Admin Read/Write Access) /wp-json/badgeos-api/admin-award-achievement/
To Revoke any Achievement /wp-json/badgeos-api/revoke-achievement
To get steps that are associated with a specific trigger by trigger name /wp-json/badgeos-api/steps-by-trigger/ (trigger’s name)

Get All Achievement Types

  • EndPoint: /wp-json/badgeos-api/get-achievements-types/
  • DO: Retrieve all achievement types. 
  • Method: GET
  • Available Parameters and Arguments: No
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-achievements-types/?apikey=abcd123efgh456ijklm789mjhvg 

Get All Achievement Types By ID

  • EndPoint: /wp-json/badgeos-api/get-achievement-type-by-id/(achievement type’s ID)
  • DO: Retrieve all achievement types by ID. 
  • Method: GET
  • Available Parameters and Arguments: (achievement type’s ID)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-achievement-type-by-id/31?apikey=abcd123efgh456ijklm789mjhvg

Get All Achievements By ID

  • EndPoint:  /wp-json/badgeos-api/get-achievement-by-id/(achievement’s ID)
  • DO: Retrieve all achievements by ID. 
  • Method: GET
  • Available Parameters and Arguments: (achievement’s ID)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-achievement-by-id/23?apikey=abcd123efgh456ijklm789mjhvg 

Get All Achievements

  •  EndPoint: /wp-json/badgeos-api/get-all-achievements
  • DO: Retrieve all achievements. 
  • Method: GET, POST
  • Available Parameters:

achievements_per_page

Selects how many achievements to show on 1 page ( default = 10 )
achievements_page Selects the number of page  ( default’= 1 )
achievements_search Achievements search (default = false )
achievements_order_by Achievement’s Order ( default = false )
achievements_order Achievement’s Display order ( default = ASC ),
achievements_status Achievement’s status (default = publish)
achievements_types Achievement type search by name (default = ‘ ’ )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-all-achievements?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Getting All Awarded Achievements 

  • EndPoint: /wp-json/badgeos-api/awarded-achievements
  • DO: Retrieve all awarded achievements. 
  • Method: GET, POST
  • Available Parameters:
achievement_id Achievement’s ID ( default = 0 )
user_id User ID (default = 1 )
achievement_type Achievement type by name ( default = ‘ ’ )  
start_date Start Date (default = ’ ‘ ) (format: yyyy-mm-dd Hrs:Mins)
end_date End Date (default = ’ ’ ) (format: yyyy-mm-dd Hrs:Mins)
no_step No Steps (default = true)
since Since (default = 0 ) (format: yyyy-mm-dd Hrs:Mins)
pagination Paginate the results (default = false)
page Page Number (default = 1 )
limit Limit per page (default = 10)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/awarded-achievements?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Award Achievement

  • EndPoint: /wp-json/badgeos-api/award-achievement
  • DO: It awards achievements. 
  • Method: GET, POST
  • Available Parameters:  
trigger_name Name of the trigger (‘default’ => ”)
user_id The ID of the user to be awarded (default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/award-achievement?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Award Achievement (Admin Read/Write Access)

  • EndPoint: /wp-json/badgeos-api/admin-award-achievement/
  • DO: It awards achievements. 
  • Method:  POST
  • Available Parameters:
user_id The ID of the user to be awarded (default = 0 )
achievement_id Achievement’s ID ( default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api//admin-award-achievement/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Revoke Achievement

  • EndPoint: /wp-json/badgeos-api/revoke-achievement
  • DO: It revokes achievements. 
  • Method: GET, POST
  • Available Parameters:  
achievements_id Achievement’s ID ( default = 0 )
entry_id ID of earned achievement (default = 0 )
user_id The ID of the user to be awarded (default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/revoke-achievement?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Get Steps associated with a Specific Trigger

  • EndPoint: /wp-json/badgeos-api/steps-by-trigger/ (trigger name)
  • DO: Retrieve all steps that are associated with a specific trigger. 
  • Method: GET, POST
  • Available Parameters and Arguments: (trigger name)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/steps-by-trigger/(trigger name)?apikey=abcd123efgh456ijklm789mjhvg

 

Ranks Endpoints

Getting all Rank Types /wp-json/badgeos-api/get-rank-types/
Getting Rank Types By ID /wp-json/badgeos-api/get-rank-type-by-id/(rank type’s ID)
Getting Ranks By ID /wp-json/badgeos-api/get-rank-by-id/(rank’s ID)
Getting all Ranks /wp-json/badgeos-api/get-all-ranks/
Getting all Awarded Ranks /wp-json/badgeos-api/awarded-ranks/
To Award any Rank /wp-json/badgeos-api/award-rank
To Award any Rank (Admin Read/Write Access) /wp-json/badgeos-api/admin-award-rank/
To Revoke any Rank /wp-json/badgeos-api/revoke-rank
To get steps that are associated with a specific trigger by trigger name /wp-json/badgeos-api/rank-steps-by-trigger/ (trigger’s name)

Get All Rank Types

  • EndPoint: /wp-json/badgeos-api/get-rank-types/
  • DO: Retrieve all rank types. 
  • Method: GET
  • Available Parameters and Arguments: No
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-rank-types/?apikey=abcd123efgh456ijklm789mjhvg 

Get All Rank Types By ID

  • EndPoint:  /wp-json/badgeos-api/get-rank-type-by-id/ (rank type ID)
  • DO: Retrieve all rank types by ID. 
  • Method: GET
  • Available Parameters and Arguments: (rank type ID)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-rank-type-by-id/33?apikey=abcd123efgh456ijklm789mjhvg

Get Ranks By ID

  • EndPoint:  /wp-json/badgeos-api/get-rank-by-id/(rank ID)
  • DO: Retrieve all ranks by ID. 
  • Method: GET
  • Available Parameters and Arguments: (rank ID)
  • Eg:https://yourwebsite.com/wp-json/badgeos-api/get-rank-by-id/5?apikey=abcd123efgh456ijklm789mjhvg 

Getting all Ranks

  • EndPoint: /wp-json/badgeos-api/get-all-ranks/
  • DO: Retrieve all ranks.
  • Method: GET, POST 
  • Available Parameters:
ranks_per_page Selects how many ranks to show per page (default = 10)
ranks_page Selects the number of page (default = 1)
ranks_search Ranks search  (default = false  )
ranks_order_by Rank’s Order ( default = false )
ranks_order Rank’s Display order ( default = ASC )
ranks_status Rank’s status (default = publish)
ranks_types Rank type search by name (default = ‘ ’ )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-all-ranks/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Getting all Awarded Ranks

  • EndPoint: /wp-json/badgeos-api/awarded-ranks/
  • DO: Retrieve all awarded ranks. 
  • Method: GET, POST
  • Available Parameters:
rank_id Rank’s ID ( default = 0 )
user_id User ID (default = 0 )
rank_type Rank type by name ( default = ‘ ‘  )
start_date Start Date(default = ‘ ’ ) (format: yyyy-mm-dd Hrs:Mins)
end_date End Date (default = ’ ’ ) (format: yyyy-mm-dd Hrs:Mins)
no_step No Steps (default = true)
since Since (default = 0 ) (format: yyyy-mm-dd Hrs:Mins)
pagination Paginate the results (default = false)
page Page Number (default = 1 )
limit Limit per page (default = 10)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/awarded-ranks/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Award Rank

  • EndPoint: /wp-json/badgeos-api/award-rank
  • DO: It awards ranks.
  • Method: GET, POST 
  • Available Parameters:  
trigger_name Name of the trigger (default = ‘ ’ )
user_id The ID of the user to be awarded (default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/award-rank?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Award Rank (Admin Read/Write Access)

  • EndPoint: /wp-json/badgeos-api/admin-award-rank/
  • DO: It awards ranks.
  • Method: POST 
  • Available Parameters:  
user_id The ID of the user to be awarded (default = 0 )
rank_id Rank’s ID ( default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/admin-award-rank/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Revoke Rank

  • EndPoint: /wp-json/badgeos-api/revoke-rank
  • DO: It revokes ranks. 
  • Method: GET, POST
  • Available Parameters:  
rank_id The ID of the rank to be awarded (default = 0 )
user_id The ID of the user to be awarded (default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/revoke-rank?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Get Steps associated with a Specific Trigger

  • EndPoint: /wp-json/badgeos-api/rank-steps-by-trigger/ (trigger name)
  • DO: Retrieve all steps of rank that are associated with a specific trigger. 
  • Method: GET, POST
  • Available Parameters and Arguments: (trigger name)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/rank-steps-by-trigger/(trigger name)?apikey=abcd123efgh456ijklm789mjhvg

Point Types Endpoints

Getting all Point Types /wp-json/badgeos-api/get-point-types
Getting Point Types By ID /wp-json/badgeos-api/get-point-type-by-id/(point type’s ID)
Getting Point Type’s Balance By Point type ID and User ID /wp-json/badgeos-api/get-point-balance/(point type’s ID)/(user’s id)
Get Steps of Awarding Point type associated with a Specific Trigger /wp-json/badgeos-api/award-point-steps-by-trigger/ (trigger’s name)
Get Steps of Deducting Point type associated with a Specific Trigger /wp-json/badgeos-api/deduct-point-steps-by-trigger/(trigger’s name)
To Award points /wp-json/badgeos-api/award-point/
To Award points (Admin Read/Write Access) /wp-json/badgeos-api/admin-award-point/
To deduct points /wp-json/badgeos-api/deduct-point
To deduct points (Admin Read/Write Access) /wp-json/badgeos-api/admin-deduct-point/

Get All Point Types

  • EndPoint: /wp-json/badgeos-api/get-point-types/
  • DO: Retrieve all point types. 
  • Method: GET
  • Available Parameters and Arguments: No
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-point-types?apikey=abcd123efgh456ijklm789mjhvg 

Get All Point Types By ID

  • EndPoint:  /wp-json/badgeos-api/get-point-type-by-id/ (point type ID)
  • DO: Retrieve all point types by ID. 
  • Method: GET
  • Available Parameters and Arguments: (point type ID)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-point-type-by-id/ 39?apikey=abcd123efgh456ijklm789mjhvg

Get Points Balance of a User

  • EndPoint:  /wp-json/badgeos-api/get-point-balance/type_id/user_id
  • DO: Retrieve points balance by point type ID and user ID. 
  • Method: GET
  • Available Parameters and Arguments: type ID (point type ID) and user ID
  • Example: https://yourwebsite.com/wp-json/badgeos-api/get-point-balance/39/3?apikey=abcd123efgh456ijklm789mjhvg 

Get Steps of Awarding Point type associated with a Specific Trigger

  • EndPoint: /wp-json/badgeos-api/award-point-steps-by-trigger/ (trigger name)
  • DO: Retrieve all steps of awarding point type associated with a specific trigger. 
  • Method: GET, POST
  • Available Parameters and Arguments: (trigger name)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/award-point-steps-by-trigger/(trigger name)

Get Steps of Deducting Point type associated with a Specific Trigger

  • EndPoint: /wp-json/badgeos-api/deduct-point-steps-by-trigger/ (trigger name)
  • DO: Retrieve all steps of deducting point type associated with a specific trigger. 
  • Method: GET, POST
  • Available Parameters and Arguments: (trigger name)
  • Example: https://yourwebsite.com/wp-json/badgeos-api/deduct-point-steps-by-trigger/(trigger name) 

Award points

  • EndPoint: /wp-json/badgeos-api/award-point/
  • DO: To award points. 
  • Method: GET, POST
  • Available Parameters:
trigger_name Name of the trigger (default = ‘ ‘ )
user_id ID of the user to be awarded (default = 0 )
  • Example:https://yourwebsite.com/wp-json/badgeos-api/award-point/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Award points (Admin Read/Write Access)

  • EndPoint: /wp-json/badgeos-api/admin-award-point/
  • DO: To award points. 
  • Method:  POST
  • Available Parameters:
user_id ID of the user to be awarded (default = 0 )
credit_id ID of the point type (default = 0 )
credit Amount of points you want to award
  • Example: https://yourwebsite.com/wp-json/badgeos-api/admin-award-point/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Deduct points

  • EndPoint: /wp-json/badgeos-api/deduct-point/
  • DO: To deduct points. 
  • Method: GET, POST
  • Available Parameters:
trigger_name Name of the trigger (default = ‘ ‘ )
user_id ID of the user to be awarded (default = 0 )
  • Example: https://yourwebsite.com/wp-json/badgeos-api/deduct-point/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

Deduct points (Admin Read/Write Access)

  • EndPoint: /wp-json/badgeos-api/admin-deduct-point/
  • DO: To deduct points. 
  • Method:  POST
  • Available Parameters: 
user_id ID of the user to be awarded (default = 0 )
credit_id ID of the point type (default = 0 )
credit Amount of points you want to deduct
  • Example: https://yourwebsite.com/wp-json/badgeos-api/admin-deduct-point/?apikey=abcd123efgh456ijklm789mjhvg  (with form-data)

5. BadgeOS Triggers For Trigger_Name Parameter

The following is the list of trigger names for the default BadgeOS triggers. These will be used to determine the name of the trigger when the parameter “trigger_name” is used.

BadgeOS Triggers trigger_name
Log in to Website badgeos_wp_login
Not Login for X days badgeos_wp_not_login
Comment on a post badgeos_new_comment
Comment on a specific post badgeos_specific_new_comment
Publish a new post badgeos_new_post
Visit a Post badgeos_visit_a_post
Publish a new page badgeos_new_page
Visit a Page badgeos_visit_a_page
Register to the website user_register
Daily visit website badgeos_daily_visit
Specific Achievement of Type specific-achievement
Any Achievement of Type any-achievement
All Achievements of Type all-achievements