Introduction

Get leaderboard API will enable you to fetch the leaderboard information of a given leaderboard campaign which can be consumed on your application leaderboard dashboard to show the leaderboard status to the applicable customer.

You can consume this API for the following use cases:

Refresh the leaderboard rankings and points
To know the reward assigned to the leaderboard participants
To get the information of past leaderboard
To know the reward status of a leaderboard campaign

API details

API Endpoint: https://api.rehook.ai/campaigns/leaderboards/{campaign_id}

HTTP Method: GET

Prerequisites

API Key and Secret Key for your application
If you don't know the API key and secret key, please go to setting module on admin panel to view API details for your application. To know more about application setting, please visit Application setting
API key and secret key are auto generated and cannot be changed.
Leaderboard campaign to be created on rehook dashboard. To know more about how to configure the leaderboard campaign, please visit Leaderboard campaign setting

Authentication

You need to provide the API key and Secret of your application in every new request as Authorization. Rehook use Basic authentication method to authenticate the API calls.

Authorization	Value
Username	API key of your application
Password	Secret key of your application

Parameters

Path parameters

You have to provide the campaign_id as path parameter in the end point URL

Path URL: https://api.rehook.ai/campaigns/leaderboards/camp_29vfKDh0hHOgkOXdWoSyA

In above URL, value 'camp_29vfKDh0hHOgkOXdWoSyA' is the campaign id

parameter	Definition	In
campaign_id	campaign_id assigned by rehook for a leaderboard campaign created	Path

Query Parameters

You have to provide following query parameters

Parameter	Definition	value	use case
source_id	optional Rehook id or source id of your customer	KMN@123	To know the signed in user rank and reward
activity_id	optional unique id assigned by rehook for every recurrence of leaderboard	abc133nan	To fetch the past leaderboard information
page	optional page number (default value is 1) max of 20 records are returned in a single page.	2	To fetch the leaderboard records of next page.

Body Parameters

This API doesn't requires any body parameters.

Sample request

URL = https://api.rehook.ai/campaigns/leaderboards/camp_29vfKDh0hHOgkOXdWoSyA

source_id = KMN@123
page= 1
activity_id = ""

Complete response

{
  "number_of_participants": 5,
  "leaderboard_reward_given": false,
  "page": 1,
  "reward_brackets": [
    {
      "position": "1-2",
      "reward_value": "30"
    }
  ],
  "past_leaderboard_intervals": [
    {
      "recurrence_type": "daily",
      "recurrence_type_value": 1,
      "activit	y_id": "ldac_Q8zWIV2r7cmZ8akj0Fjd4",
      "start_date_time": "2023-09-18T12:26:13.656765Z",
      "end_date_time": "2023-09-18T18:29:58.999999Z",
      "status": "active"
    }
  ],
  "my_rank": {
    "source_id": "KMN@123",
    "rank": 1,
    "points": 4,
    "reward": "30"
  },
  "leaderboard": [
    {
      "source_id": "KMN@123",
      "rank": 1,
      "points": 4,
      "reward": "30"
    },
    {
      "source_id": "New_customer2",
      "rank": 2,
      "points": 3,
      "reward": "30"
    },
    {
      "source_id": "krishna123",
      "rank": 3,
      "points": 1,
      "reward": "0"
    },
    {
      "source_id": "New_customer3",
      "rank": 3,
      "points": 1,
      "reward": "0"
    },
    {
      "source_id": "New_customer4",
      "rank": 3,
      "points": 1,
      "reward": "0"
    }
  ]
}

Definition of response body fields

Fields without an object

Field	Definition	value
number_of_participants	Number of users participated in the current leaderboard campaign	20
leaderboard_reward_given	Leaderboard reward is assigned to the participants or not	boolean
page	Page number of leaderboard records	1

Rewards_brackets (array of object)

This object has the reward points to be assigned to the leaderboard participants based on their position bracket configured. you have to assign the reward to the customer on your application only if field 'leaderboard_reward_given' value is 'yes'. If this field value is 'No' but reward_value is given in this object, that means, this customer may get the potential reward.

