API Reference

This document contains information about the application programming interfaces (APIs) offered by Educatia AS to developers. Note that you need a valid license to use the web services described here.

General

The API uses a REST-style interface over HTTP(S). The API endpoint for the cloud service is https://secure.e-learning.no/web/services and all paths below are relative to that. Different endpoints will exist for on-premise installations and for test environments.

Developers may use command-line tools such as curl or browser plugins such as RESTClient for Firefox to test the API.

API Keys and Authentication

The API is stateless and each request must contain an API key to authenticate the request. An API key is associated with a specific user account. The API key has the same permissions and privileges as the user when that user is logged into the system via the GUI. It is recommended that you create a separate user for API usage, and assign this user the minimum privileges it needs to do its work.

How to get your API Key

To view the API key of a user, do the following:

  1. Login as the System Administrator
  2. Click "Administrators"
  3. Click on an administrator (or create one if one does not already exist)
  4. Click the "Change" button
  5. Set the "Shared Account" setting to "Yes" and click "Save Changes"
  6. On the Administrator Details page, click the "View API Key" link to view the API Key
Note: API keys should be treated like passwords and should never be exposed in client-side code (such as Javascript) and never transmitted in plain text. All web service calls should be over HTTPS to ensure that the API key is protected.

If an API key has been compromised, a new API key can be issued by the system administrator by changing the password for the user associated with the API key.

All requests must be made over HTTPS (HTTP requests will return an error). Note that test environments may be configured to accept insecure (HTTP) requests to facilitate testing and troubleshooting.

Request Format

The API receives values via HTTP requests. Parameter values are passed using HTTP POST.

A sample request looks like this:

  curl https://secure.e-learning.no/web/services/exam.get_results -d "api_key=YOUR_API_KEY&exam_session_id=1234"

In addition to parameters specific to each service operation, the following parameters are common to all calls:

Parameter Description Required Default
api_key The API key used to authenticate. See the section about API Keys above for more information. Yes
api_version Specifies the API version used to make the call. At the time of writing, version 1.0 is the latest version. No latest_version

For brevity, these parameters are not included in the example calls below.

Response Format

The API always returns a JSON object with the Content-Type set to application/json. If the request was successful, the requested object is returned. If the call fails, a JSON object is returned with details about the error.

Unless otherwise noted, date values are represented using the ISO 8601 format, as local time (without a time zone designator), for example 2014-01-20T12:57:00. Booleans are represented with Y for true and N for false.

Example Response:

[{
  "exam_session_status": "COMPLETED",
  "exam_session_result": "FAILED",
  "exam_session_score": "60",
  "api_status": "OK",
  "api_message": "Session found.",
  "api_datetime": "2014-01-20T12:57:00"
}]

In addition to return values specific to each service operation, the following return values are common to all calls:

Property Description
api_status A code indicating the status of the call. If the call was successful, the string OK is returned, otherwise the string ERROR is returned.
api_message A text string containing more information about the result of the call.
api_datetime The current server date and time.

For brevity, these properties are not included in the example return values below.


Person Service

List persons

This call lists persons (users).

/person.list

The call has the following parameters:

Parameter Description Required Default
search_name A string that filters persons by name. No
search_email A string that filters persons by email address. No
search_group_name A string that filters persons by group name. No

The call returns the following:

Property Description
list A list of persons matching the search criteria.

Example Request:

  curl https://secure.e-learning.no/web/services/person.list -d "search_name=john"

Example Response:

[{
"list":[
{
"group_name":"Sales",
"person_email":"kari@example",
"person_id":"1342",
"person_name":"Kari Johnsen"
}, 
{
"group_name":"Sales",
"person_email":"john@example",
"person_id":"259",
"person_name":"John Doe"
}, 
{
"group_name":"Sales",
"person_email":"",
"person_id":"1529",
"person_name":"Johnny Mueller"
}
]
}]

Get temporary login URL

This call returns a temporary login link for a given person (user). It can be used to enable Single Sign-On from your system, so that users do not have to login with a username and password.

For example, if you want users to access our service from your corporate intranet, you would make a call to this API and pass the ID of the person (if necessary, use the person.list API first to retrieve the person ID based on email or name). Alternatively, pass one or more of the alternative identifiers (employee number, mobile phone number, etc.) to identify a person.

Then you simply redirect to the URL returned from the API (or add the URL as a link that can be clicked by the user on a web page, or perhaps in an email).

Note that the URL changes each time this API is called, and expires when the URL is used to login, so do not store the URL permanently. You should request a new, temporary login URL each time the user wants to login.

