Guides

Create subscription events: Migration guide

Suggest Edits

We've combined the PUT subscribeToEmailNotificationsand PUT unsubscribeToEmailNotifications endpoints from API v1 into a single, more efficient endpoint in API v2: Create subscription events.

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

💡

Key changes

  • Bulk operation: The v2 endpoint operates as a bulk endpoint, allowing you to process up to 100,000 subscription events asynchronously. This replaces the individual user subscription/unsubscription actions of the v1 endpoints with a more efficient, batched approach.
  • Restricted scope: The v2 endpoint is restricted and requires the following scope: subscriptions:bulk. To request this scope, reach out to your Customer Success Partner (CSP).
  • HTTP method: The v2 endpoint uses the POST method, while v1 used the PUT method.
  • Terminology: The API v2 uses slightly different terms for managing email subscriptions. Where you previously used subscribe and unsubscribe to email notifications, you'll now use activation and deactivation of subscription events, respectively.

PUT subscribeToEmailNotifications 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/users/subscribeToEmailNotifications
  • API v2: /api/v2/bulk/notifications/subscriptions

Input changes

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

API v1 input example

curl --location --request PUT 'https://app.360learning.com/api/v1/users/subscribeToEmailNotifications?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "usersEmails" : [
        "[email protected]",
        "[email protected]"
    ]
}'

API v2 input example

curl --request POST \
     --url https://app.us.360learning.com/api/v2/bulk/notifications/subscriptions \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "input": [
    {
      "mail": "[email protected]",
      "type": "activation"
    },
    {
      "mail": "[email protected]",
      "type": "deactivation"
    }
  ]
}
'

Main input differences

Change typeAPI v1API v2
Modified
Body parameter		usersEmails: Array of strings. Each string represents a user's email address.mail(Required): Modified name, placement, and data type. Now, this string representing a single user email is nested within an input array of objects.
Added
Body parameter		-input(Required): New array of objects, where each object contains mail and type.
Added
Body parameter		-type(Required): New string within each object in the input array, specifying the subscription event type. Possible values are activation and deactivation. Use activation for subscribing.

Output changes

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

API v1 successful response example

{
    "message": "Success"
}

API v2 successful response example

202 Accepted

Main output differences

API v2 shifted from synchronous to asynchronous operations. Instead of immediate results, it returns a Location header to track bulk operation status.

Change typeAPI v1API v2
Modified
Success output		200202 and Location header with the URL to track the operation status: Changed for asynchronous operation tracking.
Modified
Error code		400400: Refined to provide more specific error messages, including array size limits.
Added
Error codes		-401(Invalid token), 403 (Insufficient scope), 429 (Concurrency limit), 503 (Service unavailable): Added to handle asynchronous processing, authentication, authorization, concurrency, and service availability.

PUT unsubscribeToEmailNotifications 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/users/unsubscribeToEmailNotifications
  • API v2:/api/v2/bulk/notifications/subscriptions

Input changes

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

API v1 input example

curl --location --request PUT 'https://app.360learning.com/api/v1/users/unsubscribeToEmailNotifications?company=347074sad045da327bcfafcf&apiKey=5da7653c2d19442fb3e38c2a46cbcc6f' \
--header 'Content-Type: application/json' \
--data-raw '{
   "usersEmails" : [
        "[email protected]",
        "[email protected]"
    ]
}'

API v2 input example

curl --request POST \
     --url https://app.us.360learning.com/api/v2/bulk/notifications/subscriptions \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "input": [
    {
      "mail": "[email protected]",
      "type": "activation"
    },
    {
      "mail": "[email protected]",
      "type": "deactivation"
    }
  ]
}
'

Main input differences

Change typeAPI v1API v2
Modified
Body parameter		usersEmails: Array of strings. Each string represents a user's email address.mail(Required): Modified name, placement, and data type. Now, this string representing a single user email is nested within an input array of objects.
Added
Body parameter		-input(Required): New array of objects, where each object contains mail and type.
Added
Body parameter		-type(Required): New string within each object in the input array, specifying the subscription event type. Possible values are activation and deactivation. Use deactivation for unsubscribing.

Output changes

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

API v1 successful response example

{
    "message": "Operation succeeded for 2 users."
}

API v2 successful response example

202 Accepted

Main output differences

API v2 shifted from synchronous to asynchronous operations. Instead of immediate results, it returns a Location header to track bulk operation status.

Change typeAPI v1API v2
Modified
Success output		200202 and Location header with the URL to track the operation status: Changed for asynchronous operation tracking.
Modified
Error code		400400: Refined to provide more specific error messages, including array size limits.
Added
Error codes		-401(Invalid token), 403 (Insufficient scope), 429 (Concurrency limit), 503 (Service unavailable): Added to handle asynchronous processing, authentication, authorization, concurrency, and service availability.

Updated 5 days ago