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:

1. Refresh the leaderboard rankings and points
2. To know the reward assigned to the leaderboard participants
3. To get the information of past leaderboard
4. 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

1. API Key and Secret Key for your application
2. 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
3. API key and secret key are auto generated and cannot be changed.
4. 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.

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

Query Parameters

You have to provide following query parameters

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

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

past_leaderboard_intervals (array of objects)

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.

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"
    }

Success Response:

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

Error Responses

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

error response body

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
}