Skip to content

Users

The users endpoint returns the list of dashboard users that belong to your account. Results are scoped to the client(s) your API key represents. For keys with up to 10 authorised clients, an unscoped request aggregates users across those clients; for keys with more than 10 authorised clients, provide clientId to list users for one client at a time.

Pagination

This endpoint uses offset-based pagination. Use the limit parameter to control page size and the offset parameter to skip results. The response paging object reports the total number of matching users so you can iterate until offset + count reaches total.

Endpoint

GET /v1/users

Parameters

Parameter Type Required Description
clientId string Conditional Filter users to a specific client ID. Must be a client your API key is authorised for. Required when your API key is authorised for more than 10 clients; otherwise defaults to all clients on the key.
search string No Free-text, case-insensitive partial match on email, name, or surname.
role string No Filter by role. Accepted values are superuser, parentadmin, user, and admin. The admin role is PhishFort-internal and internal users are excluded from responses, so client integrations normally use superuser, parentadmin, or user. See User Roles.
limit integer No Maximum number of users to return per page. Must be from 1 to 200. Defaults to 200.
offset integer No Number of users to skip before returning results. Must be 0 or greater. Defaults to 0.

Large reseller accounts

If your API key is authorised for more than 10 clients, unscoped requests return 400 with Please provide clientId when listing users for API keys with more than 10 authorized clients.. Use clientId to fetch each client separately.

Pagination validation

limit and offset must be whole numbers within the ranges above. Invalid values return 400 with Value for limit or offset is not valid..

Request Example

curl -X GET -G 'https://capi.phishfort.com/v1/users' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d 'role=superuser' \
  -d 'limit=50'

import requests

response = requests.get(
    "https://capi.phishfort.com/v1/users",
    headers={
        "accept": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    params={
        "role": "superuser",
        "limit": 50,
    },
)
print(response.json())

const params = new URLSearchParams({
  role: "superuser",
  limit: "50",
});

const response = await fetch(
  `https://capi.phishfort.com/v1/users?${params}`,
  {
    headers: {
      accept: "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

Response Example

The data field is an array of UserStructure's. The paging object reports the page window and the total number of matching users.

{
    "message": "success",
    "data": [
        {
            "id": "user-abc123",
            "email": "alice@exampleclient.com",
            "name": "Alice",
            "surname": "Smith",
            "roles": ["superuser"],
            "clientId": "0Xp5voyA4y5xYNoufOVC",
            "clientName": "Example Client",
            "mfaEnabled": true,
            "createdAt": "2026-01-15T10:30:00.000Z",
            "updatedAt": "2026-06-20T14:22:00.000Z"
        }
    ],
    "paging": {
        "limit": 50,
        "offset": 0,
        "count": 1,
        "total": 1
    }
}

Fetching the Next Page

To fetch the next page of results, increment the offset by your limit: 

curl -X GET -G 'https://capi.phishfort.com/v1/users' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d 'limit=50' \
  -d 'offset=50'