/person.get_temporary_login_url

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. No
person_name The name of the person. No
person_email The email address of the person. No
person_mob The mobile phone number of the person. No
employee_number The employee number of the person. No

The call returns the following:

Property Description
person_login_url A unique link that allows the user to login (one time) without specifying a username or password.

Example Request:

  curl https://secure.e-learning.no/web/services/person.get_temporary_login_url -d "person_id=1234"

Example Response:

[{
"person_login_url":"https://secure.e-learning.no/sso/example-company/1234/ILQ4AM1B2T9ONOD3E8MRNSAZXKJWCI50LZH5"
}]

Add person

This call adds a new person (user).

/person.add

The call has the following parameters:

Parameter Description Required Default
person_name The name of the person. Yes
person_email The email address of the person. No
group_id A number that identifies a group. No The group defined as default for new users.

The call returns the following:

Property Description
person_id A number that identifies the person.

Example Request:

  curl https://secure.e-learning.no/web/services/person.add -d "person_name=john"

Example Response:

[{
"person_id":"1234"
}]

Add or update person

This call adds a new person (user) or updates an existing person (user). This API call is typically used to keep user data synchronized with an external system. When trying to determine if the person already exists, the system first uses the person ID (if specified), then the employee number, and finally attempts to match against the person's name, email address and phone number.

/person.add_or_update

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. No
person_name The name of the person. Yes
person_email The email address of the person. No
person_mob The mobile phone number of the person. No
employee_number The employee number of the person. No
company_name The name of the company or organization that the person works for. No
department_name The name of the department that the person belongs to. No
job_title The job title (position) of the person. No
profile_list A colon-separated list of competency profiles that should be assigned to the person. No
group_id A number that identifies a group that the new person should be added to (new persons only). If specified, the group ID takes precedence over the group code and group name. No The group defined as default for new users.
group_code A string that identifies a group that the new person should be added to (new persons only). If specified, the group code takes precedence over the group name. No
group_name The name of the group that the new person should be added to (new persons only). No
lang_code The language code of the person. No
manager_number The employee number of the person's manager. No
is_active A boolean that indicates if the person is active or not. Inactive users will not be able to login to the system. No Y
send_message A boolean indicating whether the person should receive a welcome message (new persons only). No N
employed_from_date The person's employment start date. No
employed_to_date The person's employment to date. No
employment_category The person's employment category (full time, part time, contractor, apprentice, retired, etc.). No
employment_pct The person's employment as a percentage of full-time employment. No
salary_group The person's salary group code. No
salary_level The person's salary level. No
gender The person's gender. Valid values are M for males or F for females. No
birth_date The person's birth date. No
nationality The person's nationality. No
next_of_kin_name The person's next of kin name. No
next_of_kin_mob The person's next of kin mobile phone number. No
address The person's postal address. No
post_code The person's postal code. No
post_area The person's postal area name. No
country_name The person's country of residence. No
sso_user_name A string that identifies the person for Single Sign-On (SSO) purposes. No

The call returns the following:

Property Description
person_id A number that identifies the person.

Example Request:

  curl https://secure.e-learning.no/web/services/person.add_or_update -d "person_name=john&employee_number=4567&department_name=Accounting"

Example Response:

[{
"person_id":"1234"
}]

Move person to trashcan

This call moves a person to the trashcan (Recycle Bin). To permanently delete a person's data, an administrator must purge the trashcan.

/person.trash

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. No
person_name The name of the person. No
person_email The email address of the person. No
person_mob The mobile phone number of the person. No
employee_number The employee number of the person. No

The call returns the following:

Property Description
person_id A number that identifies the person.

Example Request:

  curl https://secure.e-learning.no/web/services/person.trash -d "employee_number=4567"

Example Response:

[{
"person_id":"1234"
}]

List person messages

This call lists all messages sent to a given person.

/person.list_messages

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. Yes

The call returns the following:

Property Description
list A list of messages.

Example Request:

  curl https://secure.e-learning.no/web/services/person.list_messages -d "person_id=1234"

Example Response:

[{
"list":[
{
"body":"Click this link to login:  \n\nNOTE: The link above contains your private code, do not share the link with others.\n\nIf you need help, please contact no-reply@example",
"message_id":"3541",
"sent_date":"",
"title":"Welcome to e-learning at ExampleCompany",
"type":"SEC"
}, 
{
"body":"Click this link to start: \n\nNOTE: You must complete "Your first course" by 20.01.2014",
"message_id":"3542",
"sent_date":"",
"title":"Your first course",
"type":"NOT"
}
]
}]

List person courses

