---
title: "List users"
method: GET
path: "/v1/users"
tags: ["Users"]
---

# List users

`GET /v1/users`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/users`
- Auth: API key in header `x-api-key`

Lists all users in your organization with pagination and optional filtering.

You can filter the results by exact email address or employee ID. Use pagination parameters to control the number of results returned per page.

## Query parameters

- `page` integer: Page to return, starting at 1.
- `pageSize` integer: Items per page, at most 50. Defaults to 10.
- `email` string, email: Filter by exact email address
- `employeeId` string: Filter by exact employee ID

## Response `200`

Successfully retrieved list of users

- ListUsersResponse
  - `page` integer, required: The page these items came from.
  - `pageSize` integer, required: Items per page, as requested.
  - `itemsCount` integer, required: Total items across all pages. Divide by pageSize to get the number of pages.
  - `items` UserListItem[], required: Users on this page.
    - `id` string, required: UUID of the user. Use it to provision a plan, submit a port-in, or update the user.
    - `email` string, email, required: Email address. Unique within your organization.
    - `firstName` string, required: First name.
    - `lastName` string, required: Last name.
    - `teamId` string, nullable, required: UUID of the team the user belongs to, or null.
    - `employeeId` string, nullable, required: Your own identifier for this person, as sent on create or update, or null.
    - `costCode` string, nullable, required: Cost center code used on invoices, or null.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to list users
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)