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)

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: 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, 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 — 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.

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. Matched exactly. A username with no account behind it returns `404`.

Sample request

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. 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.
`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, 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

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.

This page as markdown · All pages · llms.txt