Freezing, Archiving and Deleting Users via the AMS API

This article explains how to freeze, archive or delete user accounts within the Assurance Monitoring System (AMS) using the public API.

These three actions provide different ways of managing users who have left an organisation, no longer require access or should no longer appear within the system.

Understanding the differences is important for maintaining system security, preserving historical information and ensuring accurate reporting across AMS and ProHealth (PHA).

Before you start

Required API permissions

• read_users - Retrieve user information.

• write_users - Update user accounts.

• write_frozen_users - Freeze or unfreeze users.

• allow_archive_user - Archive users.

• delete_users - Delete user accounts.

Important: Freezing, archiving and deleting are separate actions, each with different implications for user access, visibility and historical information.

Understanding the differences

Freezing a user

Freezing a user prevents them from logging in while retaining their account and associated historical information.

This was designed to allow organisations to remove a user's access immediately without losing the ability to find and reference their previous activity.

Key notes

• The user can no longer log in.

• The user account and historical information are retained.

• The user can still be found and referenced in reports.

• Previous activity and associated records remain available.

• This is particularly useful within PHA, where organisations may need to review assessments previously completed against an individual.

• Historical information may also be relevant to reporting, investigations, audit requirements or other operational purposes.

When to use: When a member of staff leaves the organisation or requires their access removed, but their historical information should remain visible and reportable.

Archiving a user

Archiving a user removes them from the active interface and excludes them from normal reporting, while retaining the underlying historical information rather than deleting the account.

This is designed for circumstances where an organisation no longer wants an individual to appear within the system or its reports.

Key notes

• The user is removed from the normal interface.

• The user no longer appears in standard reports.

• The user's underlying record is retained rather than deleted.

• Archived accounts can still be identified through the API's archived-user filtering.

• Archiving is useful where historical records need to be preserved but the individual should no longer be referenced in normal day-to-day activities or reporting.

When to use: When a user should no longer appear in the system or its normal reports, but their underlying record should be retained.

Deleting a user

Deleting a user removes their account from AMS.

Unlike freezing or archiving, deletion is intended for removing an account rather than retaining it for future reference.

Key notes

• The user account is deleted.

• The action requires the delete_users permission.

• The API provides a dedicated deletion endpoint.

• The API documentation does not fully describe how deletion affects historical records or associated data.

When to use: When an account needs to be deleted rather than frozen or archived, and the implications of removal have been considered.

Which option should I choose?

Setup order

1. Step 1 - Identify the user account.

2. Step 2 - Freeze a user.

3. Step 3 - Archive a user.

4. Step 4 - Delete a user.

5. Step 5 - Verify the outcome.

Step 1 - Identify the user account

Before freezing, archiving or deleting an account, retrieve the user information to confirm that the correct person has been selected.

Endpoint: GET /v2/admin/users

Permission required: read_users

The endpoint supports filters including email, name and surname.

Example request

GET /v2/admin/users?email=alex.example@example.org

To retrieve an individual account:

Endpoint: GET /v2/admin/users/{userId}

Replace {userId} with the account's unique AMS user ID.

Key notes

• Confirm the user's identity before making changes.

• Record the user ID for the following steps

Step 2 - Freeze a user

Freezing is recommended when the immediate requirement is to prevent login while preserving the user's existing records and visibility within reports.

Endpoint: PATCH /v2/admin/users/{userId}

Permissions required: write_users and write_frozen_users

Example request body

{
  "frozen": 1
}

Key notes

• Setting frozen to 1 freezes the account.

• The user can no longer log in.

• The account and its historical information remain available.

• A user cannot freeze or unfreeze their own account.

• Freezing can be reversed by an authorised user.

Verify the account is frozen

Endpoint: GET /v2/admin/users?frozen=frozen

The user-list endpoint supports three frozen-status filters:

• normal - Users who are not frozen.

• frozen - Users whose accounts are frozen.

• both - Both frozen and non-frozen users.

Successful response: 200 OK

Step 3 - Archive a user

Archiving removes a user from the normal AMS interface and standard reporting, without deleting the underlying account record.

Endpoint: PATCH /v2/admin/users/archive/{userId}

Permission required: allow_archive_user

Key notes

• The user is removed from normal interface listings.

• The user is excluded from standard reports.

• The account record is retained.

Verify the account is archived

Endpoint: GET /v2/admin/users

Use the user_status parameter to filter results.

Example request

GET /v2/admin/users?user_status=3

This returns archived users accessible to the authenticated account.

Successful response: 200 OK

Step 4 - Delete a user

Deleting removes a user account from AMS.

Endpoint: DELETE /v2/admin/users/{userId}

Permission required: delete_users

Key notes

• The request targets the specified user account.

• The operation requires the appropriate deletion permission.

• Deletion should not be used interchangeably with freezing or archiving.

• Previous tasks, management assigned to this user will need to be reallocated before deletion through delegating endpoints.

Important: Where historical information needs to remain available for reporting, auditing or review, consider whether freezing or archiving is more appropriate.

Verify deletion

Check the response from the deletion request.

Successful response: 200 OK

A subsequent user lookup can be used to check whether the account remains accessible.

Step 5 - Verify the outcome

After submitting an account-management request, verify that the intended change has taken effect.

Recommended checks

• Frozen user: Confirm the account appears when filtering for frozen users and that login access is prevented.

• Archived user: Confirm the account is excluded from normal user listings but appears in archived-user results.

• Deleted user: Confirm the deletion request succeeded and that the account is no longer returned as an active user.

Where relevant, review the associated reporting behaviour to ensure it aligns with the intended action.

Common errors

The API provides an endpoint containing documented application errors:

Endpoint: GET /v2/admin/errors

Common HTTP responses include:

• 200 OK - The operation completed successfully.

• 401 Unauthenticated - Authentication is missing, invalid or expired.

• 403 Forbidden - The calling account does not have sufficient permissions.

Troubleshooting tip: If a request fails, first confirm that the correct user ID has been supplied and that the account making the request has the appropriate permissions.

Additional information

Preserving historical records

Freezing was designed specifically to preserve access to a user's historical information after their login access has been removed.

This is particularly relevant to PHA assessments, where an individual may have previous assessments that need to remain searchable and reportable.

It can also support wider operational requirements within AMS, including historic activity, reporting and audit records.

Archiving provides an alternative where an individual should no longer appear in normal system interfaces or reporting but their underlying record should not be deleted.

API limits and bulk operations

The documented freeze, archive and delete operations target individual user accounts.

For large-scale user offboarding or account synchronisation, contact the AMS support team to agree the appropriate integration approach.