Retrieve a user: Migration guide

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

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}

Behavior changes

The key behavior change is the separation of concerns. Instead of getting user details along with custom fields, certifications, achievements, etc, in one unique call, you now make a specific call to retrieve specific information. This allows for more efficient retrieval of core user information when other related information is not immediately needed.

Input changes

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

API v1 input example

curl --location -g 'https://app.360learning.com/api/v1/users/5b56f4c392af558eb5f1386c?company={{company}}&apiKey={{apiKey}}'

API v2 input example

curl --request GET \
     --url https://app.360learning.com/api/v2/users/5b56f4c392af558eb5f1386c \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token'

Main input differences

Change type	API v1	API v2
Modified Path parameter	`user_email` User's email.	`userId`: User's internal identifier.

Output changes

This section details the specific alterations to the output returned between API versions.

API v1 output example

{
  "_id": "5b56f4c392af558eb5f1386c",
  "mail": "[email protected]",
  "firstName": "Paul",
  "lastName": "Durand",
  "primaryGroupId": "5694ea540fa69fdd0ec0004f",
  "assignedPrograms": 7,
  "averageScore": 76,
  "custom": "updated custom field",
  "certifications": [],
  "customFields": [
    {
      "customFieldId": "610aac9922cc37084f692457",
      "value": "custom_value_0",
      "name": "My New Custom Field"
    }
  ],
  "championAchievements": {
    "coursesCreated": [
      "Champion",
      "Guide",
      "Role Model",
      "Guru"
    ],
    "repliesOnOwnActivitiesGiven": [
      "Educator"
    ],
    "positiveReactionsOnOwnContent": [
      "Recognized"
    ]
  },
  "paths": [
    "Product Rookie",
    "Product Influencer"
  ],
  "comments": 29,
  "completedPrograms": 15,
  "managers": [
    "5bead800990d8867f3c5146c"
  ],
  "subordinates": [
    "5c4f0499928e2f55fa8d3664",
    "5bead808880d8862f3c51473"
  ],
  "labels": [
    "LabelCreatedWithTheAPI 0",
    "LabelCreatedWithTheAPI 1"
  ],
  "groups": [
    {
      "_id": "5694ea540fa69fdd0ec0004f",
      "name": "360Learning",
      "public": false
    },
    {
      "_id": "5ae6f360c3b99d7884975380",
      "name": "EXTERNAL",
      "public": false,
      "parent": "5694ea540fa69fdd0ec0004f"
    }
  ],
  "imageUrl": "https://team.360mooc.com/api/medias/user/5be3e234a7df8c2534ec570c",
  "lastLoginAt": "2019-11-07T09:30:19.716Z",
  "championStatus": "champion",
  "learnerAchievements": {
    "repliesGiven": [
      "Helping hand",
      "Contributor"
    ],
    "reactionsGiven": [
      "Community member",
      "Supporter"
    ],
    "coursesPlayed": [
      "Curious",
      "Diligent"
    ]
  },
  "messages": 64,
  "publications": 1,
  "reactions": 123,
  "skills": [
    {
      "_id": "5be5e234caaa8c3534ec570c",
      "name": "Trello Expert",
      "assessmentScore": "",
      "averageScore": 100,
      "eLearningScore": 100
    }
  ],
  "toDeactivateAt": "",
  "totalTimeSpentInMinutes": 2527
}

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-06T12:58:22.531Z"
  ],
  "reactivatedAt": [
    "2025-06-06T12:58:22.531Z"
  ],
  "lastLoginDate": "2025-06-06T12:58:22.531Z",
  "toBeDeactivatedAt": "2025-06-06T12:58:22.531Z"
}

Main output differences

API v2 provides a more streamlined response, focusing on the essential properties of a user.

The user details (memberships, custom fields, managers) are no longer embedded in the response. Use the appropriate calls listed below to get this information.

Change type	API v1	API v2
Removed Output property	`primaryGroupId`: Removed from endpoint v2 version.	User's memberships can be retrieved through List all memberships of a user
Removed Output property	`groups`: Removed from endpoint v2 version.	User's memberships can be retrieved through List all memberships of a user
Removed Output property	`customFields`: Removed from endpoint v2 version.	User's custom fields values can be retrieved through List all custom fields values for a user
Removed Output property	`managers`: Removed from endpoint v2 version.	User's managers can be retrieved through List all manager IDs for a user