example: for rank 1 : assign 80 points,for rank 2-3 : assign 30 points, for rank 6-7 : assign 20 points

Field	Definition	value
position	rank of participants (positions can be configured in range also, for ex: 1-4	1, 4-6
reward_value	reward points to be assigned for the position	30
is_minimum_value	Indicates if user requires min leaderboard score required to eligible for the reward bracket	boolean
value	minimum leaderboard score required to eligible for the reward bracket	50

past_leaderboard_intervals (array of objects)

Field	Definition	value
recurrence_type	Time frame to decide the final ranking and reset the leaderboard during campaign duration	daily/weekly/monthly/campaign_duration
recurrence_type_value	number of times leaderboard is reset	1
activity_id	unique id assigned by rehook for every recurrence of leaderboard	ldac_Q8zWIV2r7cmZ8akj0Fjd4
start_date_time	Start time of leaderboard recurrence	2023-09-18T12:26:13.656765Z
end_date_time	end time of leaderboard recurrence	2023-09-18T18:29:58.999999Z
active	status of past leaderboard	Active/Inactive

My rank (object)

Rehook will return the values in this object only if source_id is passed in the query parameter. This will help you to specifically know the rank of logged in user and show it on your application UI at applicable touch point.

Field	Definition	value
source_id	source_id passed in query parameter	KMN@123
rank	leaderboard rank of given source_id	2
points	leaderboard points achieved by the source_id	20
reward	reward points assigned to the given source_id	40

leaderboard (array of objects)

This is a array of objects having leaderboard details of all the participants. each array has leaderboard details of each source_id participated. Details are passed in the ascending order of the leaderboard ranks. you have to consume this object to refresh the leaderboard on your application.

"leaderboard": [
    {
      "source_id": "KMN@123",
      "rank": 1,
      "points": 4,
      "reward": "30"
    },
    {
      "source_id": "New_customer2",
      "rank": 2,
      "points": 3,
      "reward": "30"
    }

Field	Definition	value
source_id	source_id of participated customer	KMN@123
rank	leaderboard rank of customer	2
points	leaderboard points achieved by the customer	20
reward	reward points assigned to the customer	40

Success Response:

If API call is successful, then Rehook will return the following HTTP success code with response body as given above.

HTTP Code	Message
200	Ok

Error Responses

If API call is failed, then Rehook will return the following HTTP success code with response body as given below:

HTTP Code	Message
400	bad request

error response body

field name	description	example
Code	Error code	400
details	Error details	Given coupon code is wrong
message	error message	coupon_code not found
request_id	API request Id assigned by Rehook	abc_123

Below table shows possible list of cases with error messages

When leaderboard wrong campaign_id is passed in the path URL or not passed in the URL

leaderboard results will be null

{
  "number_of_participants": 0,
  "leaderboard_reward_given": false,
  "page": 1,
  "reward_brackets": null,
  "past_leaderboard_intervals": null,
  "my_rank": {
    "reward": ""
  },
  "leaderboard": null
}

When wrong source_id is passed in the query parameter

{
  "code": 404,
  "key": "not_found",
  "message": "Resource not found",
  "details": "Cannot find customer with source id kr",
  "request_id": "d6393d5b-45e4-9662-b5e5-d441ec0984dc"
}

When wrong activity_id is passed in the query parameter

leaderboard results will be empty

{
  "number_of_participants": 0,
  "leaderboard_reward_given": false,
  "page": 1,
  "reward_brackets": [
    {
      "position": "1-2",
      "reward_value": "30"
    }
  ],
  "past_leaderboard_intervals": [
    {
      "recurrence_type": "daily",
      "recurrence_type_value": 1,
      "activity_id": "ldac_Q8zWIV2r7cmZ8akj0Fjd4",
      "start_date_time": "2023-09-18T12:26:13.656765Z",
      "end_date_time": "2023-09-18T18:29:58.999999Z",
      "status": "active"
    }
  ],
  "my_rank": {
    "reward": ""
  },
  "leaderboard": null
}