# account_list_users

List Users

## Beschreibung

Lists the people on the account — resolve `@handle` mentions,
pick a `user_id` target, or show a roster.

Admin and employer callers additionally see email, phone_number,
time_zone (contact-sensitive data) and employment-time
metadata: `working_hours` — the merged shape from ENG-1434
with `start_at` (HH:MM), `paused_minutes`, and
`hours_by_weekday` ({"mon": 8.0, …}, missing key = not a
workday); plus `checkin_not_required` (exempt from
clock-in/out logic, e.g. C-level), and
`standup_not_required`. `include_inactive` defaults to true
so historical mentions still resolve; pass false for a live
roster. `search` is a case-insensitive substring over handle /
first_name / last_name (+ email for admin/employer).

## Zugriff

Zugriffsprofil: `basic`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (e.g., acct_abc123). Discover via account_list. |
| `include_inactive` | boolean | Nein | Include inactive (departed) users so historical @handles still resolve. Default true. Pass false for a live-roster view. |
| `search` | string | Nein | Case-insensitive substring, 1+ chars. Matches handle / first_name / last_name (admin/employer: also email). Use for narrowing before pulling the full list. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123). Discover via account_list."
    },
    "include_inactive": {
      "type": "boolean",
      "description": "Include inactive (departed) users so historical @handles still resolve. Default true. Pass false for a live-roster view."
    },
    "search": {
      "type": "string",
      "description": "Case-insensitive substring, 1+ chars. Matches handle / first_name / last_name (admin/employer: also email). Use for narrowing before pulling the full list."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User prefix ID (user_…) — pass to tools that accept user_id (handle also accepted)."
          },
          "db_id": {
            "type": "integer",
            "description": "Integer PK — matches user.db_id in chat/time-clock/standup response rows."
          },
          "handle": {
            "type": "string",
            "description": "Unique within the account; what @handle mentions reference."
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": [
              "string",
              "null"
            ],
            "description": "Omitted for external (guest) callers."
          },
          "remote_worker": {
            "type": "boolean",
            "description": "Omitted for external (guest) callers."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Omitted for external (guest) callers."
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "admin",
                "employer"
              ]
            },
            "description": "Empty = regular member."
          },
          "is_agent": {
            "type": "boolean",
            "description": "True if this user is a bot account (AI participant). Treat the row as an agent rather than a person — don't ask the bot for human feedback; don't assign tasks expecting human work."
          },
          "email": {
            "type": "string",
            "description": "Only present for admin/employer callers."
          },
          "phone_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only present for admin/employer callers."
          },
          "time_zone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Rails TimeZone display label (e.g. 'Berlin'), not an IANA id. Only for admin/employer callers."
          },
          "working_hours": {
            "type": "object",
            "description": "ENG-1434. Merged working-hours record for this member. `start_at` HH:MM daily start, `paused_minutes` daily break, `hours_by_weekday` a map of weekday → Float hours (missing key = not a workday for this member; don't flag them missing). Only present for admin/employer callers.",
            "properties": {
              "start_at": {
                "type": "string"
              },
              "paused_minutes": {
                "type": "integer"
              },
              "hours_by_weekday": {
                "type": "object",
                "description": "e.g. {\"mon\": 8.0, \"fri\": 4.0}"
              }
            }
          },
          "checkin_not_required": {
            "type": "boolean",
            "description": "True when the user is exempt from clock-in/out (C-level, etc.) — attendance logic must NOT flag them as missing. Only present for admin/employer callers."
          },
          "standup_not_required": {
            "type": "boolean",
            "description": "True when the user is exempt from the daily standup roster. Only present for admin/employer callers."
          }
        },
        "required": [
          "id",
          "db_id",
          "handle",
          "name",
          "roles",
          "is_agent"
        ]
      }
    }
  },
  "required": [
    "users"
  ],
  "type": "object"
}
```