Migrate getExternalCourse (using external ID)

This guide details how to migrate from the v1 getExternalCourse (using external ID) endpoint to the new v2 architecture. To replicate the v1 response, your integration must now perform a two-step "join" operation.

💡
Key changes
Decoupled data model: In API v2, you must call 2 endpoints to retrieve the full dataset previously available in a single v1 call.

Step 1: Call the Retrieve an external course v2 endpoint using the externalId. This response includes a courseId field.

Step 2: Use that courseId to call the Retrieve a course v2 endpoint, and get course attributes.

Documentation links

Here are the links to the API reference for:

API v1
API v2:
- Step 1: Retrieve an external course
- Step 2: Retrieve a course

Step 1: Retrieve an external course metadata

The first step is to call the Retrieve an external course v2 endpoint. This identifies the content via its integration and external IDs and retrieves the internal 360Learning course ID required for the second step.

Endpoint mapping (Step 1):

API v1: /api/v1/externalContents/groups/:groupId/externalPlatforms/:externalPlatform/courses/:externalId
API v2: /api/v2/integrations/{integrationId}/courses/{externalId}

Input changes (Step 1)

API v1 input example

curl --location -g 'https://app.360learning.com/api/v1/externalContents/groups/62be0535045424d93edaad7b/externalPlatforms/myPlatform/courses/l3ssup3rh3r0s'

API v2 input example (Step 1)

curl --request GET \
     --url https://app.360learning.com/api/v2/integrations/507f1f77bcf86cd799439011/courses/a3215H-7 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token'

Main input differences (Step 1)

Change type	API v1	API v2
Removed Path parameter	`groupId`: ID of the group where external contents were imported.
Removed Path parameter	`externalPlatform`: Name of the external platform to which the external content is attached.
Added Path parameter		`integrationId` (Required): The unique ID of the specific integration. This replaces the group/platform context logic.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.

Output changes (Step 1)

API v1 output example

{
  "id": "6463973f9b19ff7b9ca674e9",
  "authorId": "62bdbc00293a604543f44386",
  "archived": false,
  "title": "Machine Learning Crash Course",
  "description": "Learn the basics of machine learning.",
  "language": "en",
  "courseDuration": 10,
  "skills": [
    "63970d8ec2675a57f2b3f509"
  ],
  "externalId": "l3ssup3rh3r0s",
  "externalPlatform": "myPlatform",
  "groupId": "62be0535045424d93edaad7b",
  "authors": [
    "John Doe"
  ],
  "alternativeLanguages": [
    "fr"
  ],
  "launchUrl": "https://player.mylearningplatform.com/ql/fg-q6dfax2e_6ys",
  "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/fg-q6dfax2e_6ys",
  "thumbnailUrl": "https://upload.wikimedia.org/wikipedia/commons/0/07/Wikipedia_logo_%28svg%29.svg",
  "difficultyLevel": "beginner",
  "contentType": "course",
  "numberOfVideos": 1,
  "sources": [
    {
      "name": "Wikipedia",
      "logo": "https://en.wikipedia.org/static/images/icons/wikipedia.png"
    }
  ],
  "subjects": [
    "Machine learning"
  ]
}

API v2 output example (Step 1)

{
  "defaultLang": "en",
  "externalId": "l3ssup3rh3r0s",
  "launchUrl": "https://player.mylearningplatform.com/ql/fg-q6dfax2e_6ys",
  "name": "Machine Learning Crash Course",
  "sources": [
    {
      "name": "Wikipedia",
      "logoUrl": "https://en.wikipedia.org/static/images/icons/wikipedia.png"
    }
  ],
  "subjects": [
    "Machine Learning",
    "IT"
  ],
  "contentType": "course",
  "description": "Learn the basics of machine learning.",
  "difficultyLevel": "beginner",
  "duration": 10,
  "imageUrl": "https://player.mylearningplatform.com/image/l3ssup3rh3r0s",
  "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/launch/l3ssup3rh3r0s",
  "authorId": "62bdbc00293a604543f44386",
  "courseId": "6463973f9b19ff7b9ca674e9",
  "translations": [
    {
      "lang": "fr",
      "translatedFields": {
        "description": "Apprenez les bases de l'apprentissage automatique.",
        "launchUrl": "https://player.mylearningplatform.com/launch/l3ssup3rh3r0s/fr",
        "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/launch/l3ssup3rh3r0s/fr",
        "name": "Cours intensif sur l'apprentissage automatique",
        "subjects": [
          "Apprentissage automatique",
          "TI"
        ]
      }
    }
  ]
}

Main output differences (Step 1)

After calling Retrieve an external course, you must extract the courseId from the response body. This ID is the unique 360Learning identifier required to call Retrieve a course.

Change type	API v1	API v2
Removed Output property	`archived`: `true` if the external course has been deleted, otherwise `false`.	Found in Step 2.
Removed Output property	`skills`: Array of IDs of skills the external course refers to.	Use List all tags in a course to get the list of tags (previously known as skills) associated with the course.
Removed Output property	`externalPlatform`: Name of the external platform to which the external content is attached.	Found in Step 2.
Removed Output property	`groupId`: ID of the group where external contents are imported.	Found in Step 2.
Removed Output property	`authors`: Array with the authors of the external course	Replaced by users' internal IDs in v2. Use Retrieve a user to get full users' information.
Removed Output property	`numberOfVideos`: The number of videos / activities in the external course.
Modified Output property	`id`: The unique ID of the course created from this external course.	`courseId`: Renamed.
Modified Output property	`thumbnailUrl`: URL of the image of the external course	`imageUrl`: Renamed.
Modified Output property	`title`: Title of the external course	`name`: Renamed.
Modified Output property	`language`: Main default language of the external course	`defaultLang`: Renamed.
Modified Output property	`courseDuration`: Duration of the external course (in minutes)	`duration`: Renamed.
Modified Output property	`alternativeLanguages`	`translations`: Array of objects with the different translations available for the external course.
Modified Output property	`sources.logo`: URL of the source's logo	`sources.logoUrl`: Renamed.

