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:

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

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

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": "+33123456789",
  "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

{
  "status": "user_updated"
}

API v2 output example

{
  "_id": "507f1f77bcf86cd799439011",
  "mail": "[email protected]",
  "username": "johnsmith",
  "deleted": true,
  "lang": "bg",
  "firstName": "John",
  "lastName": "Smith",
  "job": "Engineer",
  "organization": "360Learning",
  "phone": "+33123456789",
  "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.