About the OPEN ELMS API
About the OPEN ELMS API
The Open Elms API is a RESTful web service and uses token authenticate 3rd party applications. Before starting to use the Open ELMS API you will need to contact support@openelms.com to obtain a key in order to access this service.
The API enables third party applications to control Open Elms features by communicating between the systems.
The API can be used for a variety of purposes such as:
- The management of users (add/remove/delete) from HR systems
- Assigning user to learning resources within Training Management Systems
- Listing learning resources in the system
- Editing learning from within a third party Learning Management System
- Running and recording elearning from a third party Learning Management System
Use the menu on the right hand side to access the instructions for authenticating and then using the API. Open eLMS staff are on stand-by to help with any queries you may have, contact support for further details.
A summary of HTTP Response Codes returned is shown below:
HTTP Code | Summary | Description |
200 | OK | Successful API call. |
400 | Bad Request | A validation exception has occurred. |
401 | Unauthorized | Invalid authorization credentials. |
404 | Not Found | The resource you have specified cannot be found |
412 | Precondition Failed | One or more conditions given in the request header fields were invalid. |
500 | Internal Error | An unhandled error. Contact the Open Elms team if problems persist |
501 | Not Implemented | The method you have called has not been implemented (e.g. POST Organisation) |
503 | Rate Limit Exceeded | The API rate limit for your organisation/application pairing has been exceeded. |
503 | Not Available | API is currently unavailable – typically due to a scheduled outage – try again soon. |
Getting the authentication token
Access is controlled is token based. The value of the token is configured in Open LMS at System Setup/Defaults/Configuration/APITokenAccess.
When calling the API, you need to pass the token value in an HTTP “Authorization” header – the value of the header should be “Basic ####”, where #### is the value of the APITokenAccess configuration option (see screenshot below). A 403 (Forbidden) error will be thrown if authentication fails. Below is a screenshot of a REST API which is used to invoke the API
An example of calling the API with a REST client. The value of the token (‘12345’) is given in the HTTP Authorization header.
User Commands
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/
Method
POST
Description
Creates a new user account.
Note: groups_id can be a comma separated string of group ids to assign multiple groups, if groups_id is set to an empty string then it will remove that user from all groups. If the user is assigned to a group which has learning assigned to it, then the new user will automatically have that learning assigned to their account.
Form Data
We have separated the form data into different categories for ease of use:
Required fields
- fname – User’s first name
- lname – User’s last name
- username – User’s username
- email – User’s email
- password – User’s password
Optional fields
- department – User’s department (created if not found in the database)
- department_address – Department address
- department_postcode – Department post code
- city – User’s city (created if not found in the database)
- company – User’s company (created if not found in the database)
- country – User’s country (created if not found in the database)
- job – Job title (created if not found in the database)
- groups – groups can be a comma separated string of group ids to assign multiple groups.
- phone – User’s phone
- week_hours – Working Week hours
- manager_name – Manager’s name
- manager_job_title – Manager’s job title
- manager_email – Manager’s email
ILR main fields
- AddLine1
- AddLine2
- AddLine3
- AddLine4
- Postcode
- Sex (M or F)
- Ethnicity – ethnicity (a numeric id, * check to see how to retrieve the id value)
- LLDDHealthProb – disability status (a numeric id, * check to see how to retrieve the id value)
- DateOfBirth
- NINumber – National Insurance number
ILR Employment Status fields
- EmployerX_EmpStat – Employment status
- EmployerX_DateEmpStatApp – Date employment status applies (date, will try to parse any format)
- EmployerX_EmpId – Employer identifier
- EmployerX_AgreeId – Agreement identifier
ILR Employment Status Monitoring fields
- EmployerX_SEI – Is the learner self employed? (set to 1 if yes)
- EmployerX_PEI – Was the learner in full time education or training prior to enrolment? (set to 1 if yes)
- EmployerX_SEM – Small Employer (set to 1 if yes)
- EmployerX_LOU – Length of unemployment (a numeric id, * check to see how to retrieve the id value)
- EmployerX_BSI – Benefit status indicator (a numeric id, * check to see how to retrieve the id value)
- EmployerX_EII – Employment intensity indicator (a numeric id, * check to see how to retrieve the id value)
- EmployerX_LOE – Length of employment (a numeric id, * check to see how to retrieve the id value)
Note: X can be any number between 1 and 5. In other words you can up to five employment status records by using Employer1_{field_name}, Employer2_{field_name}, etc.
* Retrieving valid values for numeric ids
Possible values of numeric ids can be retrieved through the following service:
GET backend/user/fields
It results in a JSON which contains all the possible values for each user field, as well as their labels
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/{USER_ID}
Method
PUT
Description
Updates new user account
Note: groups_id can be a comma separated string of group ids to assign multiple groups, if groups_id is set to an empty string then it will remove that user from all groups. If the user is assigned to a group which has learning assigned to it, then the new user will automatically have that learning assigned to their account.
Form Data
We have separated the form data into different categories for ease of use:
Required fields
- fname – User’s first name
- lname – User’s last name
- username – User’s username
- email – User’s email
- password – User’s password
Optional fields
- department – User’s department (created if not found in the database)
- department_address – Department address
- department_postcode – Department post code
- city – User’s city (created if not found in the database)
- company – User’s company (created if not found in the database)
- country – User’s country (created if not found in the database)
- job – Job title (created if not found in the database)
- groups – groups can be a comma separated string of groups to assign multiple groups.
- phone – User’s phone
- week_hours – Working Week hours
- manager_name – Manager’s name
- manager_job_title – Manager’s job title
- manager_email – Manager’s email
ILR main fields
- AddLine1
- AddLine2
- AddLine3
- AddLine4
- Postcode
- Sex (M or F)
- Ethnicity – ethnicity (a numeric id, * check to see how to retrieve the id value)
- LLDDHealthProb – disability status (a numeric id, * check to see how to retrieve the id value)
- DateOfBirth
- NINumber – National Insurance number
ILR Employment Status fields
- EmployerX_EmpStat – Employment status
- EmployerX_DateEmpStatApp – Date employment status applies (date, will try to parse any format)
- EmployerX_EmpId – Employer identifier
- EmployerX_AgreeId – Agreement identifier
ILR Employment Status Monitoring fields
- EmployerX_SEI – Is the learner self employed? (set to 1 if yes)
- EmployerX_PEI – Was the learner in full time education or training prior to enrolment? (set to 1 if yes)
- EmployerX_SEM – Small Employer (set to 1 if yes)
- EmployerX_LOU – Length of unemployment (a numeric id, * check to see how to retrieve the id value)
- EmployerX_BSI – Benefit status indicator (a numeric id, * check to see how to retrieve the id value)
- EmployerX_EII – Employment intensity indicator (a numeric id, * check to see how to retrieve the id value)
- EmployerX_LOE – Length of employment (a numeric id, * check to see how to retrieve the id value)
Note: X can be any number between 1 and 5. In other words you can up to five employment status records by using Employer1_{field_name}, Employer2_{field_name}, etc.
* Retrieving valid values for numeric ids
Possible values of numeric ids can be retrieved through the following service:
GET backend/user/fields
It results in a JSON which contains all the possible values for each user field, as well as their labels
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/{USER_ID}
Method
GET
Description
Retrieves a list of user accounts. {USER_ID} is optional – if given, then only the details of the specified account are returned.
Return value
A list of user accounts, including the following fields:
Fields | |
---|---|
username | Username |
employee_id | Employee ID |
Email address | |
fname | First name |
lname | Last name |
country | Country record |
city | City record |
company | Company record |
department | Department record |
location | Location record |
job | Job record |
groups | A collection of group records |
learning | A collection of learning resource records |
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/users/?{FIELD_NAME1}={FIELD_VALUE1}&{FIELD_NAME2}={FIELD_VALUE2}..,
Method
GET
Description
Retrieves a list of user accounts which match the given criteria. Currently, the following search fields are supported: fname, lname, username, usercode, email, company_id, department_id, country_id, city_id, location_id, group_id
Return value
A list of user accounts, including the following fields:
Fields | |
---|---|
username | Username |
employee_id | Employee ID |
Email address | |
fname | First name |
lname | Last name |
country | Country record |
city | City record |
company | Company record |
department | Department record |
location | Location record |
job | Job record |
groups | A collection of group records |
learning | A collection of learning resource records |
Learning Commands
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/assign/{USER_ID}/{L_ID1, L_ID2, L_ID3 etc}
Method
PUT
Description
This adds to the learner the learning resource specified by the learning ID. Multiple learning IDs (L_ID1, L_ID2, L_ID3 etc.) can be added by using a CSV list as is shown above.
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/unassign/{USER_ID}/{L_ID1, L_ID2, L_ID3 etc}
Method
DELETE
Description
This removes from the learner the learning resource specified by the learning ID. Multiple learning IDs (L_ID1, L_ID2, L_ID3 etc.) can be added by using a CSV list as is shown above.
Return value
User id
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}
Method
GET
Description
List available learning resources. {LEARNING_ID} is optional – if given, then only the details of the specified learning resource are returned. If the learning resource is a SCORM one, then its download link is also returned.
Return value
A list of learning resources, including learning id, name, learning type and an optional download link.
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/download/{LEARNING_ID}
Method
GET
Description
Downloads a SCORM learning resource. Note that this service only works for e-learning (i.e. SCORM) learning resources.
Return value
The SCORM files compressed in a single ZIP file.
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/download-container/{LEARNING_ID}
Method
GET
Description
Downloads a SCORM learning resource container. Note that this service only works for e-learning (i.e. SCORM) learning resources. Container serves files directly from e-learningWMB servers. Container does not hold SCORM files. Configuration option “allowSCORMContainerPlayer” must be set to true to allow playing of containers
Return value
The SCORM container files compressed in a single ZIP file.
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/new-resource
Method
POST
Description
Create new e-learning resource, type is optional.
Form data
name*, type(audit, elearning, elearning_quiz, induction, mp4_quiz, quiz, skillscan, vimeo_quiz, youtube_quiz)
Return value
Learning resource ID(string)
Open eLMS Creator Command
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/creator-url/{LEARNING_ID}
Method
GET
Description
Returns a one time URL that can be opened in the browser and will load the jackdaw editor for a given resource. New requests will make earlier URL non functional.
Return value
Open eLMS Creator URL (string)
Learning progress
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}/trainees/{USER_ID}
Method
GET
Description
Returns the learning status of the trainees assigned to a given learning resource. If {USER_ID} is specified, then the learning status of just the trainee with the given user_id is returned.
Return value
JSON array containing the completion status (‘not attempted’, ‘in progress’, ‘completed’ or ‘failed), numeric score (null if not completed) and the date of completion (null if not completed) of the corresponding learning result
URL
https://openelms.e-learningwmb.co.uk/{SITE_ID}/backend/learning/{LEARNING_ID}/{USER_ID}/{ACTION}/{SCORE}
Method
PUT
Description
Updates the learning status of the given user for the given course. There are two possible updates which are determined by the type of action. If action is ‘start’, then the learning resource is marked as ‘in progress’. If the action is ‘complete’, then the resource is marked as ‘complete’. If the action is ‘fail’, then the course is marked as failed. The score is an option numeric parameter, which is only used for ‘complete’ and ‘fail’.
Return value
JSON array containing the completion status (‘not attempted’, ‘in progress’, ‘completed’ or ‘failed), numeric score (null if not completed) and the date of completion (null if not completed) of the corresponding learning result
AI SCORM Generator
URL
https://library.openelms.com/api/ai-scorm/create
Method
POST
Description
Creates a single AI SCORM package with an optional PDF file upload. The endpoint expects multipart/form-data
with courseTitle
and learningObjectives
as required fields; all other parameters have default values.
Return value
Returns a JSON object indicating that the SCORM package creation has been initiated. The object includes a success flag, a message, and a data object containing the request_id
, draft_id
, progress_id
, and the current progress status.
URL
https://library.openelms.com/api/ai-scorm/progress/{requestId}
Method
GET
Description
Gets the current progress status of a SCORM creation request using the requestId
.
Return value
Returns a JSON object with the progress information. This includes the request_id
, progress_status
(e.g., ‘in_progress’), progress messages, and timestamps.
URL
https://library.openelms.com/api/ai-scorm/bulk-upload
Method
POST
Description
Upload a CSV or Excel file containing multiple SCORM requests for batch processing. The CSV/Excel file must have “Title” and “Learning Objective” columns.
Return value
Returns a JSON object confirming the bulk upload has started. The object includes a success flag, a message, a unique batch_id
for the upload, and the number of rows processed from the file.
URL
https://library.openelms.com/api/ai-scorm/bulk-status/{batchId}
Method
GET
Description
Gets the status and progress of a bulk upload batch using the batchId
.
Return value
Returns a JSON object detailing the batch’s status. This includes the batch_id
, counts for total, completed, failed, and pending requests, the success rate, and an array of the individual SCORM requests within the batch.
URL
https://library.openelms.com/api/ai-scorm/batches
Method
GET
Description
Gets a list of recent bulk upload batches with summary information.
Return value
Returns a JSON object containing an array of recent batch summaries. Each summary includes the batch_id
, counts for total, completed, failed, and pending requests, the success rate, and the creation date.
URL
https://library.openelms.com/api/ai-scorm/requests
Method
GET
Description
Gets a paginated list of SCORM requests, with options to filter by batch_id
or status
.
Return value
Returns a JSON object containing a paginated list of SCORM requests. The object includes an array of request data and a pagination object with details like the current page, total pages, and total number of items.