Udemy Business API Best Practices

This guide was created by Udemy as a best practice reference on supporting integration builds using Udemy Business’ APIs. We recommend following the tips in this guide to ensure the best experience for your end users. 

Udemy’s Sales & Solutions Engineering team is available to answer any questions that arise during the build process.  Please feel free to reach out to your business contact at Udemy Business to arrange a meeting if you have any questions. 

Access Udemy’s full API documentation.

This document was last updated January 25, 2023.

 

Screen_Shot_2023-01-27_at_7.57.39_AM.png

 

Table of Contents:

Udemy Business API Best Practices

1. General API information

2. Course List API

3. Learning Path APIs

4. Reporting APIs

5. What’s coming soon

6. Feedback?

 

1. General API information

Authentication & SSO

Note that authentication and user management within Udemy Business is handled independently from your  learning management systems (LMS) and learning experience platforms (LXP) system.  When learners access a Udemy Business course through a LMS/LXP system, those users must also have a license for Udemy Business to complete the course within Udemy Business.  Udemy business supports user management via several mechanisms - standard username/password, email domain access, and Single Sign On.

Error handling + rate limits

429 Errors

  • All Udemy APIs have rate limits; when the rate limit is exceeded, a 429 error response will be returned with a Retry-After header. You should implement retry logic to wait the number of seconds in the Retry-After header before making additional requests. 
  • Note: Udemy rate limits are subject to change. Retry logic should be implemented based on the value in the 429 response, rather than on any hard-coded rate limits.

50X Errors

  • Retry logic should also be implemented for any 502/503 errors. If you receive any 50X errors when accessing the Course List endpoint, try decreasing the page_size parameter value to prevent further errors.
  • We also recommend implementing customer facing mechanisms to re-sync the course catalog and refresh reporting data.

2. Course List API 

How it works

The Udemy Business Course List API enables you to get all of the courses and course metadata associated with Udemy courses into your system.  From there you can search for, discover, and access your Udemy Business Courses from within 3rd party platforms such as your LMS, LXP, or other systems.  Along with key course information such as title, description, thumbnail, etc…, the course integration includes a deep link URL that will automatically redirect a learner from the  LMS/LXP back to your Udemy Business instance and learners will complete the course within Udemy Business.  

The integration does not support the ability to embed or complete the Udemy Business course within the 3rd party system.  This avoids the need to re-host your content in other systems and also ensures the best-possible learner experience as the courses are designed to be consumed within Udemy and also include access to learner tools, instructor Q&A and more.

Udemy Business supports course auto-enrollment as an optional setting for the API configuration.  This is recommended for integrations, and when auto-enrollment is active, learners will automatically be enrolled when they click on the course link from the LMS/LXP system. 

Access to courses in Udemy vs. 3rd party systems

Some LMS/LXP systems support the ability to restrict which courses are accessible by which users within the LMS/LXP.  Except for non-public custom courses and learning paths, all users within Udemy Business will be able to access and enroll in the entire public course catalog from within Udemy Business. While this is not an issue for our customers, it’s important to note this functionality may be slightly different between your LMS/LXP system and Udemy Business.

Course refresh frequency

Since the course catalog is subject to change we recommend performing a catalog refresh daily.  This should occur automatically, with no manual steps required from the end user.  We recommend doing the refresh during off-peak hours (3am UTC is the ideal time).

Recommended course data

While we offer a large amount of course metadata returned through the API, we advise using the below data points at a minimum for the best user experience: 

 

API Field

Recommendation

title

description

primary_category

primary_subcategory

Use these fields to match a user’s search term

images[]

An image URL that provides the user with a image of the course

url

mobile_native_deeplink

Deeplinks to the course in the customer’s environment on the Udemy Business web app and mobile app, respectively

locale

The Udemy Business catalog has courses in several different languages, the ability for your system to identify & filter on this is critical

estimated_content_length

Provided in minutes and is great to display for users and can be used to inform reporting/user gamification

level

Course level (beginner, intermediate, expert) 

 

Efficient API calls

Our Udemy Business Collection can have between 6,000 to 18,000 courses depending on a customers’ language collection.  With a maximum page size of 100, it will take 60 to 180 API returns to get all of those courses.  Setting up your system to manage that process successfully will have major benefits in the long term.  If you would like personalized consulting on this process, please reach out to your Udemy Solutions Engineer contact.

