CROWDMANAGERCROWDMANAGER

Top Positions

Description

A TopPosition resource represents a Participant in the Leaderboard area, along with his score and position. This endpoint allows customers to fetch TopPositions for selected Leadeboards.

Fields

Name Description Type Supported Methods
ParticipantName Participant's Nickname with fallback to FirstName + LastName first letter, with fallback to Anonymous in case all fields are empty string GET
CustomerProfileId Matching CustomerProfile Id of given Participant long GET
Score Total score gained in given Leaderboard. nullable decimal GET
Position Current Leaderboard position nullable long GET
PreviousPosition Previous Leaderboard position, which means before last Leaderboards recalculation, usually previous day nullable long GET

Fetch TopPositions

Endpoint

GET https://api.crowdmanager.io/v2/{orgId}/mypage/leaderboards/toppositions

Warning

  1. The endpoint uses application/json content type instead of application/vnd.api+json used by most other endpoints in the API. The Accept header is entirely optional.
  2. Leaderboard Season has to be configured for given customer.

Example

Request

GET https://api.crowdmanager.io/v2/{orgId}/mypage/leaderboards/toppositions?
    leaderboardseasonid={id}
    &demographicValue={value}
    &intervalId={id}
    &positionCount={count}
Authorization: Basic aaabbbccc111222333
Content-Type: application/json
Parameter Description Default Type/Supported Values Supported Methods
leaderboardseasonid Leaderboards Season Id in the system the most current Leaderboard Season long GET
demographicValue DemographicField value for the given DemographicFieldId of LeaderboardSeason general (non-demographics) Leaderboard string GET
intervalId Leaderboards Interval Id in the system global (non-interval) Leaderboard long GET
positionCount Count of positions returend (see below) 10 int <1,100> GET

Most current Leaderboard Season - the one that is currently active, or the newest one that was active in the past, or the future one that will be active the soonest. Position Count - All positions lower than or equal to the count are returned. This mean that more participants than the count would be returned in the special case where position is held by more than one person.

Response

200 Ok
Response:
[{
    "participantName": "John Doe",
    "customerProfileId": 123,
    "score": 23.22,
    "position": 1,
    "previousPosition": null
}, {
    "participantName": "Jane Doe",
    "customerProfileId": 121,
    "score": 21.22,
    "position": 2,
    "previousPosition": 3
}, {
    "participantName": "Snake Doe",
    "customerProfileId": 124,
    "score": 20.22,
    "position": 3,
    "previousPosition": 1
},
{...}.
...]

Errors

Code Error Message
400 Season <1234> has no DemographicField configured
404 No suitable LeaderboardSeason could be found for tenant <1234>
404 Could not find Leaderboard for given parameters: seasonId <1234>, intervalId <1234>, demographicValue <\fieldValue>