This call lists all courses a given person has been enrolled in.

/person.list_courses

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. Yes

The call returns the following:

Property Description
list A list of courses.

Example Request:

  curl https://secure.e-learning.no/web/services/person.list_courses -d "person_id=1234"

Example Response:

[{
"list":[
{
"completed_date":"",
"course_enrolment_id":"850",
"course_name":"Your first course",
"feedback":"",
"progress":"0",
"rating":"",
"started_date":""
}
]
}]

Add a course to person's course history

This call adds a course to a person's history of courses.

/person.add_course_history

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. If this is specified, it takes presedence over the employee number. No
employee_number A string that identifies a person. No
course_id A number that identifies a course. If this is specified, it takes presedence over the course code. No
course_code A string that identifies a course. No
start_date The start date of the course. No
end_date The end date of the course. No
expiry_date The expiry date of the course/certificate. No
diploma_url A link (URL) to the person's diploma or other documentation of the completed course. No
location_name The name of the location where the course was taken. No
teacher_name The name of the course instructor. No
remarks Comments related to the course. No
skip_duplicates A boolean that indicates if existing person/course combinations should be skipped. No Y

The call returns the following:

Property Description
course_session_id A number that uniquely identifies the course session.

Example Request:

  curl https://secure.e-learning.no/web/services/person.add_course_history -d "course_id=100&person_id=991"

Example Response:

[{
  "course_session_id": "1234"
}]

List person exams

This call lists all exams a given person has started or completed.

/person.list_exams

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. Yes

The call returns the following:

Property Description
list A list of exams.

Example Request:

  curl https://secure.e-learning.no/web/services/person.list_exams -d "person_id=1234"

Example Response:

[{
"list":[
{
"completed":"Y",
"completed_date":"2014-01-19T16:56:15",
"exam_name":"Computer Skills Assessment",
"exam_session_id":"830",
"passed":"N",
"score":"0",
"started_date":"2014-01-19T16:56:04"
}, 
{
"completed":"Y",
"completed_date":"2014-01-19T16:56:29",
"exam_name":"Office 2010 Pre-Test",
"exam_session_id":"831",
"passed":"Y",
"score":"100",
"started_date":"2014-01-19T16:56:21"
}
]
}]

List person CV items

This call lists all CV items for given person.

/person.list_cv

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person. Yes

The call returns the following:

Property Description
list A list of CV items.

Example Request:

  curl https://secure.e-learning.no/web/services/person.list_cv -d "person_id=1234"

Example Response:

[{
"list":[
{
"description":"",
"from_date":"",
"item_id":"261",
"location":"",
"name":"English",
"organization":"",
"to_date":"",
"type":"LAN"
}, 
{
"description":"",
"from_date":"",
"item_id":"262",
"location":"",
"name":"German",
"organization":"",
"to_date":"",
"type":"LAN"
}, 
{
"description":"",
"from_date":"",
"item_id":"263",
"location":"",
"name":"French",
"organization":"",
"to_date":"",
"type":"LAN"
}, 
{
"description":"",
"from_date":"2014-01-01T00:00:00",
"item_id":"264",
"location":"",
"name":"Certified Technician",
"organization":"",
"to_date":"2014-12-31T00:00:00",
"type":"CER"
}
]
}]

Search CVs

This call searches for persons (users) with CVs that contain matching keywords.

/person.search_cv

The call has the following parameters:

Parameter Description Required Default
search_string A string that represents the keywords being searched for. Yes
group_id A number that identifies a group. If specified it limits the search to persons in the group. No
since_days A number that limits the search to recent CV entries. No

The call returns the following:

Property Description
list A list of persons matching the search criteria.

Example Request:

  curl https://secure.e-learning.no/web/services/person.search_cv -d "search_string=truck high school german"

Example Response:

[{
"list":[
{
"person_id":"1342",
"person_name":"Kari Johnsen",
"search_score":"12"
}, 
{
"person_id":"259",
"person_name":"John Doe",
"search_score":"7"
}, 
{
"person_id":"1529",
"person_name":"Johnny Mueller",
"search_score":"3"
}
]
}]

Course Service

List courses

This call lists courses.

/course.list

The call has the following parameters:

Parameter Description Required Default
search_name A string that filters courses by name. No
search_subject A string that filters courses by subject. No
course_type A string that filters courses by type. Valid values are STD for standard e-learning courses, CLA for classroom courses, and EXT for external courses. No

The call returns the following:

Property Description
list A list of courses matching the search criteria.

Example Request:

  curl https://secure.e-learning.no/web/services/course.list -d "search_type=EXT"

