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:

• API v1
• API v2

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:

1. 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.
2. 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

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.