Developer Documentation

Get top ranked users

get https://{host}/api_gateway/intouch-api-v3/v3.1/leaderboards/targetGroups/232?targetId=366&periodId=243&pageOffset=4&pageSize=10

The API fetches a ranked list of users who have achieved a target within a timeframe

👍

Note

For detailed information about our APIs and for hands-on testing, refer documentation on API overview and step-by-step guide on making your first API call.

Prerequisites

  • Authentication: Basic/OAuth authentication
  • Default access group
  • Enable leaderboards for the organisation.
  • Create a target milestone or streak.
  • Enable leaderboards for the milestone or streak

Resource Information

URIapi_gateway/intouch-api-v3/v3.1/leaderboards/targetGroups/{targetGroup}
HTTP MethodGET
PaginationYes
Rate limit informationNA

API Endpoint Example

https://eu.api.capillarytech.com/api_gateway/intouch-api-v3/v3.1/leaderboards/targetGroups/232?targetId=366&periodId=243&pageOffset=4&pageSize=10

Headers

HeaderDescription
DATA-SCOPE-ORGList of Organisation IDs
DATA-SCOPEScopes define what data can be accessed using the API. You can use scopes to control access to data from a parent or child organisation. Defining a scope ensures that the response contains only data from the respective organisation. Supported headers: SELF, OTHER and ALL. Refer to connected orgs data scopes for more information.

Request path parameters

Request path parameters

ParametersTypeDescription
targetGroupsIntegerThe ID of the target group. A target group is an entity that contains targets.

Request query parameters

Parameters (Parameters marked with * sign are mandatory)TypeDescription
targetId*LongThe ID of the target. A target is a set of conditions or rules that need to be met to achieve a specific goal.
periodIdLongThe period ID of the target. A period is a set of parameters that define the timeframe for a target. If periodId is not provided, the current period of the target group will be used.
pageSizeIntegerThe number of results required.
For example, to view the top five ranks only, set the value to 5.
pageOffsetIntegerThe start page from which data retrieval starts. This value should not be negative.

For example, a value of 5 indicates that data retrieval will begin from the 4th page.
pageLimitIntegerNumber of pages from which results are displayed.
A maximum of 100 pages can be viewed in one request.

Response body


    "pagination": {
        "limit": 3,
        "offset": 0,
        "total": 4527
    },
    "data": {
        "lastSyncTime": "2024-06-24T17:37:00.000IST",
        "targetGroupId": 232,
        "targetGroupName": "Target",
        "periodId": 243,
        "periodRefCode": "target_period",
        "targetRuleId": 366,
        "targetRuleName": "target1",
        "rankings": [
            {
                "rank": 1,
                "userId": 381329844,
                "achievedValue": 21000,
                "lastActivityTime": "2022-11-25T21:44:40.000IST",
                "userEnrichmentDetails": {
                    "birthday": "NOT-CAPTURED",
                    "gender": "Male",
                    "mobile": "918828069049",
                    "last_name": "Emf_lname_918828069049",
                    "first_name": "Emf_fname_918828069049",
                    "anniversary": "NOT-CAPTURED",
                    "email": "[email protected]"
                }
            },
            {
                "rank": 2,
                "userId": 381332324,
                "achievedValue": 21000,
                "lastActivityTime": "2022-11-29T00:14:48.000IST",
                "userEnrichmentDetails": {
                    "birthday": "NOT-CAPTURED",
                    "gender": "Male",
                    "mobile": "918969294257",
                    "last_name": "Emf_lname_918969294257",
                    "first_name": "Emf_fname_918969294257",
                    "anniversary": "NOT-CAPTURED",
                    "email": "[email protected]"
                }
            },
            {
                "rank": 3,
                "userId": 381333386,
                "achievedValue": 21000,
                "lastActivityTime": "2022-11-29T13:48:28.000IST",
                "userEnrichmentDetails": {
                    "birthday": "NOT-CAPTURED",
                    "gender": "Male",
                    "mobile": "918424528743",
                    "last_name": "Emf_lname_918424528743",
                    "first_name": "Emf_fname_918424528743",
                    "anniversary": "NOT-CAPTURED",
                    "email": "[email protected]"
                }
            }
        ]
    },
    "errors": [],
    "warnings": []
}

Response parameters

ParametersTypeDescription
paginationObjectObject containing pagination details.
– limitStringNumber of entries per page.
– offsetStringPage number of the current result set.
– totalStringTotal number of entries.
dataObjectObject containing details of the leaderboard.
– lastSyncTimeStringTime when data was updated Supported format: YYYY-MM-DDTHH:MM:SS.000z.
The system uses the organisation time zone to display.
–targetGroupIdIntegerThe unique ID of the target group. A target group contains an array of targets.
–targetGroupNameStringUnique name of the target group.
–periodIdIntegerUnique ID of the target period. A period is a set of parameters that define the timeframe for a target.
–periodRefCodeStringUnique name of the target period.
–targetRuleIdIntegerUnique ID of the target rule. A target rule is a set of parameters that define the rules for achieving a target.
–targetRuleNameStringUnique name of the target rule.
–rankingsObjectObject containing user ranking details.
–rankIntegerRank of the user.
–userIdIntegerUnique identifier of the customer.
–achievedValueIntegerThe achieved value of the customer in the period.
Example: If the customer has earned 5000 points, the value will be 5000.
–lastActivityTimeStringLast activity time Supported format: YYYY-MM-DDTHH:MM:SS.000z.
--mobileIntegerMobile number associated with the user.
–userEnrichmentDetailsObjectAn object containing information related to the user.
--birthdayStringBirthday of the user.
genderStringGender of the user.
--last_nameStringLast name of the user.
--first_nameStringFirst name of the user.
--anniversaryStringAnniversary date of the user.
--emailStringEmail address associated with the user.

API-specific warnings and errors

Error CodeDescriptionReason
-Page offset can not be in negative, fetching the first page by defaultThe page offset value is negative.
-Page Size can not be more than 100, capping the page size to 100The page size value is more than the supported limit of 100.
310133Leaderboards are not enabled for the following orgsLeaderboards are not enabled for the organisation.
310017Target group not found or deactivatedThe target group passed is either invalid or currently inactive.
310134Leaderboard is not enabled for the target groupLeaderboard is not enabled for the requested target group.
310079target rule id doesn't belong to target groupThe target rule ID passed does not belong to the target group or is invalid.
310118Target Period not found for the targetThe target period ID passed does not belong to the target group or is invalid or does not exist.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!