Introduction

The TeamBuilder API gives your internal systems read access to your company’s gamification data and one write operation: syncing your roster. It is a server-to-server REST API with JSON responses, Bearer-key authentication and cursor pagination. Who it’s for: engineering and IT teams at companies that use TeamBuilder and want its data where employees already spend their day: an intranet, an internal portal, Slack or Teams bots, office screens, or a data warehouse.

What you can build

Leaderboards

Rank people by XP for this month, the last 3 months, the last year or all time, company-wide or per department.

Employee widgets

Show level, XP progress, coins, ranks and badges on intranet profiles, plus your reward catalogue.

Roster sync

Push your HR roster daily so joiners, departments, job titles and leavers stay current automatically.

Base URL

https://api.teambuilder.ge/v1

All requests use HTTPS. Request and response bodies are JSON with snake_case keys, and timestamps are ISO 8601 in UTC.

A 20-second example

Fetch this month’s top employee:

curl "https://api.teambuilder.ge/v1/leaderboard?period=this_month&limit=1" \
  -H "Authorization: Bearer $TEAMBUILDER_API_KEY"

const res = await fetch(
  "https://api.teambuilder.ge/v1/leaderboard?period=this_month&limit=1",
  { headers: { Authorization: `Bearer ${process.env.TEAMBUILDER_API_KEY}` } },
);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.teambuilder.ge/v1/leaderboard",
    params={"period": "this_month", "limit": 1},
    headers={"Authorization": f"Bearer {os.environ['TEAMBUILDER_API_KEY']}"},
    timeout=10,
)
data = res.json()["data"]

Response

{
  "data": [
    {
      "rank": 1,
      "employee_id": "3f1c2a9e-8d4b-4c61-9a57-0e2b6f7d1a43",
      "external_id": "EMP-00042",
      "name": "Nino Beridze",
      "department": {
        "id": "b7e0c4d2-1f3a-4e8b-9c6d-2a5f8e1b7c90",
        "external_id": "D-ENG",
        "name": "Engineering"
      },
      "level": 12,
      "xp": 2300
    }
  ],
  "pagination": { "next_cursor": "djEuQ2lwaGVydGV4dEV4YW1wbGU" }
}

Leaderboards rank people by XP, never by coins. Coin balances are available per employee from the employee stats endpoint.

Principles

Your data, scoped by your key

Every key belongs to exactly one company, and the company is resolved from the key alone, never from a parameter. Deactivated employees never appear in any response.

Predictable shapes

Lists return {"data": [], "pagination": {"next_cursor"}}. Errors return {"error": {"code", "message", "request_id"}}. Every response carries an X-Request-Id header.

A sandbox for every customer

tb_test_ keys read a sandbox company seeded with realistic sample data, through the same endpoints and response shapes as live keys.

Stable v1

Changes within /v1 are additive. Breaking changes ship as a new version, and a deprecated version keeps working for at least six months after the announcement. See Versioning.

Next steps

Quickstart

Your first request in five minutes.

Authentication

Keys, scopes and rotation.

API reference

Every endpoint, with a live playground.

Get API access

Ask for live and test keys for your company.

Getting started

Guides

Reference

What you can build

Leaderboards

Employee widgets

Roster sync

Base URL

A 20-second example

Principles

Next steps

Quickstart

Authentication

API reference

Get API access

​What you can build

Leaderboards

Employee widgets

Roster sync

​Base URL

​A 20-second example

​Principles

​Next steps

Quickstart

Authentication

API reference

Get API access

What you can build

Base URL

A 20-second example

Principles

Next steps