This guide serves as a best practice reference for supporting integration builds using Udemy Business’ APIs. We recommend following the tips in this guide to ensure the best experience for your end learners.
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 May 31, 2023.
Table of contents
Udemy Business API Best Practices
- How it works
- Access to courses in Udemy vs. 3rd party systems
- Course refresh frequency
- Recommended course data
- Efficient API calls
- Page size
- Synchronous API calls
- Course taxonomy
- Language codes
- Unique course catalogs
- New and retired courses
- What’s not included in the course list API
- Overview
- Reporting xAPI
- Reporting RESTful API
- Recommended endpoint
- Reporting API refresh frequency
- Reporting data
- Progress & completion
- What’s not included in the reporting API and xAPI
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). 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 23,000 courses depending on a customers’ language collection. With a maximum page size of 100, it will take 60 to 230 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.
- Change the page param for each request
- https://{{ACCOUNT_NAME}}.udemy.com/api-2.0/organizations/{{ACCOUNT_ID}}/courses/list/?fields[course]=@all&page=1
- 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.
- For instance, the time a learner spends in the course is not sent as part of the xAPI statement.
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.
- https://{{ACCOUNT_NAME}}.udemy.com/api-2.0/organizations/{{ACCOUNT_ID}}/analytics/user-course-activity/?page=1&from_date=2022-05-21&to_date=2022-05-22&page_size=100
-
- We advise of a 2 day date range consisting of the current day and previous day to ensure the most recent data is captured while also capturing sunset data (Data that may be generated at the fringes of each day/refresh)
-
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. |
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. |
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
- Udemy Business Pro Reporting
- User lab activity report and User assessment activity report are only available through direct download via Udemy admin settings at this time.
- Learning Path Reporting
- This is not available through API and is only available directly through direct download via Udemy admin settings at this time.
5. 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 Q3 2023.
- 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 Q3 2023.
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.