Skip to main content
TeamBuilder ranks individuals by XP. Two endpoints expose the ranking, both with the leaderboard:read scope:

​
Periods

Pass period to choose the XP window. Windows are calendar months in UTC and always include the current month.
In every row, xp is the XP earned in the period, and it is what decides the order. level is always derived from all-time XP, whatever the period, so a long-standing employee keeps a high level on a quiet month.
Every active employee appears, including people with no XP in the period. Windowed XP is a net figure: an admin’s manual correction can make it zero or, rarely, negative.

​
What rank means

  • rank is the employee’s company-wide position for the period, starting at 1.
  • Ranks are unique. Employees with equal XP get consecutive ranks in a stable order, so ties never share a number and never reshuffle between requests.
  • Under a department filter, each row keeps its company-wide rank. The filtered list can therefore read 2, 7, 15. To show a position within the department, number the rows yourself as you walk the pages.

​
Filtering to a department

Pass a department_id from GET /v1/departments (or from any employee’s department.id):
The filter matches the department’s direct members only; members of its sub-departments are not included. An id that is not one of your departments returns 404 not_found.

​
Grouped by department

GET /v1/leaderboard/by-department returns every active department with its top members for the period, in a single page. An archived department that still has members is listed too, so nobody drops out of the view:
Response
  • Groups are ordered by department name, case-insensitively. Active departments without members are listed too, with member_count: 0 and no leaders. The group of employees without a department has department: null, is always last, and appears only when it has members.
  • leaders holds the top limit_per_department members (1–25, default 5), or every member when the group is smaller, each with their company-wide rank.
  • department_total_xp and member_count are informational. Departments are not ranked against each other: comparing a team of 4 with a team of 40 by total or average XP rewards size, not engagement, so TeamBuilder deliberately offers no department-versus-department ranking.

​
No coins on leaderboards

Leaderboards never include coin balances, by design. Coins are a spendable currency: ranking by balance would push down anyone who redeems a reward, and a public list of balances shows what colleagues have spent. XP is never spent, so it is a fair, private-enough basis for a ranking. To show someone their own balance, read it from employee stats.

​
Refresh cadence

Rankings are computed by TeamBuilder and cached for up to 30 seconds, so a response can be that old.
Fetch each view you display (period × department) on your server at most once a minute, cache the result, and serve every page view from your cache. For office screens and dashboards, a refresh every one to five minutes looks live and stays far inside the rate limit.

​
Paging through a full board

GET /v1/leaderboard is cursor-paginated (limit 1–100, default 25). While employees earn XP, rows can move between pages, so a page-by-page walk of a large board is approximate: a row may repeat or be skipped. Display the first page or two, and if you need a complete export, de-duplicate by employee_id. See Pagination.

​
Names

name is the employee’s account name once they have signed in to TeamBuilder. Before that it is the name your roster sync sent, or null when there is none. Always render a fallback, such as “New teammate”.