Step 2: Retrieve a course metadata

Once you have the courseId from the Step 1 response, call the Courses endpoint to retrieve platform-specific attributes

Endpoint mapping (Step 2)

API v1: /api/v1/externalContents/groups/:groupId/externalPlatforms/:externalPlatform/courses/:externalId
API v2: /api/v2/courses/{courseId}

Input changes (Step 2)

API v1 input example

curl --location -g 'https://app.360learning.com/api/v1/externalContents/groups/62be0535045424d93edaad7b/externalPlatforms/myPlatform/courses/l3ssup3rh3r0s'

API v2 input example (Step 2)

curl --request GET \
     --url https://app.360learning.com/api/v2/courses/6463973f9b19ff7b9ca674e9 \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token'

Main input differences (Step 2)

Change type	API v1	API v2
Removed Path parameter	`groupId`: ID of the group where external contents were imported.
Removed Path parameter	`externalPlatform`: Name of the external platform to which the external content is attached.
Added Path parameter		`courseId` (Required): The unique ID of the course.
Added Header parameter		`360-api-version` (Required): API version identifier. Example: `v2.0`.

Output changes (Step 2)

API v1 output example

{
  "id": "6463973f9b19ff7b9ca674e9",
  "authorId": "62bdbc00293a604543f44386",
  "archived": false,
  "title": "Machine Learning Crash Course",
  "description": "Learn the basics of machine learning.",
  "language": "en",
  "courseDuration": 10,
  "skills": [
    "63970d8ec2675a57f2b3f509"
  ],
  "externalId": "l3ssup3rh3r0s",
  "externalPlatform": "myPlatform",
  "groupId": "62be0535045424d93edaad7b",
  "authors": [
    "John Doe"
  ],
  "alternativeLanguages": [
    "fr"
  ],
  "launchUrl": "https://player.mylearningplatform.com/ql/fg-q6dfax2e_6ys",
  "mobileLaunchUrl": "https://player.mylearningplatform.com/mobile/fg-q6dfax2e_6ys",
  "thumbnailUrl": "https://upload.wikimedia.org/wikipedia/commons/0/07/Wikipedia_logo_%28svg%29.svg",
  "difficultyLevel": "beginner",
  "contentType": "course",
  "numberOfVideos": 1,
  "sources": [
    {
      "name": "Wikipedia",
      "logo": "https://en.wikipedia.org/static/images/icons/wikipedia.png"
    }
  ],
  "subjects": [
    "Machine learning"
  ]
}

API v2 output example (Step 2)

{
  "name": "Machine Learning Crash Course",
  "sourceLang": "en",
  "authorId": "62bdbc00293a604543f44386",
  "groupId": "62be0535045424d93edaad7b",
  "coAuthorIds": [
    "507f1f77bcf86cd799439011"
  ],
  "description": "Learn the basics of machine learning.",
  "duration": 10,
  "_id": "6463973f9b19ff7b9ca674e9",
  "createdAt": "2026-04-22T15:04:00.725Z",
  "defaultLang": "en",
  "modifiedAt": "2026-04-22T15:04:00.725Z",
  "status": "published",
  "translations": [
    {
      "lang": "fr",
      "published": true,
      "translatorIds": [
        "507f1f77bcf86cd799439011"
      ],
      "translatedFields": {
        "name": "Machine Learning",
        "description": "Ce module vous apprend les bases de Machine Learning !"
      }
    }
  ],
  "type": "external",
  "externalPlatform": "myPlatform",
  "currentVersionNumber": 0,
  "collaborativeLearning": true
}

Main output differences (Step 2)

Change type	API v1	API v2
Removed Output property	`authors`: Author names.	Replaced by `coAuthorIds` (IDs instead of names).
Removed Output property	`launchUrl` and `mobileLaunchUrl`	Found in Step 1.
Removed Output property	`externalId`	Found in Step 1.
Removed Output property	`sources`	Found in Step 1.
Removed Output property	`thumbnailUrl`	Found in Step 1 as `imageUrl`.
Removed Output property	`difficultyLevel`	Found in Step 1.
Removed Output property	`contentType`	Found in Step 1.
Removed Output property	`skills`: Array of IDs of skills the external course refers to.
Removed Output property	`numberOfVideos`: The number of videos / activities in the external course.
Modified Output property	`archived`: Boolean. `true` if the external course has been deleted, otherwise `false`.	`status`: The status of the course. Possible values: `archived`, `deleted`, `published`.
Modified Output property	`id`: The unique ID of the course created from this external course.	`_id`: Renamed. (Also found in the output of Step 1)
Modified Output property	`title`: Title of the external course	`name`: Renamed. (Also found in the output of Step 1)
Modified Output property	`courseDuration`: Duration of the external course (in minutes)	`duration`: Renamed. (Also found in the output of Step 1)
Modified Output property	`language`: Defines the original language in which the course was created.	`sourceLang`: Renamed.
Modified Output property	`alternativeLanguages`	`translations`
Added Output property		`coAuthorIds`: Array of IDs instead of authors names.
Added Output property		`type`: Identifies if the course is external, native, or elearning standard.
Added Output property		`createdAt`: Timestamp.
Added Output property		`modifiedAt`: Timestamp.
Added Output property		`collaborativeLearning`: A boolean indicating if social features (reactions/comments) are enabled.
Added Output property		`currentVersionNumber`: Tracks the iteration of the content.

Updated 4 months ago

Did this page help you?