Example Response:

[{
"list":[
{
"course_id":"114",
"course_name":"Safety Course 101",
"course_subject":"HSEQ"
}, 
{
"course_id":"200",
"course_name":"Fire Prevention Course",
"course_subject":"HSEQ"
}
]
}]

Add course

This call adds a new course.

/course.add

The call has the following parameters:

Parameter Description Required Default
course_name The name of the course. Yes
course_code A string that identifies the course. No
course_url A link (URL) with more information about the course. No
course_description A description of the course. No
folder_id A number that identifies a folder location for the course. No

The call returns the following:

Property Description
course_id A number that identifies the course.

Example Request:

  curl https://secure.e-learning.no/web/services/course.add -d "course_name=HSEQ"

Example Response:

[{
"course_id":"1234"
}]

Enrol person in course

This call enrols a person in a course and returns information about the enrolment.

/course.enrol_person

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person (student). No
course_id A number that identifies a course. No
send_message A boolean indicating whether the person should receive a message notification about the enrolment. No Y

The call returns the following:

Property Description
course_session_id A number that uniquely identifies the course session (enrolment).
course_session_url A unique link (URL) that can be used to view the course.

Example Request:

  curl https://secure.e-learning.no/web/services/course.enrol_person -d "course_id=100&person_id=991"

Example Response:

[{
  "course_session_id": "1234",
  "course_session_url": "https://secure.e-learning.no/course/example-company/1234/ILQ4AM1B2T9ONOD3E8MRNSAZXKJWCI50LZH5"
}]

Create standalone course session

This call creates a "standalone" session; that is, it registers a new student and grants access to a single course. It returns a unique URL used to start that course, and an course session ID that can be used to track course session status.

/course.create_standalone_session

The call has the following parameters:

Parameter Description Required Default
course_id A number that identifies a course. Yes
student_name The name of the student. No
student_email The email of the student. If this is specified, the student will receive an email which includes the link to start the course. No
exit_url A URL that the student will be redirected to when the course is completed. If specified, this session-specific URL overrides any fixed exit URL configured for the course. No

The call returns the following:

Property Description
person_id A number that uniquely identifies the person (student).
course_session_id A number that uniquely identifies the course session.
course_session_url A unique link (URL) that can be used to start the course.

Example Request:

  curl https://secure.e-learning.no/web/services/course.create_standalone_session -d "course_id=1234&student_name=john%20doe"

Example Response:

[{
  "course_session_id": "1234",
  "course_session_url": "https://secure.e-learning.no/course/example-company/1234/ILQ4AM1B2T9ONOD3E8MRNSAZXKJWCI50LZH5",
  "person_id": "5551"
}]

Get course enrolment status

This call retrieves the course status results for a given course session (enrolment).

/course.get_enrolment_status

The call has the following parameters:

Parameter Description Required Default
course_session_id A number that identifies a course session (enrolment). Yes

The call returns the following:

Property Description
course_session_id A number that identifies a course session (enrolment).
course_session_progress A number that represents the progress of the course session, as a percentage of the total number of pages in the course.
course_session_status A string that indicates the status of the exam session. Possible values are APPROVAL_REQUIRED, ENROLLED, IN_PROGRESS, COMPLETED, OBSOLETED or CANCELLED.

Example Request:

  curl https://secure.e-learning.no/web/services/course.get_enrolment_status -d "course_session_id=1234"

Example Response:

[{
  "course_session_id": "1234",
  "course_session_progress": "100",
  "course_session_status": "COMPLETED"
}]

Exam Service

List exams

This call lists exams.

/exam.list

The call has the following parameters:

Parameter Description Required Default
search_name A string that filters exams by name. No
search_subject A string that filters exams by subject. No

The call returns the following:

Property Description
list A list of exams matching the search criteria.

Example Request:

  curl https://secure.e-learning.no/web/services/exam.list -d "search_subject=office"

Example Response:

[{
"list":[
{
"exam_id":"114",
"exam_name":"Advanced Macros with Excel 2010",
"exam_subject":"MS Office"
}, 
{
"exam_id":"200",
"exam_name":"Office 2010 Pre-Test",
"exam_subject":"MS Office"
}
]
}]

Grant exam access

This call grants access to an exam and returns a unique URL used to start that exam.

/exam.grant_access

The call has the following parameters:

Parameter Description Required Default
person_id A number that identifies a person (student). Yes
exam_id A number that identifies an exam. Yes
access_ip_address If this value is specified, access to the exam is restricted to this IP address. No
access_duration The duration of access to the exam. The value is specified in minutes. No 60

