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

# List users

> GET /users — paginated list of account members

## Endpoint

```http theme={null}
GET https://api.routera.io/users
```

**Route:** `/users`\
**Authentication:** Bearer JWT

## Query parameters

| Parameter  | Type    | Default | Description                                   |
| ---------- | ------- | ------- | --------------------------------------------- |
| `archived` | boolean | `false` | Set to `true` to include soft-deleted members |
| `limit`    | integer | `10`    | Maximum number of results (10–100)            |
| `offset`   | integer | `0`     | Pagination offset                             |

## Response fields

Each item in `data` includes:

| Property                               | Description                                                                                       |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`                                   | User ID (UUID)                                                                                    |
| `email`                                | User email (read-only)                                                                            |
| `full_name`, `first_name`, `last_name` | Display and name fields                                                                           |
| `role`                                 | Role display name (read-only; change via `role_id` on PATCH)                                      |
| `external_id`                          | External identifier (nullable)                                                                    |
| `phone`                                | Phone number                                                                                      |
| `office_status`                        | Whether the member is in office (boolean)                                                         |
| `working_hours`                        | Array of `{ days, start_date, end_date }` (`days` e.g. `Mon - Fri` or `monday`; times as `HH:mm`) |
| `out_office_dates`                     | Out-of-office ranges (`start_date`, `end_date`, optional `created_by`)                            |
| `time_zone`                            | IANA time zone (e.g. `America/New_York`)                                                          |
| `calendars`                            | Active calendar configs keyed by provider to email (read-only)                                    |
| `capacity`                             | Capacity assignments (`id`, `name`, `current_capacity`, `max_capacity`, `assignment_type`)        |
| `can_receive_notifications`            | Whether the member can receive notifications                                                      |
| `notification_preferences`             | Notification preference categories                                                                |
| `archived`                             | `false` when active; ISO timestamp when archived                                                  |
| `archived_by`                          | Present when archived                                                                             |

## Response

**200** — Paginated list

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "full_name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "role": "Administrator",
      "external_id": null,
      "phone": null,
      "office_status": true,
      "working_hours": [
        {
          "days": "Mon - Fri",
          "start_date": "09:00",
          "end_date": "17:00"
        },
        {
          "days": "saturday",
          "start_date": "10:00",
          "end_date": "14:00"
        }
      ],
      "out_office_dates": [
        {
          "start_date": "2026-04-02T12:00:00.000Z",
          "end_date": "2026-04-03T12:00:00.000Z",
          "created_by": "user@example.com"
        }
      ],
      "time_zone": "America/New_York",
      "calendars": {
        "outlook": "user@example.com"
      },
      "capacity": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "Leads",
          "current_capacity": 2,
          "max_capacity": 10,
          "assignment_type": "user"
        }
      ],
      "can_receive_notifications": true,
      "notification_preferences": [
        "billing",
        "routing",
        "system"
      ],
      "archived": false
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 1
  }
}
```

`pagination.count` is the number of items in this page (not the total account member count).

## Errors

| Status | When                                      |
| ------ | ----------------------------------------- |
| `400`  | Invalid list path or query parameters     |
| `401`  | Missing or invalid account context in JWT |
| `500`  | Internal server error                     |


## OpenAPI

````yaml GET /users
openapi: 3.0.1
info:
  title: Routera API
  description: >-
    Routera v2 REST API. Objects CRUD for contacts, companies, deals, and
    tickets, users and routers APIs, plus router dispatch.
  version: 1.0.0
servers:
  - url: https://api.routera.io
    description: >-
      API Gateway base URL (override with ROUTERA_API_BASE_URL when generating
      docs)
security: []
tags:
  - name: Authentication
    description: Access token issuance
  - name: Contacts
    description: Contact records
  - name: Companies
    description: Company records
  - name: Deals
    description: Deal records
  - name: Tickets
    description: Ticket records
  - name: Users
    description: Account members
  - name: Routers
    description: Router configuration
  - name: Dispatch
    description: Router assignment
