List all users: Migration guide

This guide outlines the changes introduced in the List all users v2 endpoint (previously known as getUsers in v1).

💡

Key changes

• Pagination: The v2 endpoint is paginated and returns 500 users per page.

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
• API v2: /api/v2/users

Input changes

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

API v1 input example

Shell

curl --location -g 'https://{{host}}/api/v1/users?company={{company}}&apiKey={{apiKey}}'

API v2 input example

Shell

curl --request GET \
     --url https://app.staging.360learning-dev.com/api/v2/users \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json'

Main input differences

Change type	API v1	API v2
Removed Query parameter	deleted (Optional): Removed from endpoint v2 version, not replaced.	-

Output changes

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

API v1 output example

JSON

[
  {
    "_id": "58eb5dad1a92bb4fb526b2d3",
    "mail": "[email protected]",
    "firstName": "Apprenant",
    "lastName": "Groupe1",
    "custom": "AZE123",
    "primaryGroupId": "5694ea540fa69fdd0ec0004f"
  }
]

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-30T13:23:56.059Z"
    ],
    "reactivatedAt": [
      "2025-06-30T13:23:56.059Z"
    ],
    "lastLoginDate": "2025-06-30T13:23:56.059Z",
    "toBeDeactivatedAt": "2025-06-30T13:23:56.059Z"
  }
]

Main output differences

API v2 introduces pagination for the List all users endpoint. Instead of returning all groups in a single response, it now returns a maximum of 500 users per page. To retrieve subsequent pages, you need to follow the URL provided in the Link header of the response.

Change type	API v1	API v2
Removed Output property	primaryGroupId (Required): Removed from endpoint v2 version, not replaced.	-
Added Output property	-	deleted (Required): Indicate whether the user is currently deleted (deactivated) or not.
Modified Success response	200: Returns an array of all users.	200: Returns one page of 500 users.
Added Header	-	Link: String. URL (between < and >) to fetch the immediate next page of results. Only included if there is another page of results.