Replace a path session audience: Migration guide

We've combined the addUsersToPathSessionand addGroupsToPathSession endpoints from API v1 into a single, more efficient endpoint in API v2: Replace a path session audience.

This guide outlines the key differences you'll encounter when moving to API v2:

From addUsersToPathSession
From addGroupsToPathSession

💡
Key changes
Important: the v2 endpoint to update a path session audience only supports paths created with the Audience Builder. You will not be able to update the audience of paths having been created with the legacy behavior.

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

`addUsersToPathSession` migration

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/paths/sessions/:sessionId/users
API v2: /api/v2/paths/{pathId}/sessions/{sessionId}/audiences

Behavior changes

This v2 endpoint works on a Replace mechanism. It means that the path session audience will be overridden by what you are sending to it through the input payload. In order to do a differential update only, you must first Retrieve a path session audience for the path session in question, perform your delta update in the audience, then send back everything to the v2 endpoints Replace a path session audience.

How to identify users in v2

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 PATCH 'https://{{host}}/api/v1/paths/sessions/:sessionId/users?company={{company}}&apiKey={{api_key}}' \
--header 'Content-Type: application/json' \
--data '{
    "userEmails":[
        "user_email_0",
        "user_email_1",
        "user_email_2"
    ]
}'

API v2 input example

curl --request PUT \
     --url https://app.360learning.com/api/v2/paths/507f1f77bcf86cd799439011/sessions/507f1f77bcf86cd799439011/audiences \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "mode": "dynamic",
  "filters": [
    {
      "type": "users",
      "ids": [
        "507f1f77bcf86cd799439011",
        "507f1f77bcf86cd799439011"
      ]
    },
		{
      "type": "excludedLearners",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
		{
      "type": "groups",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    }
  ]
}
'

Main input differences

V1 and v2 endpoints are completely different, please pay close attention to the table below, exhaustively explaining all the input differences.

To replicate the behavior of the API v1 addUserstoPathSession endpoint, you should use the v2 endpoint Replace a path session audience with an updated filter of type users (see below).

Change type	API v1	API v2
Removed Body parameter	`userEmails` (Required): Removed from endpoint v2 version, replaced by `users` filter (see below).	-
Added Body parameter	-	`filters` (Required): List of filters (array) in the audience, being of types `users`, `groups` or `excludedLearners` (see below for descriptions)
Added Body parameter	-	`filters (type = users)` (Optional): Filter containing the list of users' unique IDs to enroll in the path session. See Behavior changes (section above) for how to get the ID from an email.
Added Body parameter	-	`filters (type = excludedLearners)` (Optional): Filter containing the list of users' unique IDs to exclude from the path session. See Behavior changes (section above) for how to get the ID from an email.
Added Body parameter	-	`filters (type = groups)` (Optional): Filter containing the list of groups' unique IDs to enroll in the path session.
Added Body parameter	-	`mode` (Optional): Audience builder update mode, being either dynamic or manual.
Added Path parameter	-	`pathId` (Required): Path unique ID.

Output changes

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

API v1 output example

{
  "success": "user(s) successfully assigned"
}

API v2 output example

{
  "filters": [
    {
      "type": "users",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
    {
      "type": "groups",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
    {
      "type": "excludedLearners",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    }
  ],
  "mode": "dynamic"
}

Main output differences

The response of the v2 endpoint contains the updated audience builder filters. Thus it has the very same structure as the input payload, and reflects the changes you've sent with this call.

`addGroupsToPathSession` migration

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/paths/sessions/:sessionId/groups
API v2: /api/v2/paths/{pathId}/sessions/{sessionId}/audiences

Behavior changes

How to identify users in v2

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 PATCH 'https://{{host}}/api/v1/paths/sessions/5cb8a717eaaa4c504c3e9459/groups?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
    "groupIds": [
        "5cb8a717eaaa4c504c3e9456",
        "5cb8a717ec3f4c5aaa3e9456"
    ]
}'

API v2 input example

curl --request PUT \
     --url https://app.360learning.com/api/v2/paths/507f1f77bcf86cd799439011/sessions/507f1f77bcf86cd799439011/audiences \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "mode": "dynamic",
  "filters": [
    {
      "type": "users",
      "ids": [
        "507f1f77bcf86cd799439011",
        "507f1f77bcf86cd799439011"
      ]
    },
		{
      "type": "excludedLearners",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
		{
      "type": "groups",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    }
  ]
}
'

Main input differences

V1 and v2 endpoints are completely different, please pay close attention to the table below, exhaustively explaining all the input differences.

To replicate the behavior of the API v1 addGroupstoPathSession endpoint, you should use the v2 endpoint Replace a path session audience with an updated filter of type groups (see below).

Change type	API v1	API v2
Removed Body parameter	`groupIds` (Required): Removed from endpoint v2 version, replaced by `groups` filter (see below).	-
Added Body parameter	-	`filters` (Required): List of filters (array) in the audience, being of types `users`, `groups` or `excludedLearners` (see below for descriptions)
Added Body parameter	-	`filters (type = users)` (Optional): Filter containing the list of users' unique IDs to enroll in the path session. See Behavior changes (section above) for how to get the ID from an email.
Added Body parameter	-	`filters (type = excludedLearners)` (Optional): Filter containing the list of users' unique IDs to exclude from the path session. See Behavior changes (section above) for how to get the ID from an email.
Added Body parameter	-	`filters (type = groups)` (Optional): Filter containing the list of groups' unique IDs to enroll in the path session.
Added Body parameter	-	`mode` (Optional): Audience builder update mode, being either dynamic or manual.
Added Path parameter	-	`pathId` (Required): Path unique ID.

Output changes

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

API v1 output example

{
  "success": [
    "5cb8a717eaaa4c504c3e9456",
    "5cb8a717ec3f4c5aaa3e9456"
  ]
}

API v2 output example

{
  "filters": [
    {
      "type": "users",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
    {
      "type": "groups",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    },
    {
      "type": "excludedLearners",
      "ids": [
        "507f1f77bcf86cd799439011"
      ]
    }
  ],
  "mode": "dynamic"
}

Main output differences

The response of the v2 endpoint contains the updated audience builder filters. Thus it has the very same structure as the input payload, and reflects the changes you've sent with this call.

💡Key changes

addUsersToPathSession migration

Documentation links

Endpoint mapping

Behavior changes

How to identify users in v2

Input changes

API v1 input example

API v2 input example

Main input differences

Output changes

API v1 output example

API v2 output example

Main output differences

addGroupsToPathSession migration

Documentation links

Endpoint mapping

Behavior changes

How to identify users in v2

Input changes

API v1 input example

API v2 input example

Main input differences

Output changes

API v1 output example

API v2 output example

Main output differences

💡
Key changes

`addUsersToPathSession` migration

`addGroupsToPathSession` migration