paths:
  /users:
    get:
      tags:
        - Users
      summary: List users
      operationId: listUsers
      parameters:
        - name: archived
          in: query
          description: Include archived (soft-deleted) members when true
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum results (default 10, max 100)
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Pagination offset (default 0)
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: Paginated list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
              example:
                data:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    email: user@example.com
                    full_name: Jane Doe
                    first_name: Jane
                    last_name: Doe
                    role: Administrator
                    external_id: null
                    phone: null
                    office_status: true
                    working_hours:
                      - days: Mon - Fri
                        start_date: '09:00'
                        end_date: '17:00'
                      - days: saturday
                        start_date: '10:00'
                        end_date: '14:00'
                    out_office_dates:
                      - start_date: '2026-04-02T12:00:00.000Z'
                        end_date: '2026-04-03T12:00:00.000Z'
                        created_by: user@example.com
                    time_zone: America/New_York
                    calendars:
                      outlook: user@example.com
                    capacity:
                      - id: 660e8400-e29b-41d4-a716-446655440001
                        name: Leads
                        current_capacity: 2
                        max_capacity: 10
                        assignment_type: user
                    can_receive_notifications: true
                    notification_preferences:
                      - billing
                      - routing
                      - system
                    archived: false
                pagination:
                  limit: 10
                  offset: 0
                  count: 1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
components:
  schemas:
    ListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
        pagination:
          $ref: '#/components/schemas/Pagination'
    User:
      type: object
      description: >-
        Account member (user + member_account). Role is the display name string.
        Archived members include archived timestamp and archived_by.
      properties:
        id:
          type: string
          description: User ID (UUID)
        email:
          type: string
        full_name:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        role:
          type: string
          description: Role display name (read-only)
        external_id:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        office_status:
          type: boolean
        working_hours:
          type: array
          items:
            $ref: '#/components/schemas/WorkingHour'
          description: >-
            Working hour ranges. Empty array means available 24/7. Times are
            interpreted in `time_zone`.
          example:
            - days: Mon - Fri
              start_date: '09:00'
              end_date: '17:00'
            - days: saturday
              start_date: '10:00'
              end_date: '14:00'
        out_office_dates:
          type: array
          items:
            $ref: '#/components/schemas/OutOfficeDate'
        time_zone:
          type: string
          description: IANA time zone
          example: America/New_York
        calendars:
          type: object
          additionalProperties:
            type: string
          description: Active calendar configs keyed by provider to email
        capacity:
          type: array
          items:
            $ref: '#/components/schemas/UserCapacity'
        can_receive_notifications:
          type: boolean
        notification_preferences:
          type: array
          items:
            type: string
        archived:
          description: false when active, or ISO timestamp when archived
          oneOf:
            - type: boolean
            - type: string
              format: date-time
        archived_by:
          type: string
          description: Present when archived
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        email: user@example.com
        full_name: Jane Doe
        first_name: Jane
        last_name: Doe
        role: Administrator
        external_id: null
        phone: null
        office_status: true
        working_hours:
          - days: Mon - Fri
            start_date: '09:00'
            end_date: '17:00'
          - days: saturday
            start_date: '10:00'
            end_date: '14:00'
        out_office_dates:
          - start_date: '2026-04-02T12:00:00.000Z'
            end_date: '2026-04-03T12:00:00.000Z'
            created_by: user@example.com
        time_zone: America/New_York
        calendars:
          outlook: user@example.com
        capacity:
          - id: 660e8400-e29b-41d4-a716-446655440001
            name: Leads
            current_capacity: 2
            max_capacity: 10
            assignment_type: user
        can_receive_notifications: true
        notification_preferences:
          - billing
          - routing
          - system
        archived: false
    ApiError:
      type: object
      required:
        - message
        - error
      properties:
        message:
          type: string
        error:
          type: boolean
          enum:
            - true
        field:
          type: string
          description: Field that caused a conflict (409 duplicate responses)
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
    WorkingHour:
      type: object
      required:
        - days
        - start_date
        - end_date
      properties:
        days:
          type: string
          description: >-
            Day or range: `monday`…`sunday`, `Mon - Fri` / `mon-fri`, `Sat -
            Sun` / `sat-sun`, `saturday`, or `sunday`
          example: Mon - Fri
        start_date:
          type: string
          description: Start time in `HH:mm` (member time zone)
          example: '09:00'
        end_date:
          type: string
          description: End time in `HH:mm` (member time zone)
          example: '17:00'
    OutOfficeDate:
      type: object
      properties:
        start_date:
          type: string
          format: date-time
          description: Range start (ISO 8601)
        end_date:
          type: string
          format: date-time
          description: Range end (ISO 8601); must be >= start_date
        created_by:
          type: string
          description: Email of who created the range (response only)
    UserCapacity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        current_capacity:
          type: integer
        max_capacity:
          type: integer
        assignment_type:
          type: string
          description: e.g. user or team
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT with valid account context.

````