List all learning needs: Migration guide

This guide outlines the changes introduced in the List all learning needs v2 endpoint (previously known as GET listLearningNeeds in v1).

💡
Key changes

Pagination: The v2 endpoint is paginated with a page size of 500 learning needs. A Link header is provided to fetch subsequent pages.

Property renaming: Field names have been updated for consistency and clarity.

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/learningneeds
API v2: /api/v2/learning-needs

Input changes

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

API v1 input example

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

API v2 input example

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

Output changes

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

API v1 output example

[
  {
    "_id": "634f418bd1c19f021bca0df9",
    "group": "507f1f77bcf86cd799439011",
    "name": "Cross-Cultural Communication",
    "status": "new",
    "declaredAt": "2022-10-19T00:15:07.000Z",
    "declaredBy": "6234e14c9ce27e1cbe0cebb8",
    "questions": [
      {
        "mandatory": true,
        "title": "What is the problem that creating this training would solve?",
        "answer": "It would strengthen the ties between the US and French Staff"
      }
    ],
    "suggestedExperts": [],
    "volunteers": []
  }
]

API v2 output example

[
  {
    "_id": "634f418bd1c19f021bca0df9",
    "groupId": "507f1f77bcf86cd799439011",
    "name": "Cross-Cultural Communication",
    "status": "new",
    "createdAt": "2026-03-30T14:52:45.765Z",
    "authorId": "6234e14c9ce27e1cbe0cebb8",
    "questions": [
      {
        "title": "What is the problem that creating this training would solve?",
        "answer": "It would strengthen the ties between the US and French Staff."
      }
    ],
    "suggestedExpertIds": [
      "507f1f77bcf86cd799439011"
    ],
    "volunteerIds": [
      "507f1f77bcf86cd799439011"
    ]
  }
]

Main output differences

API v2 shifted from returning a full list to a paginated model. It returns a maximum of 500 objects per request and includes a Link header to fetch the next page.

Several output properties have been renamed for consistency and to explicitly indicate when a field contains an array of IDs.

Change type	API v1	API v2
Removed Output property	`mandatory`: Removed from endpoint v2 version, not replaced.
Modified Success output	`200`: Returns the full list of learning needs in a single response.	`200`: Returns a paginated list (max 500). Includes a `Link` header for the next page of results.
Modified Output property	`group`: String representing the linked group ID.	`groupId`: Renamed for clarity.
Modified Output property	`declaredAt`: Descriptive naming for creation date.	`createdAt`: Renamed to standard resource metadata naming.
Modified Output property	`declaredBy`: Descriptive naming for author.	`authorId`: Renamed to standard resource metadata naming.
Modified Output property	`suggestedExperts`: Arrays of user IDs.	`suggestedExpertIds`: Renamed to indicate the fields contain identifiers.
Modified Output property	`volunteers`: Arrays of user IDs.	`volunteerIds`: Renamed to indicate the fields contain identifiers.