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:

• API v1
• API v2

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.

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

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.