Create an ID mapping: Migration guide

This guide details how the Create an ID mapping endpoint has changed (previously known as addExternalIdToUser in v1).

💡
Key changes

HTTP method: The v2 endpoint uses the POST method, while v1 used the PUT method.

Identifier type: The v2 endpoint requires a user's unique ID. It no longer accepts an email address as a direct identifier. Migrating requires extra steps if you previously used email. For more information, see the How to identify users in v2 section below.

Terminology and behavior: The API v2 uses a more generic "ID mapping" concept. Where you previously managed an externalId specifically for a user, you now create a mapping for various resource types by specifying a targetType.

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

Behavior changes

The v2 endpoint is designed to be more flexible. Instead of exclusively linking an external ID to a user, it can now create a mapping for various resource types (e.g., user, course, group). This is specified via the targetType field in the request body.

How to identify users in v2

For this endpoint, use the user's internal ID in the targetID field.

A key update in v2 is the standardized method for identifying users. For improved security and consistency, you must now use the user's unique internal ID when referencing a user.

If you already have the internal ID, you can use it directly.
If you only have the user's email address, you'll need to fetch their internal ID first.

To get the user ID based on their email address:

Retrieve and cache all users:
Call List all users to retrieve the full list of users in your organization. To ensure your application is performant, this data should be stored in a local database or cache that is updated periodically.
Find the user and get their ID:
Find the user object where the mail field matches the email you are searching for.
Copy the value of their _id. This is the internal ID.

Input changes

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

API v1 input example

curl --location -g --request PUT 'https://app.360learning.com/api/v1/users/[email protected]/externalId?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'externalPlatform=BambooHR' \
--data-urlencode 'externalId=14562'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/external-ids \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer your_access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "targetType": "user",
  "platform": "BambooHR",
  "targetId": "68491a8338669364cc69b6d0",
  "value": "14562"
}
'

Main input differences

Change type	API v1	API v2
Modified Parameter	`user_email` (Path parameter, Required): Could be the email or the ID of the user. This parameter email was part of the URL path.	`targetId` (Body parameter, Required): The ID for the resource (e.g., user ID) is now a required string in the request body. Must be the user's internal ID. An email is no longer accepted here. See Behavior changes (section above) for how to get the ID from an email.
Modified Body Parameter	`externalPlatform`: The name of the HRIS.	`platform` (Required): Renamed. Now sent within a JSON request body.
Modified Body Parameter	`externalId`: The user's ID in the external platform.	`value` (Required): Renamed. Represents the external ID value and is now sent within a JSON request body.
Added Body parameter	-	`targetType`: (Required): Specifies the type of resource being mapped. To replicate v1 behavior, set this to `user`.

Output changes

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

API v1 output example

{
  "status": "external_id_updated"
}

API v2 output example

{
  "platform": "BambooHR",
  "targetId": "68491a8338669364cc69b6d0",
  "targetType": "user",
  "value": "14562",
  "_id": "507f1f77bcf86cd799439011"
}

Main output differences

API v2 returns a 201 Created status and the full mapping resource that was created, including a new unique ID for the mapping itself (_id). This replaces the simple status message from v1.

Change type	API v1	API v2
Removed Output property	`status`: The status message has been removed.	-
Modified Success output	`200 OK` with a status message in the body.	`201 Created` with the created resource object in the body.
Added Output parameter	-	`platform` (Required): The name of the platform where the external ID comes from.
Added Output parameter	-	`targetId`(Required): The resource ID to which the external ID is linked.
Added Output parameter	-	`targetType`: (Required): Specifies the type of resource being mapped. To replicate v1 behavior, this will be set to `user`.
Added Output parameter	-	`value` (Required): The value of the external ID.
Added Output parameter	-	`_id` (Required): The unique ID that identifies the resources mapping.

💡Key changes