List all ID mappings: Migration guide

This guide details how the List all ID mapping endpoint has changed (previously known as getUserByExternalId in v1).

💡
Key changes

Terminology and behavior: The v2 endpoint's purpose is to list generic ID mappings, not just retrieve users. Where you previously retrieved a full user object, you now retrieve a mapping object that links an external ID to an internal resource ID. For more information about how to retrieve the full profile of a user based on their external ID, see the Behavior changes section below.

Pagination: The v2 endpoint is paginated with a page size of 5000 external IDs, and returns a Link header to fetch subsequent pages of results, if any.

Filtering: Filtering is significantly more flexible and powerful. The rigid path parameters from v1 (externalId, externalPlatform) are replaced by query parameters that allow for more complex queries. You can now filter on the resource type (e.g., user, course), the platform, the external value, and the internal targetId.

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/getUserByExternalId/:externalId/:externalPlatform
API v2: /api/v2/external-ids

Behavior changes

The fundamental behavior of the endpoint has changed.

The v1 endpoint was designed to retrieve a single, complete user profile based on an external identifier.
The v2 endpoint is a more generic mapping service that returns an array of mappings, not the final user object.

As a result, retrieving a user's full profile is now a two-step process:

Find the user's internal ID: Use the List all ID mappings endpoint and filter by type[eq]=user and value[eq]={externalId}.
This call returns a mapping object containing the user's unique internal ID in the targetId field.
Retrieve the user's profile: Use the targetId from the previous step to make a second API call to the separate Retrieve a user endpoint.
This request will return the complete user profile, including their email and name.

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/getUserByExternalId/14562/BambooHR?company={{company}}&apiKey={{apiKey}}'

API v2 input example

curl --request GET \
     --url 'https://app.360learning.com/api/v2/external-ids?value[eq]=14562&type[eq]=user' \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_access_token>'

Main input differences

Change type	API v1	API v2
Modified Parameter	`externalPlatform` (Required): The name of the platform where the external ID comes from.	`platform` (Optional): Modified name, placement, and syntax. This parameter is now an optional query parameter that supports filtering using LHS bracket notation.
Modified Parameter	`externalId` (Required): Path parameter used to identify the user.	`value`(Optional): Modified name, placement, and syntax. This parameter is now an optional query parameter that supports filtering using LHS bracket notation. To find a user, this should be set to the value of their external ID.
Added Query parameter	-	`type` (Optional): New query parameter to filter mappings by resource type. To find a user, this should be set to `user`. Possible values: `attempt`, `classroom`, `classroomAttendance`, `classroomAttendanceSheet`, `classroomSlot`, `classroomSlotRegistration`, `course`, `group`, `learningNeed`, `path`, `pathEnrollment`, `pathSession`, `pathTracking`, `registrationRequest`, `user`.
Added Query parameter	-	`targetID` (Optional): New query parameter to filter mappings by the internal ID of the resource.

Output changes

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

API v1 output example

{
  "_id": "5b56f4c392af558eb5f1386c",
  "mail": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "primaryGroupId": "5694ea540fa69fdd0ec0004f"
}

API v2 output example

[
  {
    "platform": "BambooHR",
    "targetId": "5b56f4c392af558eb5f1386c",
    "targetType": "user",
    "value": "14562",
    "_id": "6b37f4c392af558eb5f1386c"
  }
]

Main output differences

API v2 returns an array of mapping objects instead of a single user object.
API v2 is paginated with a page size of 5000 external IDs.

Change type	API v1	API v2
Removed Output property	`mail`: The mail of the user matching the request. Removed from this endpoint v2 .	- (Can be retrieved via Retrieve a user, using `targetId` as the user identifier).
Removed Output property	`firstName`: The first name of the user matching the request. Removed from this endpoint v2.	- (Can be retrieved via Retrieve a user, using `targetId` as the user identifier).
Removed Output property	`lastName`: The last name of the user matching the request. Removed from this endpoint v2.	- (Can be retrieved via Retrieve a user, using `targetId` as the user identifier).
Removed Output property	`primaryGroupId`: The primary group of the user, if any. Removed from endpoint v2.	-
Modified Output property	`_id`: The internal ID of the user.	`targetId` (Required): Renamed. The internal ID of the mapped resource (e.g., the user).
Added Header	-	`Link` (Optional): New header returned for pagination when more results are available.
Added Output property	-	`platform` (Required): The name of the platform where the external ID comes from.
Added Output property	-	`targetType` (Required): The resource type to which the external ID is linked. Possible values: `attempt`, `classroom`, `classroomAttendance`, `classroomAttendanceSheet`, `classroomSlot`, `classroomSlotRegistration`, `course`, `group`, `learningNeed`, `path`, `pathEnrollment`, `pathSession`, `pathTracking`, `registrationRequest`, `user`.
Added Output property	-	`value` (Required): The value of the external ID.
Added Output property	-	`_id` (Required): The unique ID that identifies the resources mapping.

💡Key changes