Edit a user: Migration guide

This guide outlines the changes introduced in the Edit a user v2 endpoint (previously known as updateUser in v1).

💡

Key changes

The v2 version of this endpoint introduces a change in the HTTP method used:

• HTTP method: The v2 endpoint uses the PATCH method, while v1 used the PUT method.

Documentation links

Here are the links to the API reference for:

• API v1
• API v2

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

• API v1: /api/v1/users/{user_email}
• API v2: /api/v2/users/{userId}

Input changes

This section details the specific alterations to the input requirements between API versions.

API v1 input example

Shell

curl --location -g --request PUT 'http://app.360learning.com/api/v1/users/5b56f4c392af558eb5f1386c?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
    "firstName": "John"
}'

API v2 input example

Shell

curl --request PATCH \
     --url https://app.360learning.com/api/v2/users/507f1f77bcf86cd799439011 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "firstName": "John",
  "lastName": "Smith",
  "phone": "[phone]",
  "job": "Boss",
  "organization": "360Learning",
  "custom": "Half-time worker",
  "lang": "en",
  "mail": "[email protected]",
  "username": "johnsmith"
}
'

Main input differences

API v2 fosters streamlined data exchanges, focusing on the essential properties of a user. Thus it's not possible anymore to update a user's custom fields through this call. For this you'll have to use the Replace a user custom fields values endpoint.

Change type	API v1	API v2
Removed Body parameter	primaryGroupId: Removed from endpoint v2 version, not replaced.	Use the endpoint Add a user's role and Remove a user's role to update the membership of a user.
Removed Body parameter	password: Removed from endpoint v2 version, not replaced.	Use the endpoint Replace the password of a user to update a user's password.
Added Body parameter	-	custom: (Optional) The new value of the Additional information field in the user’s profile. This is not the value of the custom fields associated with the user.
Added Body parameter	-	username: (Optional) The new username that can be used to log in if the company allows it. Options are: lowercase letters, numbers, and the following special characters: _ - . + # ! $ % & ' * / = ? ^ ` { | } ~.

Output changes

Output is completely changed to follow RESTful principles. Instead of returning an acknowledgment of the user update, we now return the updated user object.

API v1 output example

JSON

{
  "status": "user_updated"
}

API v2 output example

JSON

{
  "_id": "507f1f77bcf86cd799439011",
  "mail": "[email protected]",
  "username": "johnsmith",
  "deleted": true,
  "lang": "bg",
  "firstName": "John",
  "lastName": "Smith",
  "job": "Engineer",
  "organization": "360Learning",
  "phone": "[phone]",
  "custom": "Half-time worker",
  "deletedAt": [
    "2025-06-06T13:21:38.271Z"
  ],
  "reactivatedAt": [
    "2025-06-06T13:21:38.271Z"
  ],
  "lastLoginDate": "2025-06-06T13:21:38.271Z",
  "toBeDeactivatedAt": "2025-06-06T13:21:38.271Z"
}

Main output differences

As shown in the example above, response is completely different, so please refer to the Retrieve a user: Migration guide for more information.

Change type	API v1	API v2
Removed Error code	400 - already_invited	-
Removed Error code	400 - mail_already_exists	-
Removed Error code	400 - user_not_found	-
Removed Error code	400 - 'toDeactivateAt' date must be in the future	-
Removed Error code	400 - mail_used_too_many_times	-
Added Error code	-	400 - deactivationDateInvalid: The given deactivation date must be set to a future date.
Added Error code	-	400 - invalidUpdateOnDeletedUser: The field toBeDeactivatedAt cannot be updated on a deleted user.
Added Error code	-	400 - mailInvalid: The given mail is invalid.
Added Error code	-	400 - mailAlreadyUsed: The given mail is already used.
Added Error code	-	400 - usernameAlreadyUsed: The given username is already used.
Added Error code	-	400 - usernameNotAllowed: The use of username for login is not allowed by your company.