Page Size

  • page_size limit is 100 records.
  • If you notice any delays or 502 errors with these requests, decrease this page_size value by half and retrying
  • Total course count is provided in the response (count) 
  • Calculate the page count by using count / page_size. i.e If count = 1000 and page size = 100, you will need to make 10 requests.
  • Alternatively, you can retrieve the next page of results by using the next value that is returned in the response.

Synchronous API calls

  • We recommend leveraging synchronous requests to efficiently retrieve the course catalog.
  • As your software is progressing through the pages of courses, one page in the sequence can fail for a variety of reasons.  It is important to know which pages have failed and include a retry mechanism in this process.  
  • Synchronous API calls and queue data structures are great for this kind of process, as it can order the next pages and retry missed calls. Asynchronous API calls may overload the API with too many calls at one moment and make it harder to track which pages in sequence may have failed.  We suggest successfully completing each course page before moving on to the next.

Course taxonomy

Review a list of the current course taxonomy. This includes a list of the categories and subcategories which can be mapped into your system via the API. Note that this taxonomy is not standardized for all languages and this taxonomy may change over time.

Language codes

The list of languages in Udemy Business and the associated codes are below.  When you download the course list from Udemy you'll see a locale field where the first two lower case letters correspond to the language of the course overall and the second two letters correspond to additional regions that may be used for captioning, subtitles, etc... For instance there is en_GB which is English Great Britain and then there is en_US which is English United States.

Arabic - ar

Bahasa Indonesian - id

English - en

French - fr

German - de

Hindi - hi

Italian - it

Japanese* - ja

Korean* - ko

Mandarin - zh

Polish - pl

Portuguese - pt

Russian - ru

Spanish - es

Turkish - tr

Unique course catalogs 

The Udemy Business course catalog is unique and private to each Udemy Business customer.  Different language packages, custom courses, and courses imported from udemy.com will be included in each customer’s collection and are included in the Course API response. Therefore you will need to maintain a unique course catalog for each Udemy Business customer organization.

New and retired courses

  • The course catalog is subject to change at any time - new courses may be added, and courses may be retired. 
  • If you are using the course catalog to GET all courses and load them into your own internal database, it is important that you remove or flag retired courses when they no longer appear in the courses list output.
  • Once a course is retired, it will no longer be returned from the Course List API and users will no longer have access to enroll in the course in Udemy.  When a course is retired from the Udemy Business collection, any learner that is already enrolled in that course at the time of retirement will continue to have access. If a learner unenrolls from a course that has been retired, they will no longer be able to access the course. Additionally it will not be possible for any new learner to access or enroll in the course.  

What’s not included in the course list API

Please note the Udemy Business Courses Catalog API does not include access to all information about courses.  Some notable things to consider that are not available today include:

  • Course Embedding or Hosting
    • You cannot embed or host the Udemy Business content outside of Udemy Business directly.  You must redirect users from LMS/LXP back to Udemy Business to consume the content.
  • Course Ratings
    • These are not included in the Course API endpoint.  Note that many LMS/LXP systems include their own system of rating courses and your learners can still utilize that independently.
  • Course Reviews
  • Enrollment Information
  • Search & Discover Functionality
    • Udemy Business has its own way it surfaces search results and recommends courses which takes into account top courses, highest rated courses, etc…  This functionality does not get “sent over” to 3rd party tools.  Udemy Business cannot control how 3rd party tools will surface results or suggest courses.
  • Learning Paths and Udemy Pro Paths
    • These are a separate object from Courses and are not included in the Course Catalog Sync.  We have a separate Learning Path API endpoint that you must leverage to import Udemy Business Learning Paths and Udemy Pro Paths.
  • Lecture-level data
    • Udemy Business’ APIs can send complete courses and complete Learning Paths through our APIs.  We cannot send partial courses such as individual course sections, lectures, or quizzes.
    • If you are looking for the ability to use partial courses to create custom Learning Paths or Learning Programs, we recommend building Learning Paths within Udemy Business and then using our Learning Path API endpoint to import Learning Paths into your LMS/LXP.  
  • UB Pro Labs, Assessments, Workspaces
    • Labs, Assessments, and Workspaces cannot be integrated into 3rd party systems and must be launched from Udemy Business Directly.  
  • You cannot bulk upload courses into Udemy via API.  Our API is for the purposes of pulling course information out of Udemy.

