Overview

This article explains how to find existing AMS user accounts, retrieve their details and update information through the public API.

This is useful when synchronising user records from external HR, workforce or identity-management systems.

If you need to create new accounts, first see Creating and Managing AMS via API.

Before you start

Required API permissions

• read_users - retrieve user information.

• write_users - update user information.

• write_permission_user - change permission groups.

• write_user_department - manage departmental assignments.

You will also need the ID of any existing user you intend to update.

Setup order

1. Step 1 - Find an existing user

2. Step 2 - Retrieve the user's details

3. Step 3 - Update the user

4. Step 4 - Update external manager relationships

5. Step 5 - Verify the changes

Step 1 - Find an existing user

Endpoint: GET /v2/admin/users

Permission required: read_users

This endpoint returns users accessible to the authenticated API account.

Non-root users can only retrieve users associated with their company.

Available filters include

• email - user's email address.

• name - first name.

• surname - surname.

• reference - user reference. This is used only in the PHA application.

• ids[] - one or more user IDs.

• frozen - frozen account status.

• user_status - archived account status.

Example request

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

Pagination

The user list supports the following parameters:

• page - page number.

• page_size - number of results requested per page.

Example request

GET /v2/admin/users?page=1&page_size=50

For large organisations, use pagination to retrieve users in manageable sets.

Searching by service number

The API supports a service_number field when creating or updating users. This is a quality of life attribute used to help identify users between AMS and the external HR or user account system. It is not used anywhere else within the AMS system.

Important: Confirm the appropriate method of matching service numbers before using them as the main identifier for an automated synchronisation.

Step 2 - Retrieve the user's details

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

Permission required: read_users

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

Example request

GET /v2/admin/users/123

Use the response to confirm that you have identified the correct account before making changes.

Step 3 - Update the user

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

Permission required: write_users

This endpoint allows an existing user account to be amended.

Supported request fields include

• name

• surname

• email

• company_id

• mail_otp

• service_number

• frozen

Example request body

{
  "name": "Alex",
  "surname": "Example",
  "email": "alex.example@example.org",
  "service_number": "EMP12345"
}

• Changes to name or surname create a new version of the user's profile.

• company_id may be ignored by most users - it is only used for system administrators.

• MFA changes should use the dedicated MFA endpoints.

• Freezing a user requires additional permission.

Step 4 - Update external manager relationships

Endpoint: PATCH /v2/admin/users/{userId}/external-hierarchy

Permission required: write_users

This endpoint supports external employee and manager references.

Example request body

{
  "external_employee_id": "EMP12345",
  "external_manager_id": "EMP10001"
}

• Both fields are optional and nullable.

• External identifiers are limited to 100 characters.

• Employee identifiers must be unique within the company.

• The manager identifier must reference an existing user within the same company.

• Users cannot be their own manager.

• Circular manager relationships are not permitted.

Common errors

• hierarchy.001 - user cannot manage themselves.

• hierarchy.002 - circular reporting relationship.

• hierarchy.003 - manager not found.

• hierarchy.004 - manager belongs to another company.

• hierarchy.005 - duplicate employee identifier.

Important: External manager relationships are separate from AMS departmental manager appointments.

To appoint someone as the manager of an AMS department, use the dedicated department-management endpoint.

Step 5 - Verify the changes

Retrieve the user again:

GET /v2/admin/users/{userId}

Confirm that the updated details match the information submitted.

For department assignments, use:

GET /v2/admin/users/{userId}/department