> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teambuilder.ge/llms.txt
> Use this file to discover all available pages before exploring further.

# List employees

> List active employees, oldest first, or find one by email, external ID or department.

<Tip>
  Building profile widgets? See [Employee widgets](/guides/employee-widgets) for lookup patterns and how to treat employees who have not signed in yet.
</Tip>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/employees
openapi: 3.0.0
info:
  title: TeamBuilder API
  description: >-
    The TeamBuilder API gives your own systems access to your company's
    gamification data (employees, leaderboards, departments and the rewards
    shop) and lets you push your employee roster from your HR system. Send every
    request to `https://api.teambuilder.ge/v1` with your API key as
    `Authorization: Bearer <key>`: live keys (`tb_live_…`) work on your real
    data, test keys (`tb_test_…`) on a sandbox company with sample data.
    Responses are JSON with snake_case fields, cursor-based pagination and
    `X-RateLimit-*` headers. For keys, scopes or help, contact
    [contact@teambuilder.ge](mailto:contact@teambuilder.ge).
  version: '1.0'
  contact:
    name: TeamBuilder support
    url: https://teambuilder.ge
    email: contact@teambuilder.ge
servers:
  - url: https://api.teambuilder.ge
    description: Production
security: []
tags:
  - name: Status
    description: Check that your API key works and see what it can access.
  - name: Employees
    description: >-
      Your active employees, their gamification stats and the badges they hold.
      Requires the `employees:read` scope.
  - name: Leaderboard
    description: >-
      XP rankings of your employees for a chosen period, company-wide or grouped
      by department. Requires the `leaderboard:read` scope.
  - name: Departments
    description: Your company's department tree. Requires the `departments:read` scope.
  - name: Shop
    description: >-
      The rewards your employees can redeem with their coins. Requires the
      `shop:read` scope.
  - name: Roster sync
    description: >-
      Keep TeamBuilder in step with your HR system by pushing your employee
      roster. Requires the `employees:write` scope, which is issued on request.
paths:
  /v1/employees:
    get:
      tags:
        - Employees
      summary: List employees
      description: >-
        Returns your company's active employees in the order they joined, 25 per
        page unless you set `limit`.


        Use it to mirror your roster, or filter by `email`, `external_id` or
        `department_id` to find one person or one team. Filters combine.


        **Notes**


        - Deactivated employees are not listed. Invited employees who have not
        signed in yet are.

        - Until an employee first signs in, `name` is the name your roster sync
        sent, or null.
      operationId: listEmployees
      parameters:
        - name: cursor
          required: false
          in: query
          description: >-
            The `pagination.next_cursor` of the previous page. Omit it, or send
            it empty, for the first page. A cursor is opaque and works only on
            the endpoint that returned it, for the same company.
          schema:
            maxLength: 512
            example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
            type: string
        - name: limit
          required: false
          in: query
          description: How many items to return per page, from 1 to 100.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            example: 25
            type: integer
        - name: email
          required: false
          in: query
          description: Only the employee with this email address. Matching ignores case.
          schema:
            maxLength: 256
            example: nino.beridze@example.com
            type: string
        - name: external_id
          required: false
          in: query
          description: >-
            Only the employee with this key from your HR system. Matching is
            exact.
          schema:
            maxLength: 255
            example: EMP-00042
            type: string
        - name: department_id
          required: false
          in: query
          description: >-
            Only members of this department. Members of its sub-departments are
            not included.
          schema:
            format: uuid
            example: b3e1f7a2-6c4d-4e8f-9a1b-2c3d4e5f6a7b
            type: string
      responses:
        '200':
          description: A page of employees.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeList'
        '400':
          description: >-
            A query parameter or the `cursor` is invalid. `message` names the
            problem.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_failed
                  message: limit must not be greater than 100
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '401':
          description: The API key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Invalid API key
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '403':
          description: Your API key does not have the `employees:read` scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: 'This API key lacks the required scope: employees:read'
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '404':
          description: '`department_id` is not a department of your company.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Department not found
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '429':
          description: >-
            Your API key made more requests than its limit allows (60 per minute
            unless agreed otherwise), or too many requests came from your IP
            address. Wait `Retry-After` seconds, then retry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests. Retry after 30 seconds.
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
      security:
        - api-key: []