3. Learning Path APIs

Overview

Similar to Udemy’s Course List API endpoint, Udemy Business also provides a Learning Path API endpoint so you can search for, discover, and access your Udemy Business Learning Paths from within 3rd party platforms such as your LMS, LXP, or other systems.  

Learning Paths are a collection of courses, individual lectures, custom content, and links grouped together, and to show the learner a route to learn a certain theme of knowledge of their design.

The information returned from Learning Paths in many ways is similar to what is returned through the Course List API endpoint but it is important to remember that Learning Paths are considered a distinct object from Courses and must be handled as such.

While developing a connector using the Learning Path API is not strictly necessary for the core use-cases of integrating with Udemy Business, it is a great additional feature to consider developing for maximizing long-term benefit of integration.

4. Reporting APIs

Overview

The Udemy Business Reporting API enables you to track how your learners engage with the content.  For instance, you can see, track, and understand who is completing which courses, how frequently, track top learners, engage learners who are struggling, and more.  These insights are immensely helpful in the context of achieving your broader learning and development goals.  Reporting insights that you export out of Udemy Business can be helpful to see in your LMS/LXP and combined or augmented with data and reporting capabilities that exist in your other external systems.

There are two mechanisms by which to obtain reporting data from Udemy: xAPI, and the REST Reporting API. For more information on the difference, visit benefits of xAPI. 

Reporting xAPI

  • Udemy will POST progress + completion events to your specified endpoint in near-real time. This eliminates the need for repeatedly polling Udemy’s API.
  • xAPI is the recommended approach if your platform has xAPI capabilities, as more and more learning systems continue to adopt this standard.
  • Note that Reporting xAPI does not currently include as many data elements as the RESTful API.

Reporting RESTful API

This API must be called periodically and data will be pulled from the Reporting REST API endpoint into your LMS/LXP.  It is not real-time and requires periodic pulls to get new records.

Recommended endpoint

user-course-activity for completion & progress data. Usingfrom_date and to_date to restrict results to a given date period.

Reporting API refresh frequency

  • Every 4 hours
    • Note: Our REST API data is updated 3x per day. 
    • Every 4 hours allows for Udemy to perform more frequent updates in the future, without requiring an integration change.

Reporting data

Data element

Details

course_id

The Unique identifier to the course 

user_email

The Unique identifier to the user 

completion_ratio

The percent of a course that a user has completed.

Note this % can change as the course changes.
E.g 100% completion + 1 new lecture can change to 80%

num_video_consumed_minutes

Great for internal LMS metrics to track user engagement total learning minutes/ credits

course_first_completion_date

Used to track if the user has completed the course at any point.

course_completion_date

Used to track the latest completion.
This can be null if the user has unenrolled from the course

user_external_id

Used as an external id unique to the user. (Only if email is not a valid unique ID)

lms_user_id

Used as an external id unique to the LMS (Only if email is not a valid unique ID)

 

Progress & completion

  • Your integration should ingest both progress and completion events.
    • This should occur for all Udemy Business courses that have been consumed, including retired courses and those which were not launched from your platform.

What’s not included in the reporting API and xAPI

  • Learning Path Reporting
    • This is not available through API and only available directly through direct download via Udemy web app at this time.

 6. What’s coming soon

Udemy is striving to continuously improve our APIs and technology stack.  

  • GraphQL - Udemy Engineering plans to update our Course Catalog APIs to utilize GraphQL architecture. Read more about the general GraphQL concept. This will allow queries to our course catalog APIs that return only the data you need for that specific call, among other benefits.  Public release of Udemy’s GraphQL APIs is scheduled for Q2 2023.  If you think you can benefit from these newer APIs today, feel free to email partnerships@udemy.com to request.

  • Search API - Udemy has a wealth of knowledge from users searching our +200k course catalog and recommending which courses can be appropriate for them.  Our search functionality can assist your search and recommendation needs.  Search is slated for release Q1 2023.  If this feature can be of use to you today, please email partnerships@udemy.com to request.

6. Feedback?

Any feedback on this document or would like to see other information?  Please submit your feedback to partnerships@udemy.com, and we look forward to hearing from you.

Related articles

Contact Us