Activate LMS WebAPI Reference

The Activate LMS WebAPI is a set of web services that lets developers integrate Activate LMS with other applications — for example to create and update users, enroll users in learning activities, retrieve launch and login links, and download completion certificates.

The API is included free of charge for active Activate LMS customers, but must be configured for each individual customer. Please contact Activate LMS support for information on how to use and configure the API.

Configuration

To call the WebAPI you need two things from Activate LMS support:

• The application name associated with your Activate LMS instance.
• A security key for your instance.

Both must be passed with every function call in addition to the function's own parameters.

Logging

All interactions with Activate LMS via the WebAPI are logged in the system log.

How to call the web services

Call the web service at this address:

http://www.activatelms.com/System/Webservices/LMSApi.svc

CreateUser

CreateUser(Key, ApplicationName, User);

Description

Creates a user.

If the user is successfully created, a password is automatically generated and emailed to the user. The password can later be changed by the user. The APIResult will return Success: true, Message: "User was successfully created.".

If any auto assignments are defined for the learning profile in the given department, the user will be enrolled in the relevant courses.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
User	CreateUserObject	Yes	An object with the fields listed below. Field names are case sensitive.

User object fields

Field	Type	Required	Description
UserName	String	Yes	The username of the user. Must be unique in the Activate LMS instance. If you want to use the Activate LMS SSO module, this should match the Active Directory field sAMAccountName.
Email	String	Yes	The valid email of the user.
UserFirstName	String	Yes	The user's first name(s).
UserLastName	String	Yes	The user's last name(s).
Department	String	Yes	The organisational unit of the user. To specify a department hierarchy, separate levels by double slash (e.g. Acme Inc//Sales//west). If the department does not exist, it will be created. The root department must exist in Activate LMS.
LearningProfile	String	Yes	A comma-separated list of learning profile names for the user. If a learning profile does not exist, it will be created.
Password	String	No (default null)	If no password is supplied, one is automatically generated.
IsActive	Boolean	No (default true)	Whether the user account should be active.
UserActiveDays	smallint	No (default null)	How many days the user will be active. If not set, the user never expires.
UILanguage	String	No (default: LMS default)	The user's language preference (e.g. da-DK, en-GB).
EmailEnabled	Boolean	No (default true)	Whether notification emails should be sent.
SMSEnabled	Boolean	No (default false)	Whether to enable SMS/text notifications. Requires the user's phone number. Additional fee per SMS notification.
Address	String	No
PostalCode	String	No
City	String	No
Country	String	No
Phone	String	No
SendEmail	Boolean	No (default true)	Whether a notification email with email, password and other information is sent to the user.

Returns

APIResult<CreateUserObject> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	1 if user was created, -1 if an error occurred.
Message	String	Information about any error, or a confirmation message.
ReturnValue	CreateUserObject (optional)	The posted user object.

CreateUser2

CreateUser2(Key, ApplicationName, UserName, Email, UserFirstName, UserLastName,
            Department, LearningProfile, Password, IsActive, UserActiveDays,
            UILanguage, EmailEnabled, SMSEnabled, Address, PostalCode, City,
            Country, Phone, SendEmail);

Description

Same as CreateUser but with the CreateUserObject values split into separate parameters. Data type for all parameters is String. See CreateUser for parameter descriptions.

UpdateUser

UpdateUser(Key, ApplicationName, User);

Description

Updates information about a user.

If the user is successfully updated, the APIResult will return Success: true, Message: "User was successfully updated.".

If any auto assignments are defined for the learning profile in the given department, the user will be enrolled in the relevant courses.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
User	UpdateUserObject	Yes	An object as described below. In addition to UserName (which acts as the unique identifier), it is only necessary to pass the values that are to be updated.

User object fields

Field	Type	Required	Description
UserName	String	Yes	The username of the user.
Email	String	No	The valid email of the user.
UserFirstName	String	No	The user's first name(s).
UserLastName	String	No	The user's last name(s).
Department	String	No	The organisational unit. Use double slash for hierarchy (Acme Inc//Sales//west). Created if missing; root department must already exist.
LearningProfile	String	No	Comma-separated list of learning profile names. If a profile was previously assigned but is not part of the new list, it is removed from the user.
IsActive	Boolean	No	Whether the user account should be active.
UserActiveDays	smallint	No (default null)	How many days the user will be active. If not set, the user never expires.
UILanguage	String	No	The user's language preference (e.g. da-DK, en-GB).
EmailEnabled	Boolean	No	Whether notification emails should be sent.
SMSEnabled	Boolean	No	Whether to enable SMS/text notifications. Requires the user's phone number. Additional fee per SMS.
Address	String	No
PostalCode	String	No
City	String	No
Country	String	No
Phone	String	No

Returns

APIResult<UpdateUserObject> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	2 if user was updated, -1 if an error occurred.
Message	String	Information about any error, or a confirmation message.
ReturnValue	UpdateUserObject (optional)	The posted user object.

DeleteUser

DeleteUser(Key, ApplicationName, UserName);

Description

Deletes a user. If an error occurs, the APIResult will return Success: false with the error message.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
UserName	String	Yes	The username of the user.

Returns

APIResult<string> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	3 if user was deleted, -1 if an error occurred.
Message	String	Information about any error, or a confirmation message.
ReturnValue	String (optional)	If the user was deleted, the UserName of the deleted user.

EnrollUser

EnrollUser(Key, ApplicationName, UserName, ActivityID, IsActive, StartDate,
           DueDate, EndDate, LockOnCompletion, CreateNewInstance);

Description

Enrolls a user in a learning activity. If an error occurs, the APIResult will return Success: false with the error message.

You can call the web service with all parameters (using null for empty values):

Result = API.EnrollUser("1234-abcd-5678-efgh", "www.lmsSite.com",
                        "UserName", 2245, null, null, "2014-12-24", false, false);

Or use named parameters:

APIResult Result = API.EnrollUser(strKey, strApplicationName, "anne-mette",
                                  2245, DueDate: "2014-12-20", EndDate: "2014-12-24");

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
Enrollment	CreateEnrollmentObject	Yes	JSON object with the fields below. Only UserName and ActivityID are required.

Enrollment object fields

Field	Type	Required	Description
UserName	String	Yes	The username of the user.
ActivityID	Integer	Yes	The ID for the learning activity.
IsActive	Boolean	No (default true)	Whether the enrollment is initially active.
StartDate	String yyyy-MM-dd	No (default null)	The day the enrollment becomes available. If supplied, the enrollment is not active immediately but is auto-activated on the StartDate (unless that date is in the past). If not supplied, IsActive applies.
DueDate	String yyyy-MM-dd	No (default null)	The day the enrollment is due.
EndDate	String yyyy-MM-dd	No (default null)	The day the enrollment expires. If not supplied, the enrollment never expires.
LockOnCompletion	Boolean	No (default false)	Whether the enrollment is locked after completion.
CreateNewInstance	Boolean	No (default false)	If the user is already enrolled and this is false, the enrollment is reactivated with the new StartDate and EndDate. If true, a new instance of the activity is created for the user.

Returns

APIResult<EnrollmentObject> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	4 if user was enrolled, 5 if re-enrolled in an existing enrollment, 6 if enrolled in a new instance, -1 if an error occurred.
Message	String	Information about any error, or confirmation.
ReturnValue	EnrollmentObject (optional)	See EnrollmentObject below.

EnrollmentObject

Represents the enrollment details of a user in a learning activity. Returned by functions such as EnrollUser.

Fields

Field	Type	Required	Description
Name	String	Yes	The name of the enrolled activity.
Title	String	No	The title of the enrolled activity.
LaunchLink	String	No	A direct link to launch the enrolled activity.
Children	List<EnrollmentObject>	No	A list of child enrollments, if applicable.

Example (JSON)

{
  "Name": "Introduction to Compliance",
  "Title": "Compliance Training - Level 1",
  "LaunchLink": "http://lms.example.com/launch?activity=1234",
  "Children": [
    {
      "Name": "Module 1: Overview",
      "Title": "Compliance Basics",
      "LaunchLink": "http://lms.example.com/launch?activity=1235"
    }
  ]
}

GetLoginLink and GetLoginLinkValidate

GetLoginLink(Key, ApplicationName, UserName);
GetLoginLinkValidate(Key, ApplicationName, UserName, Password);

Description

Retrieves a login link for the given user. If an error occurs, the APIResult will return Success: false with the error message.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
UserName	String	Yes	The username of the user.
Password	String	Required for GetLoginLinkValidate	The password of the user. Use GetLoginLinkValidate when username/password validation is required.

Returns

APIResult<string> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	7 if the login link was retrieved, -1 if an error occurred.
Message	String	Information about any error, or confirmation.
ReturnValue	String (optional)	If the user exists, the login link.

GetLaunchLink

GetLaunchLink(Key, ApplicationName, UserName, ActivityID, CreateEnrollment, MakeActive);

Description

Retrieves a launch link for the given user enrolled in the activity. If an error occurs, the APIResult will return Success: false with the error message.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the Activate LMS instance.
ApplicationName	String	Yes	The application name associated with the Activate LMS instance.
UserName	String	Yes	The username of the user.
ActivityID	Integer	Yes	The unique ID of the activity. Found in the LMS under the activity's ID field. The activity must exist in the LMS before its ID can be obtained.
CreateEnrollment	Boolean	No (default false)	If true, the enrollment is created if it does not exist.
MakeActive	Boolean	No (default false)	If true, the enrollment is activated if it is not active.

Returns

APIResult<string> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	8 if the launch link was retrieved, 9 if the enrollment was created and the link was retrieved, 10 if the enrollment was activated and the link was retrieved, -1 if an error occurred.
Message	String	Information about any error, or confirmation.
ReturnValue	String (optional)	If the user is enrolled in the activity, the launch link.

GetCertificatePdf

Description

Returns a certificate as a PDF file (stream) based on a specific ActivityUserID. The certificate is delivered without additional customisation.

Parameters

Parameter	Type	Required	Description
ActivityUserID	String	Yes	The ID of the user and activity the certificate is related to.

Example call

GET http://www.activatelms.com/System/Webservices/LMSApi.svc/GetCertificatePdf/{ActivityUserID}

Returns

A PDF file as a stream.

GetCertificatePdfDownload

Description

Returns a certificate as a PDF file (stream) with the option to specify the file name and download behaviour. This gives flexibility for displaying or downloading the file based on user needs.

Parameters

Parameter	Type	Required	Description
ActivityUserID	String	Yes	The ID of the user and activity the certificate is related to.
FileName	String	No	The desired name for the downloaded file.
Disposition	String	No	"inline" displays the PDF directly in the browser; "attachment" downloads the PDF as a file.

Example call

GET http://www.activatelms.com/System/Webservices/LMSApi.svc/GetCertificatePdf?ActivityUserID={ActivityUserID}&FileName={FileName}&Disposition={Disposition}

Returns

A PDF file as a stream. Depending on Disposition, it can be presented as a download or displayed in the browser.

Difference from GetCertificatePdf

GetCertificatePdf returns the certificate with default presentation. GetCertificatePdfDownload additionally lets you customise the file name and control whether the file is shown inline or downloaded.

GetEnrollments

GetEnrollments(Key, ApplicationName, UserName);

Description

Retrieves a list of a user's enrollments in learning activities. If an error occurs, the APIResult will return Success: false with the error message.

Parameters

Parameter	Type	Required	Description
Key	String	Yes	The unique key associated with the LMS instance.
ApplicationName	String	Yes	The application name associated with the LMS instance.
UserName	String	Yes	The unique username of the user in the LMS.

Returns

APIResult<List<EnrollmentListItem>> — an object with:

Field	Type	Description
Success	Boolean	true if successful, false if not.
Code	Integer	11 on success, -1 if an error occurred.
Message	String	Error description or confirmation.
ReturnValue	List<EnrollmentListItem>	A list of enrollment details for the user.

Example call

APIResult<List<EnrollmentListItem>> result = API.GetEnrollments(
    "1234-abcd-5678-efgh",
    "www.lmsSite.com",
    "john.doe");

EnrollmentListItem

Represents details about a specific enrollment for a user in a learning activity. Used in the return value for GetEnrollments.

Fields

Field	Type	Required	Description
Id	Integer	Yes	The ID of the learning activity.
Name	String	Yes	The name of the learning activity.
TypeName	String	No	The type of learning activity (e.g. course, test).
Description	String	No	A brief description of the activity.
Author	String	No	The name of the activity author.
DurationMinutes	Integer	No	Duration of the activity in minutes.
ImageUrl	String	No	A URL to an image representing the activity.
LaunchUrl	String	No	A direct link to launch the activity.
DueDate	DateTime	No	The due date for completing the activity.
EnrollmentStatus	EnrollmentStatus	Yes	The status of the enrollment.
Children	List<EnrollmentListItem>	No	A list of child enrollments, if applicable.

Example (JSON)

{
  "Id": 101,
  "Name": "Compliance Training",
  "TypeName": "Course",
  "Description": "Learn about compliance requirements.",
  "Author": "Jane Doe",
  "DurationMinutes": 60,
  "ImageUrl": "http://lms.example.com/images/compliance.png",
  "LaunchUrl": "http://lms.example.com/launch?activity=101",
  "DueDate": "2025-01-31T00:00:00",
  "EnrollmentStatus": {
    "IsActive": true,
    "IsLocked": false,
    "Status": "In Progress",
    "Score": null,
    "CertificateUrl": null
  },
  "Children": []
}

EnrollmentStatus

Describes the status of a specific enrollment.

Fields

Field	Type	Required	Description
IsActive	Boolean	Yes	Whether the enrollment is active.
IsLocked	Boolean	Yes	Whether the enrollment is locked.
Status	String	Yes	The status of the enrollment (e.g. "In Progress", "Completed").
Score	Decimal	No	The user's score for the activity, if applicable.
CertificateUrl	String	No	A URL to a certificate, if available.