Introduction
At Docebo, we believe integrating your learning platform with other third party systems is key to the success of your learning programs for increased business performance. The documents that you find in the API & developer info section of Docebo's knowledge base are intended to provide you with all of the information you may need to get started with Docebo APIs. As processes around APIs are added or modified, Docebo will update this documentation to reflect the most current information.
Current version
The default version of the currently exposed API is version 1 (v1). However, in the future, there may be specific microservices that already expose later versions (v2, v3,..). The version of the API you intend to use must be specified within the endpoint URL. For example:
GET /learn/v1/location
Docebo API browser
Reference documentation of all of Docebo’s publicly available APIs is available within your Docebo platform. The documentation is constantly updated with the most up-to-date API version.
Access the API browser
The access link to the API reference documentation is obtained by appending /api-browser
to your platform URL. For example:
https://<yourcompany>.docebosaas.com/api-browser/
or
https://<your custom domain>/api-browser/
The available microservices are listed in the SERVICES combobox. When you select a new microservice, the documentation for that specific service is automatically loaded.
View the reference documentation for an endpoint
In the navigation pane on the left:
- Select the desired microservice from the SERVICES list (for example, Course) to load its documentation.
- Then under API REFERENCE click on one of the groupings of that service (for example, Categories) to expand the list of its endpoints.
- Finally, click on a specific endpoint to jump to its documentation.
For the selected endpoint, in the right-hand pane you will see a Response sample and also a Body sample if applicable. You can click the Body schema or Response schema headings to expand the detailed documentation of all the parameters.
In the center pane there is an area where you can interactively test the endpoint by trying out a call on your platform’s data. However, to do this you must first obtain a token as described in the following paragraph.
Obtain an API access token
To make calls from the API browser, you will need an OAuth2 access token that is linked to your platform credentials, as a Superadmin, Power User, or normal user.
Please note: Docebo leverages OAuth scopes and grants to allow access to the API, so the endpoints are following a role-based access model by default. The permissions you have on the platform will determine the resources and actions you can access via API calls using this access token.
To get started, log in to the platform. You can also not log in at this stage, in which case you’ll have to enter your platform credentials later.
- Now access the API browser page and, for any endpoint, in the center pane click the Oauth button.
- In the dialog box that opens click on the api scope so that a check mark appears on it, then click Authorize.
- Now in the Authorization required dialog you will be welcomed as whatever user you previously logged in as: here click Authorize again.
Note: If you did not previously log in to the platform, you will be prompted to enter your credentials before you can click Authorize.
- Now you are redirected back to the api browser page where you can see that you are signed in (the Oauth button now says Signout):
Also the Token field is now populated:
Now you can begin making API calls on your platform’s data.
Note: In the Token field you can also directly paste a previously generated OAuth2 access token
Test an endpoint in the API browser
Once you have provided an access token in the API browser, you can try out calls to the endpoints. To do this, in the API browser navigation pane select the endpoint as before, then in the middle pane click the Try button.
A window will open where you can examine the real response of your platform to this API call:
Caution: The API calls you make here will operate on the real data of your platform, so be cautious making calls (DELETE, POST, etc) that can change or delete data.
Note that, in some rare cases, dynamically generated attributes in JSON data cannot be properly rendered in the user interface of the reference documentation. This could prevent you from testing the API directly from the documentation itself. In this case, we suggest you use a dedicated tool (for example, Postman).
API client libraries
At this time, Docebo does not provide any client library for Docebo APIs. You need to set up your own package to start coding against Docebo APIs.
API call limitations
To maintain optimum performance and to ensure APIs are available to all customers, Docebo’s APIs are limited to 1,000 API calls per hour from each IP address.
Warning: Branch API calls should never be run concurrently as unpredictable results may occur and the structure of the branches may risk being corrupted. The affected API calls are:
-
POST /manage/v1/user/batch
(only if the call also creates the branches while importing the users) POST /manage/v1/orgchart
DELETE /manage/v1/orgchart/{id}
PUT /manage/v1/orgchart/{branch_id}
POST /manage/v1/orgchart/{id}/move
DELETE /manage/v1/orgchart/batch
POST /manage/v1/orgchart/batch
Please make sure these branch API calls are run sequentially.
Backward-compatible changes
Consider the changes listed below as backward-compatible. We invite you to structure your code to be able to support any such changes to the APIs. This type of change normally happens without any notification to customers. They may include:
- Adding new endpoints
- Adding new optional parameters to existing API endpoints
- Adding new properties to API responses
- Changing the order of properties in API responses
- Any update in API documentation
Non-backward-compatible changes policy
Docebo makes every effort to keep API changes backward-compatible, but it’s not always possible. In these cases, we inform consumers of the update through our Product updates page. The effective updates occur after a reasonable timeframe, and the deprecation period duration can vary due to technical and usage considerations. In any case, the time interval is a minimum of one month from the original communication on the Product updates page to the effective update. The deprecation period rule does not apply in case there are critical security vulnerabilities. In these cases, we apply a fix immediately and communication may appear on the Product Updates page during or shortly after the fix.
API changelog
Docebo informs customers of new additions or changes to Docebo APIs through our general Product updates page. Once you see communication related to APIs on this page, it’s always best to then refer to the official API documentation (https://<yoursubdomain.docebosaas.com>/api-browser/
) for a complete understanding of the changes that occurred.
API browser and additional fields
The additional fields used in the platform for the management of users, courses, and enrollment are managed by Superadmins as dynamic values, and cannot be documented in the API browser documentation, as they change from platform to platform. For the same reason, it is not possible to test additional fields from the API browser. As an example, if you want to filter courses according to a course additional field value where xx is the additional field ID (such as field_1
, field_2
, etc), the string to use would be something like:
https://yourdomain.docebosaas.com/learn/v1/enrollments?field_6=3
The ID to use in your query instead of xx will either be an integer (for example, for dropdown additional fields), a string (for a text additional field), an array, or a date (for date additional field). Here are some examples:
- date:
-
'field_12': {'from': '2018-06-26','to': '2018-06-30'},
- textfield:
-
'field_6': 'abc'
OR
'field_6': ['abc', 'def'], dropdown: 'field_8': 3
- iframe additional fields:
- Extend
field_xx
andfield_xx_yy
whereyy
is the field from the JSON configuration and use a this syntax:'$^speakers^speaker'
. The value will either be a string (for text additional field) or an array or a date (for date additional field). Examples:- date:
-
'field_12$^datefield': {'from': '2018-06-26','to': '2018-06-30'},
- textfield:
-
'field6$^textfield': 'abc'
OR
'field6$^textfield': ['abc', 'def']
Dealing with array fields for GET requests
The query string parameters described as arrays, should be specified differently depending on the tool you’re using to consume the API:
-
Docebo API browser: due to internal conversions applied by this tool, the parameters should be separated by a comma. In addition to that, if the parameters are strings, they must be wrapped with double quotes. Example:
"enrollment_status", "enrollment_completion_percentage”
-
Postman (or similar clients): the parameter must be followed by double square brackets and specified as many times as the values you need to pass. Example:
<ENDPOINT>?learning_plan_id[]=25&learning_plan_id[]=1&extra_fields[]=enrollment_time_spent&extra_fields[]=enrollment_status