Leaderboard

Retrieve employee referral leaderboard rankings

Returns a ranked list of employees based on their referral and recommendation activity. Use this to build custom leaderboards, reward programs, or internal dashboards.

Scope required: leaderboard:read

GET /api/v1/leaderboard

Query Parameters

Parameter	Type	Default	Range	Description
period	number	365	1–3650	Days to look back
limit	number	10	1–50	Top N employees (used with groupBy=month)
page	number	1	1+	Page number
pageSize	number	10	1–50	Entries per page
vacancyIds	string	-	-	Comma-separated vacancy IDs to filter by
groupBy	string	-	month	Group results by month

Points System

Points are calculated based on employee actions:

Action	Points
Referral (employee_refer)	3
Recommendation (employee_recommend)	1

Employees are ranked by total points in descending order.

Example Request

curl -H "Authorization: Bearer wintro_abc123..." \
  "https://app.wintro.ai/api/v1/leaderboard?period=90&pageSize=5"

Response (flat)

When no groupBy parameter is set, returns a flat ranked list:

{
  "data": [
    {
      "userId": 123,
      "firstName": "Jane",
      "lastName": "Doe",
      "profileUrl": "https://linkedin.com/in/jane-doe",
      "profilePicture": "https://...",
      "referCount": 5,
      "recommendCount": 12,
      "totalPoints": 27
    }
  ],
  "meta": {
    "periodDays": 90,
    "generatedAt": "2026-03-16T12:00:00.000Z",
    "pagination": {
      "page": 1,
      "pageSize": 5,
      "totalItems": 42,
      "totalPages": 9
    }
  }
}

Response (monthly)

When groupBy=month is set, returns leaderboards grouped by month plus an overall top 3:

curl -H "Authorization: Bearer wintro_abc123..." \
  "https://app.wintro.ai/api/v1/leaderboard?period=365&groupBy=month&limit=5"

{
  "data": {
    "monthly": [
      {
        "month": "2026-03",
        "entries": [
          {
            "userId": 123,
            "firstName": "Jane",
            "lastName": "Doe",
            "profileUrl": "https://linkedin.com/in/jane-doe",
            "profilePicture": "https://...",
            "referCount": 2,
            "recommendCount": 5,
            "totalPoints": 11
          }
        ]
      }
    ],
    "topOverall": [
      {
        "userId": 456,
        "firstName": "John",
        "lastName": "Smith",
        "profileUrl": "https://linkedin.com/in/john-smith",
        "profilePicture": "https://...",
        "referCount": 8,
        "recommendCount": 20,
        "totalPoints": 44
      }
    ]
  },
  "meta": {
    "periodDays": 365,
    "limit": 5,
    "groupBy": "month",
    "generatedAt": "2026-03-16T12:00:00.000Z",
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 12,
      "totalPages": 2
    }
  }
}

When using groupBy=month:

• monthly, One entry per month, each containing the top limit employees for that month. Pagination applies to months.
• topOverall, The top 3 employees across the entire period (always included, not paginated).
• limit, Controls how many employees appear per month (not used in flat mode).

Entry Fields

Field	Type	Description
userId	number	Wintro user ID
firstName	string | null	Employee’s first name
lastName	string | null	Employee’s last name
profileUrl	string | null	LinkedIn profile URL
profilePicture	string | null	Profile picture URL
referCount	number	Number of referrals in the period
recommendCount	number	Number of recommendations in the period
totalPoints	number	Calculated score (referrals x 3 + recommendations x 1)