Get User By Email

Retrieve a single user by exact email address.

Authentication

This endpoint requires a bearer access token for the System API.

Endpoint

GET /api/v1/users/by-email?email={email}
Authorization: Bearer YOUR_ACCESS_TOKEN

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token for a System API client

Query Parameters

Parameter	Type	Required	Description
email	string	Yes	User email address. Leading and trailing whitespace is ignored, and lookup is case-insensitive.

Request Body

This endpoint does not accept a request body.

Response

200 OK

Returns the user matching the provided email address.

{
  "id": 101,
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "roles": [
    {
      "id": 1,
      "key": "administrator",
      "name": "Administrator",
      "description": "Full administrative access"
    }
  ],
  "permissions": [
    {
      "id": 1,
      "key": "users.read",
      "name": "Users Read",
      "description": "Allows reading user records"
    }
  ],
  "lastLogin": "2026-04-22T10:15:30Z",
  "status": 3,
  "isSuspended": false,
  "isLocked": false,
  "avatarUrl": "https://cdn.example.com/avatar-signed-url"
}

Response Fields

Field	Type	Description
id	integer	User identifier
firstName	string	User first name
lastName	string	User last name
email	string	User email address
roles	array	Roles currently assigned to the user
roles[].id	integer	Role identifier
roles[].key	string	Stable role key
roles[].name	string	Display name of the role
roles[].description	string	Human-readable role description
permissions	array	Business permissions assigned directly to the user
permissions[].id	integer	Permission identifier
permissions[].key	string	Stable permission key
permissions[].name	string	Display name of the permission
permissions[].description	string	Human-readable permission description
lastLogin	string or null	Last login timestamp in ISO-8601 format, when available
status	integer	User status value. 1 = Staged, 2 = Invited, 3 = Active, 4 = Archived
isSuspended	boolean	Whether the user is suspended
isLocked	boolean	Whether the user is currently locked
avatarUrl	string or null	Signed avatar URL when an avatar exists

Errors

Status	When it happens
400 Bad Request	The required email query parameter is missing or cannot be bound
401 Unauthorized	The bearer token is missing, invalid, or expired
403 Forbidden	The token is valid but does not have access to this endpoint
404 Not Found	No user exists with the provided email address

404 Example

Backend.User.Not.Found

Behavior

• The email value is trimmed and compared case-insensitively.
• This is an exact email lookup, not a partial search.
• Avatar URLs are returned as signed URLs when an avatar exists.
• isLocked is true only when the user's lockout end time is in the future.

Example

cURL

curl -X GET "https://your-tenant.guardhouse.cloud/api/v1/users/by-email?email=john.doe%40example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

.NET (raw HTTP)

using System.Net.Http.Headers;
using System.Net.Http.Json;

var requestUri = "https://your-tenant.guardhouse.cloud/api/v1/users/by-email?email=john.doe%40example.com";

using var request = new HttpRequestMessage(HttpMethod.Get, requestUri);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");

using var response = await httpClient.SendAsync(request);

if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
    return Results.NotFound();
}

response.EnsureSuccessStatusCode();

var user = await response.Content.ReadFromJsonAsync<GetUserByEmailResponse>();
return Results.Ok(user);

Python (raw HTTP)

# The Python beta does not expose System API helpers.
# Use raw HTTP for now.
#
# Example shape:
# response = requests.get(
#     "https://your-tenant.guardhouse.cloud/api/v1/users/by-email",
#     headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
#     params={"email": "[email protected]"},
# )

Notes

• Use Get Users when you need paged or partial email search.
• Use Get User By ID when you already have the numeric user identifier.