Users
Reference for the users resource. Requests follow the conventions in
Requests and Responses; fields you
receive and may write are filtered by your user's permissions, so responses can
contain a subset of the fields below.
Operations
| Operation | Request |
|---|---|
| List | GET /{profile}/user/v4/users |
| Fetch | GET /{profile}/user/v4/users/{id} |
| Create | POST /{profile}/user/v4/users |
| Update | PATCH /{profile}/user/v4/users/{id} |
| Delete | DELETE /{profile}/user/v4/users/{id} |
| Generate a new random password and email it to the user | POST /{profile}/user/v4/users/{id}/reset_password |
How it works
users are the staff accounts in your SecurityTrax company — reps, techs, admins. Each row
carries a name, login credentials, contact details, employment/HR fields, and inventory settings.
The API supports GET (read/list), POST (create), PATCH (edit), and DELETE
(deactivate).
Access is gated by the User permission, and is company-wide on every verb: reading, creating, editing, and deactivating users all require the User permission (view / create / modify / delete respectively) held at any location — you do not need to share a location with the user, matching the SecurityTrax web app's Users admin page.
What the AI and MCP surfaces can see
Users are sensitive (PII: SSN, birthdate, addresses, payroll identifiers). The AI and MCP surfaces
are deliberately limited to just four fields — fname, lname, username, and active. No
contact details, HR fields, SSN, payroll data, or notes are ever exposed to an AI/MCP client. The
full field set is available only on the HTTP api surface, subject to the User permission.
Creating a user
POST /users with the identity fields plus a valid email:
curl -X POST "https://portal.securitytrax.com/acme/user/v4/users" \
-H "Authorization: Bearer stx_acme_..." \
-H "Content-Type: application/json" \
-d '{"data":{"attributes":{"fname":"John","lname":"Doe","username":"jdoe","email":"john@example.com"}}}'
| Field | Required | Notes |
|---|---|---|
fname |
Yes | ≤ 255 chars. |
lname |
Yes | ≤ 255 chars. |
username |
Yes | ≤ 50 chars, must be unique in your company. |
email |
Yes | Valid email, ≤ 255 chars. |
Password: you cannot set or read a password through the API. A newly created user is given a
strong random password (which nobody sees — it is stored only as a hash) and is flagged to change it
on first login. To actually deliver credentials, use the reset_password action below — with
welcome: true for a brand-new user. Permission-group assignment (which locations and groups the
user belongs to) is a separate step and is not part of this resource; a freshly created user has
no group/location membership until you assign it.
Heads up. A brand-new user has no group/location membership until you assign it — but that never blocks API access to the user. Every verb is company-wide, so you can read, edit, and deactivate the new user immediately, without assigning a location first. Assigning a group/location (user_to_group_location) governs what the user can do; it's a separate step from managing the user via the API.
Resetting a password (delivering credentials)
POST /users/{id}/reset_password generates a new random password, flags the user to change it on
first login, and emails it to the user — the password never appears in the API response.
curl -X POST "https://portal.securitytrax.com/acme/user/v4/users/42/reset_password" \
-H "Authorization: Bearer stx_acme_..." \
-H "Content-Type: application/json" \
-d '{"data":{"attributes":{"welcome":true}}}'
| Field | Required | Notes |
|---|---|---|
welcome |
No | true sends the new-user welcome email (account-ready message with credentials) — use for a freshly created user. Omitted/false sends the standard password-reset email. |
The full onboarding flow for an API-created user is: create → assign a group/location
(user_to_group_location) → reset_password with welcome: true —
the user receives their username and temporary password by email and must set a new password on first
login. Resetting requires the same access as editing the user; SecurityTrax's reserved internal
system accounts can be reset only by SecurityTrax staff.
Editing / deactivating
PATCH /users/{id} updates the editable fields, grouped exactly like the SecurityTrax user form —
and each group honors the same section restrictions as the form (a restricted account can read
these fields but writes return 403):
| Group | Fields | Write also requires |
|---|---|---|
| Identity & contact | name, username, email, phones, fax, address, locale, timezone, marketing group, mobile carrier | not restricted from user account information |
| Preferences | email_reminders, restore_session |
not restricted from user preferences |
| Settings | active, login, include_in_directory |
not restricted from user settings |
| Human resources | hire/start/transfer/last/rehire dates, birthdate, legal_name, ssn, notes, leave_reason, payroll_identifier |
not restricted from user HR information |
| Hierarchy | hierarchy_title_id, hierarchy_title_designation, recruited_by_user_id |
the User Hierarchy permission |
| Inventory & tech | shipping address, tech settings, inventory settings | not restricted from user inventory or account information |
System/platform fields (status, group_id, can_emulate, can_view_pan, password bookkeeping,
audit stamps) remain read-only; writes to them return 422.
DELETE /users/{id} deactivates the user (soft delete — status becomes deleted; the row is
not physically erased). It requires the User delete permission held at any location — the same
company-wide rule as the other verbs; you do not need to share a location with the user. A token
without that permission gets 403. SecurityTrax also reserves a small block of internal system
accounts; only SecurityTrax staff can modify, deactivate, or reset them, so DELETE on those
accounts is rejected regardless of your permissions.
Reading / listing users
GET /users/{id} returns one user; GET /users lists them. Filters: username, email, fname,
lname (all match anywhere in the value), active, and group_id. Sort by id, fname, lname,
username, email, or created_at. Use ?count_only=true for the total. The list is company-wide:
if you hold the User view permission anywhere, it returns every user (including users not yet assigned
to a location), matching the web app's Users admin page — it is not narrowed to your own locations.
Fields
Fields are grouped by the permission that gates them. A group you may not view
is absent from responses; a group you may not write is rejected with 422 when
sent in a write.
Identity
View: the standard userAccountFields rules. Create: the standard userAccountFields rules. Update: the standard userAccountFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
fname |
string (nullable) | Create, update | Required on create; max length 255 |
lname |
string (nullable) | Create, update | Required on create; max length 255 |
username |
string (nullable) | Create, update | Required on create; max length 50 |
Account
View: the standard userAccountFields rules. Create: the standard userAccountFields rules. Update: the standard userAccountFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
email |
string (nullable) | Create, update | Required on create; max length 255; email format |
cell_phone |
string (nullable) | Create, update | max length 100 |
home_phone |
string (nullable) | Create, update | max length 100 |
work_phone |
string (nullable) | Create, update | max length 100 |
fax |
string (nullable) | Create, update | max length 15 |
address |
string (nullable) | Create, update | max length 255 |
locale |
string (nullable) | Create, update | max length 20 |
timezone |
string (nullable) | Create, update | max length 50 |
marketing_group_id |
integer (nullable) | Create, update | — |
mobile_carrier_id |
integer (nullable) | Create, update | — |
Preferences
View: the standard userPreferencesFields rules. Create: the standard userPreferencesFields rules. Update: the standard userPreferencesFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
email_reminders |
boolean (nullable) | Create, update | — |
restore_session |
boolean (nullable) | Create, update | — |
Identity Status
View: the standard userSettingsFields rules. Create: the standard userSettingsFields rules. Update: the standard userSettingsFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
active |
boolean (nullable) | Create, update | — |
Admin Settings
View: the standard userSettingsFields rules. Create: the standard userSettingsFields rules. Update: the standard userSettingsFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
login |
boolean (nullable) | Create, update | — |
include_in_directory |
integer (nullable) | Create, update | min 0; one of: 0, 1 |
Hr
View: the standard userHrFields rules. Create: the standard userHrFields rules. Update: the standard userHrFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
hire_date |
string (nullable) | Create, update | date format Y-m-d |
birthdate |
string (nullable) | Create, update | date format Y-m-d |
start_date |
string (nullable) | Create, update | date format Y-m-d |
transfer_date |
string (nullable) | Create, update | date format Y-m-d |
last_date |
string (nullable) | Create, update | date format Y-m-d |
rehire_date |
string (nullable) | Create, update | date format Y-m-d |
legal_name |
string (nullable) | Create, update | max length 255 |
ssn |
string (nullable) | Create, update | max length 100 |
notes |
string (nullable) | Create, update | — |
leave_reason |
string (nullable) | Create, update | — |
payroll_identifier |
string (nullable) | Create, update | max length 50 |
Hierarchy
View: the standard userHierarchyFields rules. Create: the standard userHierarchyFields rules. Update: the standard userHierarchyFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
hierarchy_title_id |
integer (nullable) | Create, update | min 0 |
hierarchy_title_designation |
string (nullable) | Create, update | max length 100 |
recruited_by_user_id |
integer (nullable) | Create, update | min 0 |
Inventory Tech
View: the standard userInventoryFields rules. Create: the standard userInventoryFields rules. Update: the standard userInventoryFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
shipping_street |
string (nullable) | Create, update | max length 100 |
shipping_city |
string (nullable) | Create, update | max length 100 |
shipping_state |
string (nullable) | Create, update | max length 2 |
shipping_zip |
string (nullable) | Create, update | max length 50 |
tech_comments |
string (nullable) | Create, update | — |
tech_coverage_radius |
integer (nullable) | Create, update | min 0 |
tech_start_address |
string (nullable) | Create, update | max length 100 |
tech_start_city |
string (nullable) | Create, update | max length 100 |
tech_start_state |
string (nullable) | Create, update | max length 2 |
tech_start_zip |
string (nullable) | Create, update | max length 50 |
inventory_recipient |
integer (nullable) | Create, update | — |
inventory_auto_replenish |
integer (nullable) | Create, update | — |
inventory_base_calculator_multiplier |
number (nullable) | Create, update | max 9.99; min 0 |
inventory_recipient_template_id |
integer (nullable) | Create, update | min 0 |
Read Only
View: the standard userBaseFields rules.
| Field | Type | Writable | Validation |
|---|---|---|---|
group_id |
integer (nullable) | Read-only | — |
status |
string (nullable) | Read-only | one of: active, deleted |
in_payroll |
boolean (nullable) | Read-only | — |
max_assigned_leads |
integer (nullable) | Read-only | min 0 |
can_emulate |
boolean (nullable) | Read-only | — |
can_view_pan |
boolean (nullable) | Read-only | — |
force_password_change |
boolean (nullable) | Read-only | — |
last_password_change_time |
datetime (nullable) | Read-only | — |
company_filings_viewed |
string (nullable) | Read-only | — |
employee_id |
string (nullable) | Read-only | max length 50 |
tech_start_latitude |
number (nullable) | Read-only | — |
tech_start_longitude |
number (nullable) | Read-only | — |
created_at |
datetime (nullable) | Read-only | — |
created_by |
integer (nullable) | Read-only | — |
updated_at |
datetime (nullable) | Read-only | — |
updated_by |
integer (nullable) | Read-only | — |
Pagination
The list endpoint uses client-controlled offset pagination: ?page= (1-based) and
?per_page= (default 25, max 100). The response mirrors
meta.pagination (page, per_page, total, last_page) and sends an RFC5988
Link header; follow rel="next" to walk pages. See
Pagination.
Filters
The list endpoint accepts these query-param filters: username, email, fname, lname, active, group_id.
An unsupported filter parameter returns 422. See
Filtering collections
for matching semantics.
Sorting
GET .../users?sort= orders the list by: id, fname, lname, username, email, created_at.
Prefix a field with - for descending; comma-separate for tie-breakers. An
unsupported field returns 422. See
Sorting collections.
Related
- Requests and Responses — envelope, errors, pagination, and rate limits.
- Authentication — tokens and the
Authorizationheader.