components:
  headers:
    X-Request-Id:
      description: Unique id of this request. Quote it when you contact support.
      schema:
        type: string
        example: req_7Hq2LmX9vT4kPz1RbN8sWc
    X-RateLimit-Limit:
      description: Requests your API key may make per minute.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
        example: 57
    X-RateLimit-Reset:
      description: When the current window ends, as a Unix timestamp in seconds.
      schema:
        type: integer
        example: 1792483260
    WWW-Authenticate:
      description: The authentication scheme to use.
      schema:
        type: string
        example: Bearer realm="TeamBuilder API"
    Retry-After:
      description: Seconds to wait before you retry.
      schema:
        type: integer
        example: 30
  schemas:
    EmployeeList:
      type: object
      properties:
        data:
          description: Employees on this page, in the order they joined.
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        pagination:
          description: Where the next page starts.
          allOf:
            - $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    Error:
      type: object
      properties:
        error:
          description: What went wrong, and the id that traces the request.
          allOf:
            - $ref: '#/components/schemas/ErrorDetail'
      description: Every error response has this shape, whatever its status code.
      required:
        - error
    Employee:
      type: object
      properties:
        employee_id:
          type: string
          format: uuid
          description: >-
            TeamBuilder id of the employee. Stable for as long as they are in
            your company.
          example: 8d2f6b1e-4c3a-4f5e-b7d9-1a2c3e4f5a6b
        external_id:
          type: string
          nullable: true
          description: The employee's key in your HR system. Null if none was set.
          example: EMP-00042
        name:
          type: string
          nullable: true
          description: >-
            Full name. Until the employee first signs in, this is the name your
            roster sync sent, or null if it sent none; afterwards, the name on
            their TeamBuilder account.
          example: Nino Beridze
        email:
          type: string
          format: email
          description: Work email address.
          example: nino.beridze@example.com
        department:
          nullable: true
          description: The department the employee belongs to. Null if they have none.
          type: object
          allOf:
            - $ref: '#/components/schemas/DepartmentRef'
      required:
        - employee_id
        - external_id
        - name
        - email
        - department
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: Pass it as `cursor` to read the next page. Null on the last page.
          example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
      required:
        - next_cursor
    ErrorDetail:
      type: object
      properties:
        code:
          description: >-
            Machine-readable error type. Branch on this, not on `message`:

            - `validation_failed` (400): a parameter, cursor or body field is
            invalid.

            - `unauthorized` (401): the API key is missing, unknown, revoked or
            expired.

            - `forbidden` (403): the key does not have the scope this endpoint
            requires.

            - `not_found` (404): the resource does not exist in your company.

            - `conflict` (409): the request clashes with work in progress, such
            as another roster sync.

            - `length_required` (411): the request body was sent without a
            `Content-Length` header.

            - `payload_too_large` (413): the request body is larger than the
            endpoint accepts.

            - `rate_limit_exceeded` (429): the key made too many requests; wait
            for `Retry-After` seconds.

            - `bad_request` (other 4xx): the request could not be accepted as
            sent.

            - `internal_error` (500): something failed on our side; contact
            support with the `request_id`.
          example: validation_failed
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable explanation for developers. It may change; do not
            parse it.
          example: limit must not be greater than 100
        request_id:
          type: string
          description: >-
            Unique id of the request, also sent as the `X-Request-Id` header.
            Quote it when you contact support.
          example: req_7Hq2LmX9vT4kPz1RbN8sWc
      required:
        - code
        - message
        - request_id
    DepartmentRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: TeamBuilder id of the department.
          example: b3e1f7a2-6c4d-4e8f-9a1b-2c3d4e5f6a7b
        external_id:
          type: string
          nullable: true
          description: The department's key in your HR system. Null if none was set.
          example: D-ENG
        name:
          type: string
          description: Department name.
          example: Engineering
      description: The department an employee belongs to.
      required:
        - id
        - external_id
        - name
    ErrorCode:
      type: string
      enum:
        - bad_request
        - validation_failed
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - length_required
        - payload_too_large
        - rate_limit_exceeded
        - internal_error
      description: >-
        Machine-readable error type. Branch on this, not on `message`:

        - `validation_failed` (400): a parameter, cursor or body field is
        invalid.

        - `unauthorized` (401): the API key is missing, unknown, revoked or
        expired.

        - `forbidden` (403): the key does not have the scope this endpoint
        requires.

        - `not_found` (404): the resource does not exist in your company.

        - `conflict` (409): the request clashes with work in progress, such as
        another roster sync.

        - `length_required` (411): the request body was sent without a
        `Content-Length` header.

        - `payload_too_large` (413): the request body is larger than the
        endpoint accepts.

        - `rate_limit_exceeded` (429): the key made too many requests; wait for
        `Retry-After` seconds.

        - `bad_request` (other 4xx): the request could not be accepted as sent.

        - `internal_error` (500): something failed on our side; contact support
        with the `request_id`.
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: API key — `tb_live_…` for production data, `tb_test_…` for the sandbox.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.