The call returns the following:

Property Description
exam_access_url A unique link (URL) that can be used to start the exam. The link is valid for a specific duration, and for a specific IP address if that was specified.

Example Request:

  curl https://secure.e-learning.no/web/services/exam.grant_access -d "exam_id=432&person_id=991"

Example Response:

[{
  "exam_access_url": "https://secure.e-learning.no/exam/example-company/1234/ILQ4AM1B2T9ONOD3E8MRNSAZXKJWCI50LZH5"
}]

Create standalone exam session

This call creates a "standalone" session; that is, it registers a new student and grants temporary access to a single exam. It returns a unique URL used to start that exam, and an exam session ID that can be used to track exam progress.

/exam.create_standalone_session

The call has the following parameters:

Parameter Description Required Default
exam_id A number that identifies an exam. Yes
student_name The name of the student. No
student_email The email of the student. If this is specified, the student will receive an email which includes the link to start the exam. No
access_ip_address If this value is specified, access to the exam is restricted to this IP address. No
access_duration The duration of access to the exam. The value is specified in minutes. No 60
exit_url A URL that the student will be redirected to when the exam is completed. If specified, this session-specific URL overrides any fixed exit URL configured for the exam. No

The call returns the following:

Property Description
person_id A number that uniquely identifies the person (student).
exam_session_id A number that uniquely identifies the exam session.
exam_session_url A unique link (URL) that can be used to start the exam. The link is valid for a specific duration, and for a specific IP address if that was specified.

Example Request:

  curl https://secure.e-learning.no/web/services/exam.create_standalone_session -d "exam_id=1234&student_name=john%20doe"

Example Response:

[{
  "exam_session_id": "1234",
  "exam_session_url": "https://secure.e-learning.no/exam-start/example-company/1234/ILQ4AM1B2T9ONOD3E8MRNSAZXKJWCI50LZH5",
  "person_id": "5551"
}]

Get exam results

This call retrieves the exam results for a given exam session ID.

/exam.get_results

The call has the following parameters:

Parameter Description Required Default
exam_session_id A number that identifies an Exam Session. Yes
include_answers A boolean that indicates if questions and answers should be included in the response. No N

The call returns the following:

Property Description
exam_session_status A string that indicates the status of the exam session. Possible values are NOT_STARTED, IN_PROGRESS or COMPLETED.
exam_session_result A string that indicates the result of the exam session. Possible values are UNDEFINED (if the session has not been completed), PASSED or FAILED.
exam_session_score The student's exam score, expressed as a percentage of correct answers.
list A list of questions and answers for the exam session.

Example Request:

  curl https://secure.e-learning.no/web/services/exam.get_results -d "exam_session_id=1234"

Example Response:

[{
  "exam_session_status": "COMPLETED",
  "exam_session_result": "FAILED",
  "exam_session_score": "60"
}]

Widget Service

Get widget

This call retrieves a widget with pre-generated content from the LMS, suitable for embedding/rendering on a web page, such as an intranet site.

Note: Remember that API keys should never be exposed to the client, so avoid calling this (and all the other APIs) from client-side script. The retrieval of the widget and the rendering must happen on the server.

The typical use case for using this API is to provide users with content from the LMS without having to login, and also to provide pass-through Single Sign-On functionality via a temporary login link in the returned widget.

/widget.get

The call has the following parameters:

Parameter Description Required Default
widget_type A string that specifies the widget type to be retrieved. Valid values are DEFAULT, SSO and SSO_REDIRECT. No DEFAULT
person_id A number that identifies a person. If a value is specified, the other personal identifiers will be ignored. If this is left empty, specify one or more of the other personal identifiers to identify the current user. No
person_name The name of the person. No
person_email The email address of the person. No
person_mob The mobile phone number of the person. No
employee_number The employee number of the person. No
sso_user_name A string that identifies the person for Single Sign-On (SSO) purposes. No

The call returns the following:

Property Description
widget_type A string that describes the type of widget. Possible values are SSO and SSO_REDIRECT.
widget_format A string that describes the format of the widget_content value. Possible values are HTML and REDIRECT.
widget_content A string that contains the widget markup. If the widget_format is HTML then the API client should embed the content as-is and display it to the end-user without modification. If the widget_format is REDIRECT then the API client should redirect the user to the URL specified as the content value.

Example Request:

  curl https://secure.e-learning.no/web/services/widget.get -d "person_email=john.doe@example.com"

Example Response:

[{
  "widget_type": "SSO",
  "widget_format": "HTML",
  "widget_content": "some HTML string here"
}]