# Retrieves detailed information for a specific administrative user

`GET /api/users/{username}`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Retrieves detailed information for a specific administrative user](https://support.gladstonesoftware.cloud/reference/users/retrieves-detailed-information-for-a-specific-administrative-user)

## Overview

Returns one staff (back-office) user by sign-in name. Staff users are the people who operate the leisure centre, not members or customers.

Reach for this before [Updates the details and settings for a specific administrative user](updates-the-details-and-settings-for-a-specific-administrative-user.md): that endpoint is a full replacement, so you need the current values of every field you are not changing. It also resolves the two identifiers whose format you cannot guess — `roleId` and `siteGroupId` — as your tenant actually stores them.

Unlike [Retrieves all administrative users configured in the system](retrieves-all-administrative-users-configured-in-the-system.md), this endpoint does not exclude deleted accounts: a deleted user is still returned here, with `isDeleted: true` and `isActive: false`. Use that to tell "no such username" apart from "username already taken by a deleted account".

Each tenant uses one of two authentication configurations — [ObjectId-role or numeric-role](retrieves-all-administrative-users-configured-in-the-system.md) — and several fields are available under only one of them. Where a field is not available for your tenant, it comes back `null` rather than being omitted. The per-field notes below say which.

## Endpoint

`GET {base_url}/api/users/{username}`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `username` | string | Yes | The sign-in name of the account to read, as returned in `[].username` by [Retrieves all administrative users configured in the system](retrieves-all-administrative-users-configured-in-the-system.md). Matched exactly. A username with no account behind it returns `404`. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/users/{username}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `username` | string | The sign-in name, echoing the path parameter. Unique within the tenant and never reassigned, including after deletion. |
| `firstName` | string | The user's given name, as supplied on create or update. |
| `lastName` | string | The user's family name, as supplied on create or update. |
| `displayName` | string | The name shown to other staff in the back office. Defaults to `"{firstName} {lastName}"` when the account was created or updated without one, so it is rarely null in practice. |
| `email` | string | The account's contact address. `null` when the account was created without one. |
| `cardId` | string | The identifier on the physical staff card this user presents at a reader or till. `null` when the user has no card. |
| `siteGroupId` | string | The site group the user belongs to — a named collection of sites, matching `id` from [Retrieves all site groups with their configuration details](../configuration/retrieves-all-site-groups-with-their-configuration-details.md). On numeric-role tenants, some accounts return the numeric site group identifier rendered as a string instead, which will not match any `id` from that endpoint. |
| `preferredSiteId` | string | The site the user works at by default, stored as the user preference named `PreferredSiteId` rather than as a field on the account. `null` when no such preference has been stored for that user. |
| `roleId` | string | The permission role granted to the user, but in one of two different formats depending on how your tenant authenticates: on ObjectId-role tenants it is a 24-character hexadecimal string, taken from the user's role claim. On numeric-role tenants this endpoint always returns `null`, even for users who do have a role — the list endpoint returns it but this one does not. Read `roleId` from the list endpoint if you need it on a numeric-role tenant. |
| `avatarId` | string | The profile image shown for the user. Always `null` on numeric-role tenants, which do not hold one. |
| `dateCreated` | string (date-time) | When the account was created. Accounts with no recorded creation date come back as `0001-01-01T00:00:00`, not `null`, so treat that value as "unknown" rather than a real date. |
| `isActive` | boolean | Whether the account may be used. Set to `false` automatically when the account is deleted, and settable directly through [Updates the details and settings for a specific administrative user](updates-the-details-and-settings-for-a-specific-administrative-user.md). |
| `isDeleted` | boolean | Whether the account has been deleted. Deleted accounts are still returned by this endpoint, so check this flag rather than assuming a `200` means the account is usable. |
| `isLocked` | boolean | Whether the account is locked out of signing in. Clearing it through the update endpoint also resets `failedLoginAttemptsCount` to `0`. |
| `isPasswordResetFlagSet` | boolean | Whether the user is being forced to set a new password at their next sign-in. Set through [Updates a user's password reset flag for account security management](updates-a-users-password-reset-flag-for-account-security-management.md), and cleared automatically when their password is changed on ObjectId-role tenants. On numeric-role tenants it is always `false` for accounts that have no legacy system-user record. |
| `lastLoginAttemptDate` | string (date-time) | When a sign-in was last attempted for this account, successful or not. `null` when no attempt has been recorded. |
| `failedLoginAttemptsCount` | integer (int32) | Consecutive failed sign-in attempts since the last success. It cannot exceed 255. Reset to `0` when the account is unlocked through the update endpoint. |

## Sample response

```json title="200 OK"
{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "displayName": "string",
  "email": "member@example.com",
  "cardId": "string",
  "siteGroupId": "string",
  "preferredSiteId": "string",
  "roleId": "string",
  "avatarId": "string",
  "dateCreated": "2026-08-14T19:00:00Z",
  "isActive": true,
  "isDeleted": true,
  "isLocked": true,
  "isPasswordResetFlagSet": true,
  "lastLoginAttemptDate": "2026-08-14T19:00:00Z",
  "failedLoginAttemptsCount": 1
}
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | The username resolved to an empty value: `The given username: {username} is invalid`. In practice a blank path segment is routed elsewhere, so this is hard to reach through the gateway. |
| `404` | Not found | No account exists with that username: `The user with username: {username} could not be found in SQL database` on numeric-role tenants, or `Failed to find user for username: {username}` on ObjectId-role tenants, where the account must be fully set up to be returned. |
| `500` | Internal server error | An unexpected server-side failure while reading the account — for example a user whose site group no longer exists, or the tenant's authentication configuration being missing or invalid. Returned with no body. |