NAV Navbar
shell

LearnUpon technical documentation

Use the LearnUpon API (Application Programming Interface) to connect to LearnUpon's system and exchange data, to support your business workflows.

LearnUpon API guide

As a learning management system (LMS), LearnUpon integrates with the software you already use, to train your employees, partners, and customers.

The LearnUpon API can speed up processes by automating time-consuming manual steps. LearnUpon's API lets you create and add users to groups, enroll them in courses, and send data back to your 3rd party system.

The LearnUpon API is RESTful. Customers access it via Basic HTTP authentication over HTTPS/TLS.

This guide highlights the basic steps for consuming the LearnUpon API. The intended audience is a developer with HTTP and JSON API experience, or a technical decision maker.

Get started

To get the most from this guide, you need to know about:

API access and authentication

The full URL for accessing the API is

https://yourdomain.learnupon.com/api/v1/resource

To access the API, companies using LearnUpon must authorize themselves via Basic HTTP Authentication over HTTPS/SSL.

For authorized access to your API endpoint, you need an API username and password. These API credentials, called keys, are different from your login credentials for LearnUpon.

Get your API keys

  1. Log in to your LearnUpon portal as an admin

  2. Select Settings > Integrations > API Keys

  3. Select Generate New Keys

If you do not see the API Keys option under Integrations contact the LearnUpon Support team to request them.

These example API keys, which appear in some code examples, are decommissioned.

username: 988d4f1313f881e5ac6bfdfc7f54244aab

password: 905a12r3a0c

Data pagination

All the API endpoints which list data, such as /enrollments or /users endpoints, use data pagination to manage the returned data.

The returned data lists 500 records per page.

To specify a page of data to return, use the page attribute in your requests. For example:

/users?page=3

returns users in your portal, starting on page 3 of your data.

LearnUpon reserves the right to review this pagination size, if required. If LearnUpon changes this page size in future, you will get advance notice to accommodate the change. LearnUpon recommends you program requests and responses to work with a dynamic pagination size, so any change in records per page will not affect your workflows.

To find out which page the API is retrieving and, more importantly, whether more pages are available (your response's pagination status), check the API HTTP response headers. Each response that supports pagination returns the headers listed in the following table.

API HTTP response headers about pagination

Header name Type Description
LU-Current-Page integer Tells you the current page of data that was returned in a response.
LU-Records-Per-Page integer Default: 500 records. Lists the number of records being rendered per page of data. Use this header to dynamically manage different page sizes, if the default value changes.
LU-Has-Next-Page boolean Indicates if more pages of data exist after the current page. Use this value to decide if you need a further API request to get more data in your list.

API throttling and suggested usage patterns

LearnUpon uses rate limiting to prevent abuse of the API, and prevent any negative impact on your portal or other customers' portals

Rate limit

The custom HTTP response headers lists the API rate limit.

These limits can vary for different types of customers and usage patterns, so your code must be able to respond to scenarios where you are close to reaching your limit.

The rate limits apply per portal, rather than per realm. In LearnUpon terms, a realm is a top-level portal and any sub-portals linked to a single top-level portal.

Both API and OAuth requests count towards the limit per portal.

Rate limit response headers

Header name Type Description
X-LU-Rate-Limit-Remaining-Minute integer Shows the number of remaining API requests for the current minute of the day.
X-LU-Rate-Limit-Remaining-Week integer Shows the number of remaining API requests for the rest of the week, calculated on a rolling basis, not a calendar basis.

The per-minute limit helps spread your API load over time, to support the overall performance of the LearnUpon API. Use this to determine when it is safe to send the next API requests. You can set up "sleep" concepts in your code, or the more thorough use of "exponential backoff".

The weekly limit helps prevent significant abuse, or denial of service attempts against the API. In the unlikely event you approach this limit, contact LearnUpon support to discuss API use-cases, and potential alternatives.

The rolling calculation means: if you use the API this Wednesday, the remaining week figure runs from that use on Wednesday to next Wednesday.

Usage patterns

If your integration is bursty in nature - for example, you occasionally create several hundred users and add their enrollment in several courses - consider prioritizing functions that you require immediately, and throttle everything else.

Large batch actions generally fall into 2 categories:

For other examples, use the same approach of identifying the most urgent tasks, and then throttling the less urgent tasks.

Additional advice

Before investing time and money in a large integration, contact your Customer Success Manager or the Support team for additional advice. They will happily discuss your usage requirements, identify any areas of concern, or suggest alternative approaches.

Sample API calls and responses

For testing outside of any client/consumer code, use the ubiquitous cURL command from any terminal window, to simulate an API consumer access. When using cURL from the command line, you may need to enclose URLs containing special characters, like ampersand (&), in quotes.

The samples in this guide use cURL. However, you can write an API consumer in any programmatic language that uses HTTPS requests.

cURL quote issue in Windows: example

If you use the cURL examples in a Windows environment, be aware that some versions of cURL on Windows have problems with the quoting. Try swapping the double quotes delimiting strings in the JSON payload to single quotes, and wrap the entire JSON payload in single quotes, not double (i.e. swap the single/double quotes throughout). This change produces invalid JSON, but lets problematic versions of cURL on Windows to execute the examples.

So for

curl .. -d '{"key":"value"}'

Replace with

curl .. -d "{'key':'value'}"

Using code samples: tips

This guide describes Boolean values as true and false throughout.

When testing your integration, if these values either generate an error, or don't return a result, try exchanging 1 for true and 0 for false.

Users

The users resource lets you create, search for (retrieve, find, or list), update and delete users.

Unique identifiers: email or username

LearnUpon uses a user's email attribute as a default unique identifier throughout the LMS.

You can set up the username attribute as an alternate unique identifier, if this attribute serves your business workflows better: for example, if your learners do not use email regularly.

Discuss the business decision with your Customer Success Manager.

If you set up usernames, requirements are:

If you need a username with less than 6 characters, you can request a change to 3-character minimum length. Contact the Support team.

Methods: users

The search methods return the same data objects. The GET using {id} returns awards in addition to user and CustomData objects.

GET requests must contain standard Query String parameter formats.

Method Description of output
GET /users Lists all users on the portal
GET /users?version_id=1.1 Lists all users on the portal, plus updated_by date in user object attributes
GET /users/{id} Searches by id: return includes custom user data
GET /users/search?email= Searches by email: return includes custom user data
GET /users/search?username= Searches by username: return includes custom user data
GET /users/instructor_users For ILTs: lists the instructors and managers+instructors on the portal
GET /users/customuserdata Lists all custom user data fields
POST /users Creates a user: needs a minimum of email or username
PUT /users/ Updates a user: requires either id, or email as part of payload
DELETE /users/{id} Deletes a user account

Search for users

cURL to search for all users


 curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/users

cURL to search for all users: user object includes updated_by field


 curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/users?version_id=1.1

cURL to search for a user by user_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/123123

Sample search and response for a user by email

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/search?email=learnuponapi@samplelearningco.com


{"user":[{"id":662,"first_name":"Learn","last_name":"Upon","email":"learnuponapi@samplelearningco.com",
"created_at":"2012-12-18T15:30:09Z", "locale" : "de" }]}

Sample search and response for a user by username

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/search?username=learnupon


{"user":[{"id":662,"first_name":"Learn","last_name":"Upon","email":"learnuponapi@samplelearningco.com",
"username":"learnupon", "created_at":"2012-12-18T15:30:09Z", "locale" : "de" }]}

Sample search and response for users with instructor user type

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/instructor_users

{"instructor_users":[{"id":291141,"username":"","email":"demouser1@learnupontest.com","first_name":"Berengar","last_name":"Hesse","instructor_pm_id":1475833,"user_type":"instructor"},{"id":291134,"username":"","email":"demouser13@learnupontest.com","first_name":"Charles","last_name":"Martel","instructor_pm_id":1475826,"user_type":"instructor"}]}

Sometimes called list, or find.

By default, a call with no parameters returns all users on the portal. For individual results, you must specify either email or username, as a unique identifier. See Unique identifiers: email or username.

Parameter name Type Description
email string Email address of the user: default unique identifier
username string Username of the user: alternate unique identifier
Parameter name Type Description
version_id=1.1 string Includes updated_at in the user object attributes, to indicate the most recent change to any of email, first_name, last_name, username, display_name, email_disabled, or a reset password request
login_enabled boolean Set to true to return enabled users only, set to false to return disabled users only
Attribute name Type Description
user object An object containing the list of users
customDataFieldDefintions object An object containing the list of custom data field definitions. Returned only when the portal admin has defined custom user data fields

User object attributes

These attributes are available for user objects. Not every attribute appears in a search result: the results depend on user type.

Attribute name Type Description
id integer The unique numeric identifier for the user
last_name string The last name of the user
first_name string The first name of the user
email string The email address of the user: see Unique identifiers: email or username
username string Appears only if you set up username in place of email as a unique identifier. See Unique identifiers: email or username.
locale string The ISO language code for the user. See the appendix for a list of supported languages. If not set, then default is the portal's language.
created_at date/time The date the user was created, in UTC format
updated_at date/time The date of recent change to indicate the most recent change to any ofemail, first_name, last_name, username, display_name, email_disabled, or a reset password request, in UTC format
last_sign_in_at date/time The date the user last signed into LearnUpon, in UTC format
account_expires date/time The date you set the user's account to expire. Expired accounts cannot access LearnUpon. This attribute overrides enabled attribute. Required format is yyyy-mm-dd like 2024-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2024
sign_in_count integer The number of times the user logged into LearnUpon
enabled boolean If set to (default)true, indicates the user's account is enabled. An account can remain enabled even if the account has expired: you must check the account_expires attribute, and vice versa. account_expires overrides enabled
user_type string Indicates the user type and their permissions in the portal: one of learner, instructor, manager, admin
can_enroll boolean Manager user type only: indicates if the user can enroll learners in courses. Default is true
can_unenroll_users boolean Manager user type only: indicates of the user can unenroll learners in courses. Default is false
can_mark_complete boolean Manager user type only: indicates if the user can manually mark complete learners on courses. Default is false
can_move_groups boolean Manager user type only: indicates if the manager can move users from one group to another. The manager must be assigned as manager for both groups. Default is false
can_act_as_instructor boolean Manager user type only: indicates if the manager has instructor permissions. Default is false
can_manage_trainings boolean Instructor user type only: indicates if the instructor can create and edit ILT modules in the ILT Center. Default is false
can_manage_sessions boolean Instructor user type only: indicates if the instructor can create and edit ILT sessions in the ILT Center. Default is false
tutor_can_edit_their_courses boolean Instructor user type only: indicates if the user can edit the courses that they instruct. Default is true
tutor_can_create_courses boolean Instructor user type only: indicates if the user can create their own courses. Default is false
number_of_enrollments integer Indicates the number of enrollments for the specified user
number_of_enrollments_accessed integer Indicates the number of enrollments that the user has in progress, completed, passed status
CustomData object Optionally defined by admins on your portal: custom data refers to any custom user data fields that you created on your portals
membership_type string Associations and memberships feature only. Indicates the membership type of the users. LearnUpon provides Member or Non-member options by default: add new membership types through the portal interface. Attribute options must have no spaces: use hyphens or underscores
number_of_points integer Gamification only: total number of gamification points awarded to the user
number_of_badges integer Gamification only: total count of gamification badges awarded to the user
sf_contact_id string Salesforce only: Contact ID. Returns null if user record doesn’t have a Salesforce Contact ID
sf_user_id string Salesforce only: Salesforce User ID. Returns null if user record doesn’t have a Salesforce user ID
is_salesforce_contact boolean Salesforce only: Returns null if user isn’t a Salesforce Contact
customDataFieldValues object Optional: an object containing custom user data details

customDataFieldValues object attributes

Attribute name Type Description
value string, decimal, integer, string_choice, decimal_choice, integer_choice or date Contains the custom user data value. This data type matches the type defined in CustomDataFieldDefinitions, type_id attribute. Date requires YYYY-MM-DD format
definition_id integer A unique numeric identifier for the custom user data field

Data attributes returned for custom user data

Attribute name Type Description
customDataFieldDefinitions object An object containing the list of custom user data fields

CustomDataFieldDefintions object definitions

Attribute name Type Description
id integer Unique numeric identifier for the custom user data field
type_id integer A numeric value identifying the custom user data field type: see the following type_id definition table
label string The name of the custom user data field
predefined_values string A list of optional values that appear in a dropdown list on the portal

type_id attribute definitions

type_id value Data type Example
1 string "my_string"
2 decimal 1.00
3 integer 1
4 string_choice "Monday","Tuesday","Wednesday"
5 decimal_choice 1.00, 2.00, 3.00, 4.00
6 integer_choice 1,2,3,4,5
7 date "2020-05-07"

In addition to user and CustomData objects, this search returns additional attributes. The API only returns awards attributes if you have enabled gamification.

Attribute name Type Description
awards object Contains data related to all badges awarded to the user

Awards object attributes

Attribute name Type Description
number_of_points integer How many points the user has earned in total
number_of_badges integer How many badges the user has earned in total
awards array List of badges awarded to the user: each badge has its own attributes

Awards data attributes

Attribute name Type Description
badge_id integer Unique numeric identifier of the badge
badge_name string Name of the badge
badge_count integer Number of times the user has received the badge
total_points integer Number of points the user has received with the badge points (in total, if received more than once)

This search returns a list of users in your portal who are either:

These users are available to assign to Instructor-Led Training (ILT) courses. This method provides attributes you need to search for an ILT session. See Search for ILT session

This method has no additional parameters.

Attribute name Type Description
id integer Unique numeric identifier for the user, aka user_id
email string The email address of the user: see Unique identifiers: email or username
username string Appears only if you set up username in place of email as a unique identifier. See Unique identifiers: email or username
first_name string Instructor user's first name
last_name string Instructor user's last name
instructor_pm_id integer Unique numeric identifier for the instructor in this portal membership
user_type string One of: instructor, manager+instructor

Search for custom user data fields

cURL to list custom user data fields

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/customuserdata

cURL to search for custom user data, using email attribute: searches return any custom data field definitions

curl -H GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/search?email=learnuponapi@samplelearningco.com

Sample response of custom data field definitions

"customDataFieldDefinitions":[ {"id":231,"type_id":1,"label":"department"},
{"id":640,"type_id":4,"label":"position"},{"id":2103,"type_id":6,"label":"sector"},
{"id":2101,"type_id":2,"label":"points"},{"id":2102,"type_id":5,"label":"average points"},
{"id":2100,"type_id":3,"label":"age"} ],

Sample response of custom data field values

"customDataFieldValues":[
{"definition_id":231,"value":"Support"},
{"definition_id":640,"value":["Account Manager"]},
{"definition_id":2103,"value":[3]},{"definition_id":2100,"value":34},
{"definition_id":2101,"value":60.0},{"definition_id":2102,"value":32} ],

The users/customuserdata endpoint lists the custom user data fields and their configuration details.

It doesn’t return the custom user data values for a user; it returns the definitions of the custom user data fields themselves.

This endpoint lets you determine what types of custom user data you can send and retrieve in other API calls: for example, API calls for listing, creating and updating users.

Update custom user data

cURL to update custom user data, using PUT and user_id

  curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
  '{"User": { "CustomData" : { "Department" : "Sales" }, "user_type": "learner",
  "last_name" : "TestUserLastName", "first_name" : "TestUserFirstName",
  "email" : "testuser@samplelearningco.com", "password" : "123123"}}'
  https://yourdomain.learnupon.com/api/v1/users/12345

You can send changes to custom user data in 2 different ways.

"CustomData" : { "department" : "Support", "position" : "Account Manager", "average points" : [99.9, 14.3, 49.9, 74.9] }

"CustomData" : { "use_definition_ids" : 1, "231" : "Support", "640" : "Account Manager", "2102" : [99.9, 14.3, 49.9, 74.9]}

In the code example, the CustomData object within the JSON payload specifies the custom data fields.

You can specify one or all of your fields here: the name of each field must match the name you gave your field in the portal settings. Field names are not case sensitive, and they honor spaces in the names of fields, when parsing your API requests.

You must use URL encoding for GET parameter values. For example, an email address of first+last@samplelearningco.com is URL encoded as first%2Blast@samplelearningco.com

Create a user

Some string fields for names and data have character limits. Exceeding these limits cause your POST calls to fail. See Portal: character limits of frequently-used fields in the application user documentation.

cURL to create a new user with last name, first name, email, password, language, membership type

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"User": {"last_name" : "Upon", "first_name" : "Learn", "email" : "learnuponapi@samplelearningco.com",
"password" : "password1", "language" : "en", "membership_type" : "Member" }}'
https://yourdomain.learnupon.com/api/v1/users

cURL to create a new user with manager+instructor permissions

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"User": {"last_name" : "Upon", "first_name" : "Learn", "email" : "learnuponapi@luptest.com", "password" : "password1", "language" : "en", "user_type": "manager",  "can_act_as_instructor" : "true" }}' https://yourdomain.learnupon.com/api/v1/users

Mandatory parameters for creating a user

You must provide either email address or username when creating a user, plus a password.

By default, LearnUpon uses a user's email attribute as a unique identifier throughout the LMS. See Unique identifiers: email or username.

Parameter name Type Description
email string The email address for the user: default unique identifier in LearnUpon
username string The username of the user, available as alternative to email. See Unique identifiers: email or username
password string The password for the user you are creating, 6+ characters in length

Optional parameters for creating a user

For parameters limited to manager user type, you must set the user_type to manager. For parameters limited to instructor user type, you must set the user_type to instructor.

Parameter name Type Description
last_name string The last name of the user being created
first_name string The first name of the user being created
language string The ISO language code for the user: see the appendix for a list of supported languages. If not set, then default is the portal's language
CustomData object Custom Data refers to any custom user data fields that you have created on your portals for a user
account_expires date/string The date you set the user's account to expire. Expired accounts cannot access LearnUpon. This attribute overrides enabled attribute. Required format is yyyy-mm-dd like 2024-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2024
enabled boolean If set to (default)true, indicates if the user's account is enabled. An account can remain enabled even if the account has expired: you must check the account_expires attribute, and vice versa. account_expires overrides enabled
user_type string Indicates the type of user or user privileges in the portal: one of: learner, instructor, manager, admin
can_enroll boolean Manager user type only: indicates if the user can enroll learners in courses. Default is true
can_unenroll_users boolean Manager user type only: indicates of the user can unenroll learners in courses. Default is false
can_mark_complete boolean Manager user type only: indicates if the user can manually mark complete learners on courses. Default is false
can_move_groups boolean Manager user type only: indicates if the manager can move users from one group to another. The manager must be assigned as manager for both groups. Default is false
can_act_as_instructor boolean Manager user type only: indicates if the manager has instructor permissions. Default is false
can_manage_trainings boolean Instructor user type only: indicates if the instructor can create and edit ILT modules in the ILT Center. Default is false
can_manage_sessions boolean Instructor user type only: indicates if the instructor can create and edit ILT sessions in the ILT Center. Default is false
tutor_can_edit_their_courses boolean Instructor user types only: indicates if the user can edit the courses that they instruct. Default is true
tutor_can_create_courses boolean Instructor user types only: indicates if the user can create their own courses. Default is false
change_password_on_first_login boolean If set to (default) false, does not force password change on first login
membership_type string Applicable only if you enable Associations features on your portal. Indicates the membership type of the users: Member or Non-member. Attribute options must have no spaces: use hyphens or underscores
sf_contact_id string Salesforce only: requires portal integration with Salesforce. Salesforce Contact ID: accepts either the 15 or 18 character ID
sf_user_id string Salesforce only: requires portal integration with Salesforce. Salesforce User ID: accepts either the 15 or 18 character ID

Data attributes returned after creating or updating a user

Attribute name Type Description
id integer Unique numeric identifier for the user created or updated

Update a user

cURL to update a user, identified with user_id, with last name, first name, email, password, language, membership type

curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"User": {"last_name" : "Upon", "first_name" : "Learn", "email" : "learnuponapi@samplelearningco.com",
"password" : "password1", "language" : "en", "membership_type" : "Member" }}'
https://yourdomain.learnupon.com/api/v1/users/12345

cURL to update a user, identified with user_id, with last name, first name, email, password, language, and instructor permissions for ILTs


curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"User": {"last_name" : "Upon", "first_name" : "Learn", "email" : "learnuponapi@samplelearningco.com", "password" : "password1", "language" : "en", "user_type" : "instructor", "can_manage_trainings" : "false", "can_manage_sessions" : "false" }}' https://yourdomain.learnupon.com/api/v1/users/12345

Update a user's attributes

Update the email or username, when you don't have the numeric identifier

Use the existing email or username and enter id of 0. In your payload data specify an attribute new_email (or new_username). The API finds their current email or username and sets it to the new email or username specified.

If you have the numeric id, and need to update their email or username, then use the numeric id in your PUT request on the URL, and specify the new email address or username in the email or username field.

Mandatory parameters for updating a user

You must provide either email or username when updating a user. By default, LearnUpon uses a user's email attribute as a unique identifier throughout the LMS. See Unique identifiers: email or username.

Parameter name Type Description
email string The email of the user: default unique identifier in LearnUpon
username string The username of the user, available as alternative to email. See Unique identifiers: email or username

Optional parameters for updating a user

For parameters limited to manager user type, you must set the user_type to manager.

For parameters limited to instructor user type, you must set the user_type to instructor.

You can change an account's user type through the API: for example, from learner to manager, or from admin to instructor. Changing an account's user type can change:

Parameter name Type Description
last_name string The last name of the user you are updating
first_name string The first name of the user you are updating
email string The email of the user: optional only if you set up username as unique identifier
username string Appears only if you set up username in place of email as unique identifier. See Unique identifiers: email or username
new_email string The new email address
new_username string The new username
password string The password for the user you are updating, 6+ characters in length
language string The ISO language code for the user. See the appendix for a list of supported languages. If not set, then default is the portal's language
CustomData object Custom data contains any custom user data fields that you created on your portals
account_expires date/string The date you set the user's account to expire. Expired accounts cannot access LearnUpon. This attribute overrides enabled attribute. Required format is yyyy-mm-dd, like 2024-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2024
enabled boolean If set to (default)true, indicates if the user's account is enabled. An account can remain enabled even if the account has expired: you must check the account_expires attribute, and vice versa. account_expires overrides enabled
user_type string Indicates the type of user or user privileges in the portal: is one of learner, instructor, manager, admin
can_enroll boolean Manager user type only: indicates if the user can enroll learners in courses. Default is true
can_unenroll_users boolean Manager user type only: indicates of the user can unenroll learners in courses. Default is false
can_mark_complete boolean Manager user type only: indicates if the user can manually mark complete learners on courses. Default is false
can_move_groups boolean Manager user type only: indicates if the manager can move users from one group to another. The manager must be assigned as manager for both groups. Default is false
can_act_as_instructor boolean Manager user type only: indicates if the manager has instructor permissions. Default is false
can_manage_trainings boolean Instructor user type only: indicates if the instructor can create and edit ILT modules in the ILT Center. Default is false
can_manage_sessions boolean Instructor user type only: indicates if the instructor can create and edit ILT sessions in the ILT Center, Default is false
tutor_can_edit_their_courses boolean Instructor user types only: indicates if the user can edit the courses that they instruct. Default is true
tutor_can_create_courses boolean Instructor user types only: indicates if the user can create their own courses. Default is false
membership_type string Applicable only if you enable Associations features on your portal. Indicates the membership type of the users: Member or Non-member. Attribute options must have no spaces: use hyphens or underscores
sf_contact_id string Salesforce only. Contact ID. Returns null if user record doesn’t have a Salesforce Contact ID
sf_user_id string Salesforce only. Salesforce User ID. Returns null if user record doesn’t have a Salesforce user ID

Delete a user

cURL to delete a user by user id

curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/users/12345

Mandatory data parameters for deleting a user

Attribute name Type Description
id integer Unique numeric identifier of the user to delete (12345 in the example call)

Portal invites

The portal_invite resource lets you invite a user into a portal or group. You can include user attributes such as first and last name in the API request.

When this API call is successful, LearnUpon sends an invitation to the specified user and email address. The recipient accepts the invitation by selecting the invite link in the email.

You can also invite users to join the portal using the Group Invites endpoint. The main differences between the Portal Invites and Group Invites API endpoints are:

See Group Invites for the List Group Invites and Delete Group Invites endpoints.

Methods: portal invites

Method Description of output
POST /portal_invite Invite individual users to join a portal or a group

Invite a user to a portal or group

cURL to invite individual users: one request per user


 curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"Invite": { "email": "someone@samplelearningco.com", "first_name": "Learn", "last_name": "Upon" }}' https://yourdomain.learnupon.com/api/v1/portal_invite

Mandatory data parameters for portal invite

For this resource, you must specify an email address, to send invites to users.

If you enable usernames (in place of email) as unique identifier, username is mandatory. See Unique identifiers: email or username.

Parameter name Type Description
email string The email of the user
username string The username of the user

Optional attributes for portal invite

Attribute name Type Description
first_name string The first name of the user you are inviting
last_name string The last name of the user you are inviting
expires_at date/string The date that the user's account expires. Expired accounts cannot access LearnUpon
group_id integer Unique numeric identifier for a group to add the user to, once they accept the invite
CustomData object Custom user data for the user being invited. If used, the customer defines the attributes of this object
sf_contact_id string Salesforce only. Contact ID. Returns null if user record doesn’t have a Salesforce Contact ID
sf_user_id string Salesforce only. Salesforce User ID. Returns null if user record doesn’t have a Salesforce user ID
portal_membership_type_id integer Sets the permissions for the user in the portal. Default user type is learner. Options are: 1=learner, 2=admin, 3=instructor, 4=manager

Attributes returned for portal invite

Attribute name Type Description
id integer Unique numeric identifier for the portal invite
email string Email address of the invite recipient, where LearnUpon sent the invite

Enrollments

The enrollments resource lets you:

See Delete courses as part of the courses endpoint.

For large volumes of enrollments, you can specify a selected page in the endpoint. See Data pagination.

Methods: enrollments

Method Description of output
POST /enrollments Creates an enrollment onto a course for users
GET /enrollments/{id} Searches for a user's enrollments, by enrollment id
GET /enrollments/search?user_id= Searches for a user's enrollments by user_id
GET /enrollments/search?email= Searches for a user's enrollments by email
GET /enrollments/search?username= Searches for a user's enrollments by username
GET /enrollments/search?course_name= Searches all enrollments by course_name
GET /enrollments/search?course_id= Searches all enrollments by course_id
DELETE /enrollments/{enrollment_id} Deletes enrollments for a user, by enrollment_id

Create an enrollment (enroll users on a course)

Enrolling a user requires either an email or username as unique identifier


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"Enrollment": { "email" : "learnuponapi@samplelearningco.com", "course_name" : "Hello API"}}'
https://yourdomain.learnupon.com/api/v1/enrollments

Mandatory data parameters for creating an enrollment

Every new enrollment needs a user to enroll, and a course to complete.

Parameter name Type Description
email string The email of the user
username string The username of the user
course_name string The exact title of the course, using the most recent published course title
course_id integer The unique numeric identifier for the course

Optional data parameters for enrollments

Parameter name Type Description
re_enroll_if_completed boolean Set to true to re-enroll the user on the course, if they have previously completed the course

Data attributes returned for enrollment

Attribute name Type Description
id integer Unique numeric identifier for the enrollment
created_at date/time The date the enrollment was created, in UTC format

Search for enrollments

Retrieve enrollments by enrollment_id: the identifier created when you enrolled users


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/enrollments/2757


Retrieve a user's enrollments by user_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/enrollments/search?user_id=1234

Retrieve a user's enrollments by user_id, and date attributes


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/enrollments/search?user_id=1234&date_from=2017-11-22&date_to=2017-11-22

Retrieve a user's enrollments by email


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/enrollments/search?email=learnuponapi@samplelearningco.com

Retrieve a user's enrollments by username


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/enrollments/search?username=learnupon

Retrieve enrollments associated with a course_name: returns multiple users

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c https://yourdomain.learnupon.com/api/v1/enrollments/search?course_name=Hello%20API

Retrieve enrollments associated with a course name, plus pagination to page 3

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c https://yourdomain.learnupon.com/api/v1/enrollments/search?course_name=Hello%20API&page=3

Retrieve enrollments associated with a course_id: returns multiple users

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/enrollments/search?course_id=1234

Mandatory parameters to retrieve enrollments

You must provide one of these attributes to retrieve enrollments.

Parameter name Type Description
id integer Unique numeric identifier for the enrollment, created when you enrolled users onto a course
user_id integer Unique numeric identifier for a user
course_id integer Unique numeric identifier for a course
course_name string The exact title of the course, using the most recent published course title

Optional parameters to retrieve enrollments

Parameter name Type Description
date_from date/time A start date to filter enrollment results, checking the enrollments' updated_at timestamp. Required format is YYYY-MM-DD
date_to date/time An end date to filter enrollment results, checking the enrollments' updated_at timestamp. Required format is YYYY-MM-DD

Data attributes returned by enrollment

Attribute name Type Description
id integer Unique numeric identifier for the enrollment
percentage integer The score achieved by the learner
date_started date/time The date the user started the course, in UTC format
date_completed date/time The date the user finished the course, in UTC format
date_lastaccessed date/time The date the user last accessed the course, in UTC format
date_enrolled date/time The date the user was enrolled on the course, in UTC format
course_id integer Unique numeric identifier for the course
course_name string The exact title of the course, using the most recent published course title
course_source_id integer For re-versioned courses, provides the course_id of the source course. Example: for course version 4, this field contains the course_id for version 3 (not version 1)
user_id integer Unique numeric identifier for the user enrolled
first_name string The first name of the user enrolled
last_name string The last name of the user enrolled
email string The email address of the user enrolled: LearnUpon's default identifier for users.
username string The username of the user enrolled, visible only if you implement usernames on your portal. See Unique identifiers: email or username
due_date date/time If set, the date by which the learner must complete the course, in UTC format
status string The enrollment status of the learner, one of the following statuses: not_started, in_progress, completed, passed, failed, pending_review
course_access_expires_at date/time If set, date when access to the course expires for the learner, in UTC format
certificate_name string Name of any certificate the user receives for completion
cert_expires_at date/time If set, when the the certification expires
version integer The course version
was_recertified boolean If set to true, indicates that recertification policies on your course certificate applied on this enrollment. For users who complete a course that has automatic recertification rules enabled, when they repeat the course, they are automatically recertified by LearnUpon
percentage_complete integer The number of modules the learner has completed, as a percentage of the number of modules in the course
unenrolled boolean Indicates if a user's completed course was unenrolled: enrollment is hidden from the learners' views, but appears in the course history report, in audit/learning history data
from_store boolean Indicates if the enrollment came through eCommerce. Default is false
from_catalog boolean Indicates if the enrollment came through the portal catalog. Default is false
updated_at date/time Indicates when the enrollment was last updated, in UTC format
group_id integer Displays the learner's group_id, if they belong to a group
is_overdue boolean Applicable only for courses with due dates: indicates if the course is overdue

Delete enrollments

Deleting an enrollment, aka unenrolling a user, does not delete the user or the course: it deletes the connection between the user and the course, and removes the user's access to the course.

By default, LearnUpon does not delete enrollments with a Completed status. They stay in a learner's history, and appear in reports. Use the optional parameter remove_from_history to delete all enrollments, including Completed ones.

Delete an enrollment using the enrollment_id

curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"remove_from_history" : "true"}' https://yourdomain.learnupon.com/api/v1/enrollments/12345

Mandatory parameters to delete enrollments

Parameter name Type Description
id integer Unique numeric identifier of the enrollment to delete (12345 in the example call)

Optional parameters to delete enrollments

Parameter name Type Description
remove_from_history boolean Set to true to force-delete the user's learning history, including completed enrollments.

Exams and surveys

The exams resource let you search (list):

Surveys use the same resource as exams, and use a unique exam_id identifier.

Methods: exams and surveys

Method Description of output
GET /exams/{exam_id} Searches for the settings for a specific exam module: no user data, no exam content
GET /exams/{exam_id}/questions Searches for the questions set, and the answer options, for a specific exam: no user data
GET /exams/{exam_id}/enrollments Searches for the enrollment data for all users enrolled on a specific exam
GET /exams/{exam_id}/answers/{exam_enrollment_id} Searches for the questions and the answers submitted by specific users, on a specific exam

Exam settings

Retrieve the settings, aka the metadata, for an exam module. This endpoint does not return either exam results, or user data.

For surveys, where attribute is_survey =true, this endpoint leaves out some returned attributes that aren't applicable.

Retrieve exam settings

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/exams/{exam_id}

Sample returned attributes for an exam

{
    "exam": {
        "name": "Mars exam questions",
        "is_survey": false,
        "exam_id": 110117,
        "is_timed_exam": true,
        "pass_percentage": 50,
        "pass_mark": null,
        "is_knowledge_check": false,
        "attempts": "unlimited",
        "time_for_exam": 2
    }
}

Sample returned attributes for a survey

{
    "exam": {
        "name": "Wrap up survey",
        "is_survey": true,
        "exam_id": 128471
    }
}

Exam attributes returned

Attribute name Type Description
exam_id integer Unique identifier of a specific course module. You can find this identifier using the list modules request
name string Exam name
is_survey boolean If set to true, indicates if the exam is a survey. Default is false
is_knowledge_check boolean If set to true, indicates the exam is a knowledge check. Default is false
attempts integer Exams only: number of attempts on the exam by the learner
is_timed_exam boolean Exams only: if set to true, indicates if exam is timed. Default is false
time_for_exam integer Timed exams only: amount of time allowed for the exam
pass_mark integer Exams only: passing mark for the exam
pass_percentage integer Exams only: alternate to a raw mark, provides passing percentage for the exam

Search for questions, and associated answers, from a specific exam

If your exam draws on a large question pool, this endpoint identifies which questions appeared in a specific exam, and what answers were offered.

Retrieve exam questions and answer options


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/exams/{exam_id}/questions

Questions attributes returned

These attributes list the questions, and the answer options, for a specific exam, which you identify with {exam_id}.

Attribute name Type Description
exam_id integer Unique identifier of a specific course module. You can find this identifier using the list modules request
questions object Question object containing a list of questions, for given exam. See following section for object details

Question object attributes returned

Attribute name Type Description
question_id integer Unique numeric identifier for an individual question
question_text text Wording of the question itself, which the user sees onscreen
question_type string One of: choice, feedback, rating, order list, match list or fill in the blanks
question_choice_type string Applies to choice question type: single or multiple choice
points integer Number of points for given question
answers object Answer object containing a list of available answers for a single question. See following section for answer details

Answers object attributes returned

A single question can offer multiple answers. This object provides details for each answer, associated with a question.

It appears as part of the questions object, which returns when you query the list of questions in a specific exam.

Attribute name Type Description
answer_id integer Unique numeric identifier for an individual answer
answer_text string Answer text, which the user reads onscreen
is_correct string For "choice" type questions: the correct answer. Returns 1=correct, otherwise 0
for_matching text For "match list" question: the correct answer
sequence integer Order sequence for answer
predefined_answers text For "fill in the blanks" questions: list of answers to select from
rating_options object For “rating” questions in surveys: list of options to choose from

Rating_options object attributes

Attribute name Type Description
answer_id integer Unique numeric identifier for an individual answer
text string Full text for given rating option
sequence integer Rating option sequence

Search for exam data

Find out which users completed which exam. This endpoint identifies users, and the status of their exam.

Retrieve enrollment data for all enrolled users on an exam


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/exams/{exam_id}/enrollments

Sample returned data for 1 learner on an exam

{
    "exam_enrollments": [
        {
            "exam_id": 110117,
            "exam_enrollment_id": 2590435,
            "status": "Passed",
            "time_taken": 12,
            "attempts_used": 1,
            "score": 100,
            "user_id": 123456,
            "portal_membership_id": 4567891,
            "date_completed": "2024-03-22T17:29:13Z"
        },
    ]
}

Enrollment data attributes returned

These attributes are about the users who enrolled in a specific exam.

Attribute name Type Description
exam_id integer Unique numeric identifier of a specific course module. You can find this identifier using the list modules request
exam_enrollment_id integer Unique numeric identifier for the user’s enrollment to the exam
user_id integer Unique numeric identifier for the user. Will not show for an anonymous survey
portal_membership_id integer Unique numeric identifier for user’s membership to the portal related to the exam enrollment. Will not show for an anonymous survey
status string Status of user’s enrollment on given exam
attempts_used integer Number of attempts the user has used on the exam
time_taken float Time the user spent on given exam in minutes
score integer User’s score for given exam. Will not have value for surveys
date_completed date/time Date the learner completed the exam in UTC format

Search for users' answers to exam questions, for a given exam

Find the responses learners provided to the exam questions.

Retrieve exam questions and users' answers for a given exam enrollment

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/exams/{exam_id}/answers/{exam_enrollment_id}


Sample return of exam questions and answers from 1 learner

{
    "exam_id": 159497,
    "questions": [
        {
            "question_text": "<p>How many people have walked on the moon: 4, 10, or 12?</p>\r\n",
            "question_id": 101457,
            "answers": {
                "correct_answer": [
                    "12 men, 0 women."
                ],
                "given_answer": [
                    "12 men, 0 women."
                ]
            },
            "overall_status": "correct"
    ],
    "user": "Charlotte Schleswig",
    "email": "charlotte.schleswig@yourdomain.com"
}

Data attributes returned for enrollment questions and answers

The questions object in these returned attributes lists questions, and returned answers.

Attribute name Type Description
exam_id integer Unique numeric identifier for the specific course module
user string First name and last name of enrolled user. Not shown for anonymous survey
email string User’s email. Not shown for anonymous survey
questions object Object containing the list of questions for given exam, together with user's answers

Attributes returned for questions object

Attribute name Type Description
question_id integer Unique identifier for the exam question
question_text text Wording of the question
overall_status string Overall question status: if the question is correct or not. One of: 0=not attempted, 1=correct, 2=incorrect. Not shown for surveys
answers object Object containing the list of answers the user gave. See the following section for answer details

Attributes returned for answers

Attribute name Type Description
correct_answer text For exams only: correct answer to a given question
given_answers text The answer which the user provides, to the exam question
for_matching text Match list questions only: list of items to match
for_rating text For survey rating questions: an option for the learner to rate

MarkCompletes

The markcompletes resource lets you update a learner's enrollment status manually. You can set an enrollment to complete, passed or failed without the learner completing the enrollment.

You can set the learner's status, score, date completed and any additional notes to explain the actions.

Methods: MarkCompletes

Method Description of output
GET /markcompletes Search for MarkComplete enrollments, refined with optional parameters
POST /markcompletes Create MarkComplete enrollments

Search for MarkComplete enrollments

Listing Mark Completes

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/markcompletes

Optional parameters for MarkCompletes

Parameter name Type Description
id integer Unique numeric identifier for the mark complete: you find this id when you create a MarkComplete
user_id integer Unique numeric identifier for the user in LearnUpon
enrollment_id integer Unique numeric identifier for enrollment, created when you enrolled users onto a course
course_id integer Unique numeric identifier for a course

Attributes returned for MarkCompletes

Attribute name Type Description
id integer Unique numeric identifier for the MarkComplete
created_at date/time The date this MarkComplete entry was created, in UTC format
date_completed date/time The date when the enrollment was completed by the learner. This date is distinct from created_at, when the MarkComplete was set
status string Enrollment status of the learner, one of: completed, passed, failed
percentage integer Percentage score achieved by the learner for their enrollment
user_id integer Unique numeric identifier of the user who marked the enrollment as complete. Set to NULL where the MarkComplete is created with the API
notes string Notes that you can add to explain the MarkComplete
action_source_type string Where the MarkComplete enrollment came from, one of: UI, API

Mark enrollments complete

This end point lets you record learners' past course results, offline training, exemptions, or other special circumstances.

Create MarkComplete


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"Markcomplete"
: {"enrollment_id" : "12345", "date_completed" : "2017-07-07T13:00:00Z" , "status" : "passed" ,  "percentage" : "100" }}'
 https://yourdomain.learnupon.com/api/v1/markcompletes

Mandatory parameters to create MarkComplete

Parameter name Type Description
enrollment_id integer Unique numeric identifier of the enrollment to mark complete
date_completed date/time Date when the enrollment was completed, in UTC format
status string Enrollment status of the learner, one of: completed, passed, failed
percentage integer Score achieved by the learner for their enrollment: required only if you set the status to passed or failed

Optional parameters to create MarkComplete

Parameter name Type Description
notes string 2000 character free text, for notes about the mark complete
award_certs boolean If set to true (default), awards the certificates associated with the course
award_credits boolean If set to true (default), awards the credits associated with the course
award_badges boolean If set to true (default), awards the badges associated with the course

Data attributes returned for creating MarkComplete

Attribute name Type Description
id integer Unique numeric identifier of the MarkComplete enrollment
created_at date/time Date that you created the MarkComplete, in UTC format

Courses

The courses resource lets you to search for (aka list or retrieve), create, update, delete and publish your courses. You can also clone courses within portals, and add or remove modules from your courses.

To add or remove modules, or delete a course, the course must be in a draft state.

Methods: courses

Method Description of output
GET /courses Searches for courses, narrowed with name or course_id
POST /courses Creates courses, with course name and course owner_id
POST /courses/publish Publishes a course: requires course_id
POST /courses/clone Copies a course: requires course_id of course you are cloning
POST /courses/add_module Adds a module: requires course_id and module_id
POST /courses/remove_module Removes a module: requires course_id and module_id
POST /courses/{id}/set_membership_type_prices add prices to courses based on association membership: requires course_id
PUT /courses/{id} Updates a course: requires course_id
DELETE /courses/{id} Deletes a course: requires course_id

Search for courses

List courses


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/courses

Optional parameters for searching for courses

A course_id is unique: it applies to only a single course. When you create a new course version, the course_id changes. When you search using course_id you should get only 1 result.

For a broader search of courses, use name as a parameter.

Parameter name Type Description
name string Course name or title. Use URL encoding to submit over a QueryString. Search for courses uses pattern matching, not exact matching, and are case insensitive
course_id integer Course's unique numeric identifier. Set include_draft to true, to include courses in draft status in your search
include_all_versions boolean Works with name. If set to true then the search returns all versions of your course, including archived versions. Default is false: returns only the current version
include_draft boolean If set to true then the search returns draft and published versions. Default is false: returns only published versions
include_licensed_courses boolean If set to true then search returns both courses created within the portal, and courses licensed to any associated sub-portals. Default is false: returns courses for current portal only
Attribute name Type Description
courses object An object containing the list of courses.
customDataFieldDefintions object An object containing the list of custom data field definitions. Returned only when the portal admin has defined custom user or custom course data fields.

Courses object attributes returned

In LearnUpon terminology, deleting a user from a course is the same as unenrolling a user: it does not delete the user, only their enrollment.

Attribute name Type Description
id integer Unique numeric identifier for the course
name string The title of the course
version integer The version of the course
source_id integer The source course_id for a course. When you update a course (re-version a course) the source id does not change This ID groups courses together that stem from the same root course in their version tree
created_at date/time Date/time when the course was created, in UTC format
sellable boolean If set to true, indicates the course is published to the store: default is false.
cataloged boolean If set to true, indicates if the course is published to the catalog: default is false
date_published date/time Date/time when the course was published, in UTC format
keywords string Keywords you provide, to help users find your course in the catalog or the store
reference_code string A customer reference code, to help you find your courses in the library in search, and use in reports: not generated by LearnUpon
manager_can_enroll boolean If set to true, indicates the manager can enroll their group members on this course: default is false
allow_users_rate_course boolean If set to (default)true, indicates learners can rate this course
number_of_reviews integer Number of reviews/ratings recorded for this course: use in combination with number_of_stars to calculate an average rating
number_of_stars integer Number of stars awarded to the course: use in combination with number_of_reviews to calculate an average rating
minute_length float The course length, if specified, that appears in your store or catalog
course_length_unit string The length unit for your course: hours or minutes
num_enrolled integer Number of learners currently enrolled
num_not_started integer Number of learners who have not started the course
num_in_progress integer Number of learners who are currently in progress
num_completed integer Number of learners who have completed the course
num_passed integer Number of learners who have passed the course
num_failed integer Number of learners who have failed the course
num_pending_review integer Number of learners who have submitted all of their assignments for their course
number_of_modules integer Number of modules in this course
price integer Price in cents for your course
published_status_id string The current published status of the course: one of published, draft, archived or under_revision
difficulty_level string The difficulty level set on your course: one of not_applicable, basic, intermediate or advanced
description_html string Course description, with full HTML markup
description_text string Course description, raw text
objectives_html string Course objectives, with full HTML markup
objectives_text string Course objectives, raw text
credits_to_be_awarded string Comma-separated list of credits the learner earns by completing or passing the course. Example: "CEU:2.00,CPE:3.00"
due_days_after_enrollment integer The number of days after enrollment, when the learner is due to complete the course
due_date_after_enrollment date/time The date/time, when this course is due for completion, in UTC format
send_due_date_reminders boolean If set to true, indicates that due date reminders are enabled on this course: default is false
due_date_reminder_days integer For the first reminder LearnUpon sends: number of days before the course is due for completion
due_date_reminder_days_2 integer For the second reminder LearnUpon sends: number of days before the course is due for completion
thumbnail_image_url string Public URL of the course thumbnail image: returns null if the course has no thumbnail
license_expires date/time Licensed course only: the date/time the course license expires, in UTC format, returns null if the license is open ended
license_number_enrollments_purchased integer Licensed course only: the number of enrollments purchased for the license, returns null if the license is unlimited
license_is_open_ended boolean Licensed course only: indicates if the license is open ended (never expires), default is false
license_has_unlimited_enrollments boolean Licensed course only: indicates if the license has an unlimited number of enrollments available, default is false
owner_first_name string The first name of the course owner
owner_last_name string The last name of the course owner
owner_email string The email address of the course owner
owner_id integer Unique numeric identifier for the course owner: portal administrator, or instructor with course creation privileges
learning_awards object Gamification only: requires query by course_id, and contains gamification related data
customDataFieldValues object An object containing the list of custom data field definitions. Returned only when the portal admin has defined custom course data fields

customDataFieldValues object attributes for courses

Attribute name Type Description
value string, decimal, integer, string_choice, decimal_choice, integer_choice or date Contains the custom course data value. This data type matches the type defined in customDataFieldDefintions, type_id attribute. Date requires YYYY-MM-DD format
definition_id integer A unique identifier for the custom course data field

Data attributes returned for custom course data

Attribute name Type Description
customDataFieldDefintions object An object containing the list of custom data fields

customDataFieldDefintions object definitions for courses

Attribute name Type Description
id integer Unique numeric identifier for the custom course data field
type_id integer A numeric value identifying the custom course data field type: see the following type_id definition table
label string The name of the custom course data field
predefined_values string A list of optional values that appear in a dropdown list on the portal

type_id attribute definitions

type_id value Data type Example
1 string "my_string"
2 decimal 1.00
3 integer 1
4 string_choice "Monday","Tuesday","Wednesday"
5 decimal_choice 1.00, 2.00, 3.00, 4.00
6 integer_choice 1,2,3,4,5
7 date "2020-05-07"

learning_awards object attributes

Attribute name Type Description
badge_id integer Unique numeric identifier of the badge
badge_name string Name of the badge
award_on string Details on criteria to award the badge: for example, learner receives a badge based on 60% score or "completion" of the course

Create a course

Some string fields for names and descriptions have character limits. Exceeding these limits cause your POST calls to fail. See Portal: character limits of frequently-used fields in the application user documentation.

Create course


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"Course": {"name" : "Course name", "owner_id" : 123123}}' https://yourdomain.learnupon.com/api/v1/courses

Mandatory parameters to create courses

Parameter name Type Description
name string Name of the new course
owner_id integer Unique numeric identifier for the course owner: portal administrator, or instructor with course creation privileges

Optional create course parameters

Parameter name Type Description
description string Course description: can include HTML markup
objectives string Course objectives: can include HTML markup
keywords string Search keywords for your store or catalog
reference_code string A customer reference code, to help you find your courses in the library in search, and use in reports: not generated by LearnUpon
allow_users_rate_course boolean If set to (default) true, allows your users to rate/review this course
review_is_mandatory boolean If set to true, rating the course with feedback is mandatory: default is false
difficulty_level integer 0=Not Applicable (default), 1=Basic, 2=Intermediate, 3=Advanced. Set your course difficulty level for store or catalog views
minute_length float Specified course length for your store or catalog views
course_length_unit integer Unit for course length: set to (default) 0 for minutes, 1 for hours
enable_sequencing boolean If set to (default) false, course modules are not sequenced, true is sequenced
disable_message_author boolean If set to (default) false, learners can message the instructor. true= no messages allowed
manager_can_enroll boolean If set to (default) false, managers cannot enroll team members in a course, true allows managers to enroll
allow_relaunch_after_completion boolean If set to (default) true, allows users to view or launch this course after completion, pass or fail. false= no relaunch allowed
days_after_enrollment integer Allow learners to access this course up to a certain number of days after they were enrolled
date_after_enrollment date/time Allow learners to access this course up to and including a specific date in the future, in the mm/dd/yyyy format. LearnUpon uses midnight (UTC) on the date specified. If you work in a different timezone, account for time difference when you set the expiry date
send_completion_email integer 0=Never (default) 1=When course is completed or passed, 2=when course is completed, passed or failed
send_completion_reminders boolean If set to true, LearnUpon sends users automated email reminders, that they have not yet completed, passed or failed the course: default is false
completion_reminder_days integer Number of days after enrollment when LearnUpon sends a first reminder
completion_reminder_days_2 integer Number of days after enrollment when LearnUpon sends a second reminder
completion_reminder_days_3 integer Number of days after enrollment when LearnUpon sends a third reminder
completion_reminder_days_4 integer Number of days after enrollment when LearnUpon sends a fourth reminder
custom_enroll string This text appears in the enrollment email to the user, if you add this field to your custom templates
custom_reminder string This text appears in the reminder emails to the user, if you add this field to your custom templates
custom_completion string This text appears in the course completion email to the user, if you add this field to your custom templates
custom_purchase string This text appears in the purchase email to the user, if you have add this field to your custom templates
sellable boolean If set to (default) false, course is not sellable on your store, true = sellable course
price float Course price value: set to 0.00 for free courses
apply_sales_tax boolean If set to (default) true, sales tax is applied to the course
cataloged boolean Set to true to list the course in the catalog: default is false
pass_mark integer Determines a pass or fail. For courses with more than one "exam" or "scoring" module, LearnUpon averages the learners' overall course score: a pass is ≥ pass mark
email_on_feedback_or_reivew boolean If set to true, LearnUpon automatically sends an email to the course owner when a learner submits feedback or reviews this course: default is false
bypass_sequencing_on_assignments boolean On sequenced courses, when a learner submits an assignment, the assignment enters a pending review state. The learner cannot progress until the instructor reviews the assignment (completing the module). Set to (default) true, to bypass sequencing rules, and let the learner continue on their course while the instructor reviews their submitted assignments
award_credits_per_session boolean If set to true, each session on your course awards the number of credits set out. Example: if you award 5 credits on your course, then by completing the course and attending 2 sessions, your learners receive 2x5=10 credits total. Default is false, where credits are awarded per course only
send_ical_reminders boolean ILT courses only: if set to true, LearnUpon sends users an email reminding them of their ILT session details, with an iCal attachment. Default is false
ical_reminder_days integer Number of days before session begins when LearnUpon sends the first reminder
ical_reminder_days_2 integer Number of days before session begins when LearnUpon sends the second reminder
due_days_after_enrollment integer The number of days after enrollment, when the learner is due to complete the course
due_date_after_enrollment time/date The date when this course is due for completion by the learner once enrolled.in the mm/dd/yyyy format. LearnUpon uses midnight (UTC) on the date specified. If you work in a different timezone, account for time difference when you set the expiry date
send_due_date_reminders boolean If set to true, enables automated due date reminders: default is false
due_date_reminder_days integer Number of days before the course is due for completion: controls the when a due date reminder email goes to the user
due_date_reminder_days_2 integer Number of days before the course is due for completion

Data attributes returned for creating a course

Attribute name Type Description
id integer Unique numeric identifier for a course

Publish courses

Courses must be in draft state to publish.

Publish Course


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{ "course_id" : 123123}' https://yourdomain.learnupon.com/api/v1/courses/publish

Mandatory parameters to publish a course

Parameter name Type Description
course_id integer Unique numeric identifer of the course you are publishing

Optional parameters to publish a course

For re-versioning and publishing existing courses: these parameters decide what happens to users who are enrolled in the course, depending on their status.

Parameter name Type Description
not_started_logic integer Controls whether to move users enrolled on the previous version of the course, and currently in Not Started status, to the new version of the course 1=Move not started enrollments to new version 2=(Default) Leave not started enrollments on the old version
in_progress_logic integer Controls whether to move users enrolled on the previous version of the course, and in "In Progress" status, to the version of the course. 1=Move "In progress" enrollments to the latest version of the course 2=(Default) Leave In progress enrollments on the previous version of course
lp_logic integer Controls whether the course being published replaces the previous version of the course on any learning paths 1=Replace the current version of the course, 2=(Default) Leave the current version of the course on the learning path

Data attributes returned for publishing a course

Attribute name Type Description
id integer Unique numeric identifier for a published course

Clone (copy) course

The API offers the same course copying options as the LearnUpon interface. You can clone a course:

In a setting with multiple sub-portals from 1 top-level portal, you can't clone courses between sub-portals.

Cloning a course a single time generates a global unique identifier guid, and a message to allow time to let the cloning process finish. Use the guid to make additional clones.

The guid tracks the cloning process, and prevents the process from throttling with unintentional clone requests. If you try to clone a course to a location where a clone already exists, you get an error message, reminding you to use guid in the API call.

Clone (copy) a course to another portal, with response


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"clone_to_portal_id" : "5127", "course_id" : "12364", "publish_after_clone" : "true"}'
 https://yourdomain.learnupon.com/api/v1/courses/clone

 {
     "guid": "9ezjl8Ig_J9WeZEcN6RBTw",
     "message": "Course cloning in progress. Please allow approximately 5 minutes for the process to complete. If you wish to clone this course again within the same portal, include the provided GUID as a param during additional API calls."
 }

Clone a course to same location more than once, using guid


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"clone_to_portal_id" : "5127", "course_id" : "12364"}'  
 https://yourdomain.learnupon.com/api/v1/courses/clone?guid=9ezjl8Ig_J9WeZEcN6RBTw

Mandatory parameters to copy a course

Parameter name Type Description
course_id integer Unique numeric identifier of the course you are cloning

Optional parameters to copy a course

Parameter name Type Description
clone_to_portal_id integer Unique numeric identifier of the destination portal for the cloned course. If this parameter is not provided, the course is cloned to the main portal (the portal that the API is being called for)
publish_after_clone boolean If set to true, sets the newly cloned course to published status: default is false, course remains in draft status
owner_id integer Include a user's unique numeric identifier, to make them the course owner of the newly cloned course

Attributes returned from course cloning

Attribute name Type Description
guid string A Global Unique Identifier (guid) for your cloned course. When cloning the same course multiple times within the same portal, you must include guid in the URL.
message string Course cloning in progress. Please allow approximately 5 minutes for the process to complete. If you wish to clone this course again within the same portal, include the provided GUID as a param during additional API calls.

Add a module to a course

A course must be in draft status, to add a module to it. LearnUpon will reject duplicate modules.

You can only add shareable modules such as pages, including text & image modules, video and audio modules, with this endpoint. You cannot add exams, assignments or ILT sessions using this endpoint.

After you add a module, you need to run a /courses/publish call to re-publish your course.

Add module to an existing course


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{ "course_id" : 123123, "module_id" : 123456}' https://yourdomain.learnupon.com/api/v1/courses/add_module

Mandatory parameters for adding a module

Parameter name Type Description
course_id integer Unique numeric identifier of the course
module_id integer Unique numeric identifier of the module you are adding to the course

Remove module from a course

A course must be in the draft state in order to remove a module.

After you remove a module, you need to run a /courses/publish call to re-publish your course.

Remove module from a course


curl  -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{ "course_id" : 123123, "module_id" : 123456}' https://yourdomain.learnupon.com/api/v1/courses/remove_module

Mandatory parameters for removing a module

Parameter name Type Description
course_id integer Unique numeric identifier of the course
module_id integer Unique numeric identifier of the module you are removing from the course

Add course prices based on association memberships

To set different prices for courses for different portal members, you need to turn on the Assocations and membership types feature at the portal level. See LearnUpon Knowledge Base articles about associations for background.

Set prices for individual courses using membership types. This call requires the ID for membership types. See: Search for association membership types in a portal.

Add course prices by membership type

curl  -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{ "membership_pricing": [{"id": 510, "price": 120}, {"id": 511, "price": 240}]}' https://yourdomain.learnupon.com/api/v1/courses/345678/set_membership_type_prices

Confirmation of course price change

{
    "message": "Successfully updated pricing"
}

Mandatory parameters to add prices to courses

Parameter name Type Description
course_id integer Unique numeric identifier for the course. Find this value from GET /courses endpoint. See: Search for courses
membership_type_id integer Unique numeric identifier for the membership type. Find this value from GET /portals/membership_types endpoint. See: Search for association membership types in a portal

Update courses

Updates to courses are changes to existing modules, like fixing typos, or correcting a link. They do not prompt re-versions on publishing.

Update Courses

curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"Course": {"name" : "Updated course name"}}' https://yourdomain.learnupon.com/api/v1/courses/123123

Mandatory parameters to update courses

Parameter name Type Description
id integer Unique numeric identifier for the course you are updating

Optional parameters to update a course

The optional parameters for updating a course are the same as for creating a course endpoint, with addition of the following:

Parameter name Type Description
name string Name of the new course
owner_id integer Unique numeric identifier for the course owner: portal administrator, or instructor with course creation privileges

Delete courses

Delete a course

curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/courses/12345

You can't delete a course when any learners are enrolled on it. You need to unenroll learners first, before deleting the course. Suggested sequence:

Mandatory parameters to delete a course

Parameter name Type Description
id integer Unique numeric identifier for the course you are deleting (12345 in the example call)

Modules

Modules are the "chunks" of content that make up a course in LearnUpon.

The modules resource lets you:

See ILT Center: overview and features in LearnUpon's Knowledge Base to learn more.

If you use legacy ILT (instructor-led training) modules within a course, or you don't use ILT modules at all, the module id remains unique for each module in your course.

Methods: modules

Method Description of output
GET /modules Searches for all modules on your portal
GET /modules?course_id= Searches for modules, within a specific course
POST /modules Publish audio and video modules
POST /modules/clone Copies a module from one course to another

Search for modules

You can search for all modules, or narrow the search with a course_id.

Listing modules linked to a single course

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/modules?course_id=12531

Optional parameters for modules

Parameter name Type Description
course_id integer Unique numeric identifier for a LearnUpon course

Data attributes for modules returned

Attribute name Type Description
id integer Numeric identifier for the module. One module_id can be associated with multiple training_id and session_id for an ILT Center module
title string Module title or name
tags string (CSV) A comma-separated list of tags for this module, to help users find courses. Can be empty, 1 tag, or a CSV list of tags. Example: "sales,finance,support"
created_at date/time Date/time when the module was created, in UTC format
updated_at date/time Date/time when the module was updated, in UTC format
exam_id integer Unique identifier for the exam associated with this module. Can be null
sequence integer Sets the order that the modules appear in the course
number_of_linked_courses integer Number of courses that contain this module
component_type string Type of module, one of: page, assignment, ilt session, exam, tincan, scorm, unknkown
description_html text Module description, with full HTML markup
description_text text Module description, plain text
creator_id integer Unique numeric identifier of the user who created this module
creator_first_name string First name of the user who created this module
creator_last_name string Last name of the user who created this module
creator_email string Email of the user who created this module
creator_username string Username of the user who created this module: appears only if your portal uses usernames. See Unique identifiers: email or usernames
assignment_passing_percentage integer Assignment module: the passing score for this assignment
assignment_question_html string Assignment module: HTML version of the assignment question text
assignment_question_text string Assignment module: text version of the assignment question text
location_id integer ILT: if the session has a location specified, this field holds a unique numeric identifier for that location
location string ILT: if the session has a location specified, this field holds the name of that location
address_1 string ILT: location address field 1
address_2 string ILT: location address field 2
address_3 string ILT: location address field 3
location_state_code string ILT: location state code
location_country_code string ILT: country code, ex: "IE" for Ireland, "US" for United States, "GB" for Great Britain
start_at date/time ILT: UTC starting date/time for ILT session
end_at date/time ILT: UTC ending date/time for ILT session
timezone string ILT: timezone of the ILT location (either the location timezone, if a location is set, or the specified timezone for a webinar session without a location)
number_enrolled_on_session integer ILT: number of learners enrolled
max_capacity integer ILT: max number of learners who can enroll
session_tutor_id integer ILT: unique identifier of the tutor user for the session. Where multiple tutors are available, the API returns only the first tutor listed
tutor_first_name string ILT: First name of the tutor
tutor_last_name string ILT: Last name of the tutor
tutor_email string ILT: Email of the tutor
tutor_username string ILT: Username of the tutor: appears only if your portal uses usernames. See Unique identifiers: email or usernames
training_id integer ILT Center: Numeric identifier for the ILT Center module. One training_id can be associated with many session_id. Value can be null, for sessions not created through the ILT Center
session_id integer ILT Center: Unique numeric identifier for an individual ILT Center session. Value can be null, for sessions not created through the ILT Center

Add a video or audio module

Create Module with audio or video


curl -X POST -H "Content-Type: application/json" --user 93a306ad8fff2fe3dbd1:d670237770e52266234ecd45678bce -d
'{"module_title":"Api video module", "video_url" : "https://url_to_the_video" }'
https://yourdomain.learnupon.com/api/v1/modules

Mandatory audio or video module parameters

Parameter name Type Description
module_title string Title of the new module
video_url string Fully qualified URL to the video file you are adding to this module
audio_url string Fully qualified URL to the audio file you are adding to this module

Optional audio or video module parameters

Parameter name Type Description
tags string A comma-separated list of tags to apply to this module, to help users find the module. Example: "sales,HR,required"

Data attributes returned for adding a video or audio module

Attribute name Type Description
id integer Unique numeric identifier of the newly created module

Clone (copy) modules

Clone a module from one course to another within a portal. The target course, where you are adding the module, must be in draft state.

Cloning a module a single time does not generate a guid: the API does not return any attributes.

When you clone the same module a second time, you get a response which includes a guid. Use the guid to make additional clones.

The guid tracks the cloning process, and prevents the process from throttling with unintentional clone requests.

The successful multiple cloning does not return new attributes.

Clone (copy) a module, first attempt


curl -X POST -H "Content-Type: application/json" --user 93a306ad8fff2fe3dbd1:d670237770e52266234ecd45678bce -d
'{"source_course_id":"12345", "target_course_id": "67890", "module_id": "87654" }'
https://yourdomain.learnupon.com/api/v1/modules/clone

Clone a module, second attempt: returned value

{"response_type":"ERROR","response_code":400,"message":"Warning: course already copied to this location, if you want to do it again add '?guid=bIDh29Hd5o_r1UDq-Jvx7g' to the end of the api call"}

Clone a module to same course more than once, using guid

curl -X POST -H "Content-Type: application/json" --user 93a306ad8fff2fe3dbd1:d670237770e52266234ecd45678bce -d
'{"source_course_id":"12345", "target_course_id": "67890", "module_id": "87654" }'
https://yourdomain.learnupon.com/api/v1/modules/clone?guid=bIDh29Hd5o_r1UDq-Jvx7g

Mandatory parameters to clone a module

Parameter name Type Description
source_course_id integer The course_id for the course containing the module you're copying
target_course_id integer The course_id for the target course, where you are adding a module
module_id integer Unique numeric identifier of the module you are adding to the course

Attributes returned from module cloning

Attribute name Type Description
guid string A Global Unique Identifier (guid) for your cloned module. This value is returned after a second attempt to clone a module.

Resources

Resources are files you provide for learners outside of a course. Learners can access resources even after the course is complete. You share resources with learners either through the LearnUpon library, or through a direct link.

The /resources endpoint lets you:

You can't create or edit resources from the API. You create resources by uploading them to the portal, through the LearnUpon application.

In the sub-portal, admins can change Show on resource tab to show or hide the resource, as required for their business needs.

To change the Show on resource tab setting in the top-level portal and share this change in the sub-portal, you need to delete and re-create the resource link using the API.

Removing a resource link from a sub-portal - for example, to re-create it - resets the counter that tracks the number of downloads in that sub-portal.

Methods: Resources

Method Description of output
GET /resources Searches for and returns all resources within a portal.
POST /resources/{id}/link Link a resource from the top level portal to a sub portal. Requires ?link_to_portal_id={id} included in POST command.
DELETE /resources/{id}/link Removes a linked resource from a sub portal. Requires ?linked_portal_id={id} included in DELETE command for a sub portal.

Use GET /portals methods to find portal IDs. See Search for a portal.

Sample search and response for resources on a portal


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/resources

{
    "learner_resources": [
        {
            "id": 10292,
            "title": "Self Leadership",
            "description": "<p><strong>You Can't Change the World, You can Only Change Yourself</strong></p>\n\n<p>To get what you want, develop yourself.</p>\n\n<p>This is a short tutorial to help you overcome the usual obstacles that get in the way of developing yourself, be they, time, money or resources. Developing yourself is one of the best investments you can make in your health, wealth and happiness.</p>\n",
            "file_name": "Self Leadership Definition.docx",
            "file_size": 13639,
            "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "is_visible": true
        }
    ]
}

Attribute name Type Description
id integer Unique identifier of a specific resource
title string Resource name
description string Resource description, with full HTML markup
file_name string The uploaded file name
file_size integer The uploaded file size, in KB
content_type string The content format for the uploaded file
is_visible boolean Default is false. This setting determines if the resource is available to learners

Sample call to link a resource from a top-level portal to a sub-level portal


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"link_to_portal_id": 12871}'
https://yourdomain.learnupon.com/api/v1/resources/{id}/link

Create a link between a resource that you created in the top-level portal to one of the sub-level portals. The resource becomes available in the sub-level portal.

Use GET /portals methods to find portal IDs. See Search for a portal.

Parameter name Type Description
id integer Unique identifier for the resource, retrieved by searching the top-level portal
link_to_portal_id integer The portal id of the destination sub-portal for the resource

Sample call to remove a resource from a sub-level portal


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"linked_portal_id": 12871}'
https://yourdomain.learnupon.com/api/v1/resources/{id}/link

Remove a resource from a sub-portal

You can remove a linked resource from a sub-portal by deleting the link.

This step doesn't delete the resource in the top-level portal: it deletes the link between the resource and the sub-portal.

Use GET /portals methods to find portal IDs. See Search for a portal.

Mandatory parameters to remove a linked resource

Parameter name Type Description
id integer Unique identifier for the resource, retrieved by searching the top-level portal
linked_portal_id integer The portal id of the sub-portal, where you're removing the link

Instructor-led training Center

See ILT Center: overview and features in LearnUpon's Knowledge Base to learn more.

In the ILT Center, the modules for training provide containers to hold sessions, and metadata that applies to all sessions. You set the following parameters at the module level:

For waitlist_status, and minimum_attendance_threshold: you must turn on these features in the portal before you can set these parameters for training modules.

You set the minimum attendance threshold in the training module, and it applies to each associated session. Optionally, you can overwrite the threshold at the session level, or turn it off, for multi-day sessions, aka sessions that run 24+ hours. This change doesn't affect the training module's parameters, or other sessions in the training. You can't overwrite the threshold for single-day sessions, aka sessions less than 24 hours long.

Within the training module, you create unlimited number of sessions.

For ILT Center, you set the following parameters at the session level for the session format:

Identifier options for ILT Center calls

Training owners

Each training module requires at least 1 owner. Multiple owners are allowed.

You identify training owners by one of: ID, email or username. If you provide multiple values for owners - for example, by listing both a user_id and a username - LearnUpon prioritizes the identifiers in the following order:

  1. owner_user_ids
  2. owner_emails
  3. owner_usernames: available if your portal has usernames as unique identifiers. See Unique identifiers: email or username

Session instructors

Multiple instructors are allowed for each session. You designate 1 instructor as primary instructor: their name goes into notifications, so learners get reminders about sessions from a single person. If you do not include an instructor name, the owner is named as instructor by default.

You identify session instructors by one of: ID, email or username.

If you provide multiple values for training instructors - for example, both a user_id and a username - LearnUpon prioritizes the identifiers in the following order:

  1. instructor_user_ids
  2. instructor_emails
  3. instructor_usernames: available if your portal has usernames as unique identifiers. See Unique identifiers: email or username

You identify a primary instructor by one of ID, by email or by username. This person's name goes into notifications to learners.

If you provide multiple values for training instructors - for example, both a user_id and a username - LearnUpon prioritizes the identifiers in the following order:

  1. primary_instructor_user_id
  2. primary_instructor_user_email
  3. primary_instructor_username: available if your portal has usernames as unique identifiers. See Unique identifiers: email or username

Session attendees, aka learners

You identify learners by one of: ID, email or username. If you provide multiple values for training instructors - for example, both a user_id and a username - LearnUpon prioritizes the identifiers in the following order:

  1. user_id
  2. email
  3. username: available if your portal has usernames as unique identifiers. See Unique identifiers: email or username

Permissions for ILT Center owners and instructors

Training owners require user type permissions to create and edit training.

Session instructors require user type permissions to lead sessions.

See Create a user and Update a user about creating accounts with specific user type permissions.

See LearnUpon's Knowledge Base Collection: user types and permissions about user type permissions associated with ILTs.

Methods: ILT Center

Method Description of output
GET /ilts/search?course_id= Searches by course_id
GET /ilts/search?location_id= In person: searches by location_id
GET /ilts/search?instructor_pm_id= Searches by instructor_pm_id
GET /ilts/search?course_status= Searches by course_status
GET /ilts/search?start_date= Searches by start_date
GET /ilts/search?end_date= Searches by end_date
GET /ilts/search?training_id= Searches by ILT Center training_id
GET /locations Searches for the course locations available in your portal
GET /timezones Searches for the timezones available in your portal
GET /webinar_connections Searches for the webinar integrations available in your portal
GET /webinars/?webinar_connection_id= Searches for a specific webinar
GET /trainings/{training_id}/sessions/{session_id} Search for the details for a specific session, including webinar URL
GET /sessions/{session_id}/attendance Lists attendance for a specific ILT Center session
POST /trainings/ Creates an ILT Center module, aka training
POST /trainings/{training_id}/sessions Creates an ILT Center session associated with a training module
POST /sessions/{session_id}/add_to_session Adds a learner to a specific ILT session and, if not already enrolled, to a course
POST /trainings/{training_id}/sessions/{session_id}/mark_attendance Marks attendance for a specific ILT Center session
POST /trainings/{training_id}/sessions/{session_id}/cancel_registration Cancels a learner's registration to a specific ILT Center session
PUT /trainings/{training_id} Updates an ILT Center module, aka training
PUT /trainings/{training_id}/sessions/{session_id} Updates an ILT Center session
Method Description of output
GET /modules See Methods: modules
POST /courses/add_module See Courses: add a module to a course
POST /courses/remove_module See Courses: remove module from a course

Search for ILT Center modules and sessions

Searches with GET /ilt/search only return modules:

These search methods return the ILT Center modules only: they don't return full course details. For a list of all modules in a course see Search for modules.

Search for ILT Center content, using course_id


 curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c GET 'https://yourdomain.learnupon.com/api/v1/ilts/search?course_id=2587242'

Search for ILT Center content, using instructor_pm_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?instructor_pm_id=291215

Search for ILT Center content, using using course_status of 1, 2, 3


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?course_status=1

Search for ILT Center content, using location_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?location_id=2256 

Search for ILT Center content, using start date and end date together


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?start_date=2023-10-01&end_date=2023-10-10

Search for ILT Center content, using training_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?training_id=359415 

Parameter name Type Description
course_id integer Unique numeric identifier for a LearnUpon course. Find this value from GET /courses endpoint. See: Search for courses
start_date string Start date of session to search for, in yyyy-mm-dd format
end_date string End date of session to search for, in yyyy-mm-dd format
instructor_pm_id integer portal membership ID of an ILT instructor. Find this value from GET /users/instructor_users endpoint See: Data attributes returned from instructor_users search
course_status integer One of: 1=published, 2=under revision, 3=archived
location_id integer Classroom only. Find this id from the GET /locations endpoint: see Search for locations
training_id integer Unique identifier for the ILT Center training module. See Create an ILT Center module

Data attributes returned for search for ILT Center modules and sessions

Attribute name Type Description
course_id integer Unique identifier for the course
course_name string Course name
session_enrollment_type integer Legacy ILT only: not in use for ILT Center
component_title string Title of the ILT Center module
description string Description of the ILT Center module
start_date string Start date of the session, requires yyyy-mm-ddThh:m:s format
end_date string End date of the session, requires yyyy-mm-ddThh:m:s format
created_at string Date the session was created, requires yyyy-mm-ddThh:m:s format
max_capacity integer Maximum number of attendees on this ILT Center session
instructor_name string Session instructor name. Where multiple instructors are available, the API returns only the first instructor listed
location_id integer Optional: unique numeric identifier of location that is set on session. Can be null for online sessions
location_title string Location title. Can be null for online sessions
timezone string Timezone of the session
session_type string One of: classroom, webinar
webinar_connection_name string Webinar connection name. Can be null for session URLs added manually
webinar_title string (Optional) Webinar title. Can be N/A for session URLs added manually
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
session_id integer Unique numeric identifier for an individual ILT Center session. This ID is part of the session URL
number_of_attendees integer Number of attendees registered for a specific session
session_title string Title of a specific session, that can be different from the module title

Sample search for locations for ILT Center sessions


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/locations

Search for locations for ILT Center sessions

This method returns the list of locations available in your portal. ILT Session Locations is an optional course setting, for in-person training. To add a location to your ILT session in the API call, you need the location 'id` provided by this call.

This method has no additional parameters.

Attribute name Type Description
id integer Unique numeric identifier for the location
title string Name of the location of the ILT session
address1 string First line of physical address
address2 string Second line of physical address
address3 string Third line of physical address
timezone string Refers to UTC time zone
country_code string country code, ex: "IE" for Ireland, "US" for United States, "GB" for Great Britain
notes string Free text field for details about the location

Sample search for timezones for ILT Center sessions


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/timezones

Search for timezones for ILT Center sessions

This method returns a list of timezones available in your portal.

This method has no additional parameters.

Attribute name Type Description
id string Unique identifier for the session timezone
name string Description which appears in the application

Sample search for ILT Center webinar connections


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/webinar_connections

Search for webinar connections

This method returns a list of of the supported 3rd party integrations available in your portal, which provide webinar services for the ILT Center. Each integration gets a unique webinar connections id on your portal. To add a webinar session to your ILT, you need the webinar_connection id provided by this call.

This method has no additional parameters.

For how-tos on setting up 3rd party integrations see the LearnUpon Knowledge Base: Add webinar tools.

Attribute name Type Description
id string Unique identifier for the webinar connection
name string Description of the 3rd party webinar provider
has_default_password boolean Default is false. This setting depends on your 3rd party integration

Sample search for webinars with a given webinar_connection_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/webinars?webinar_connection_id=679 

Search for webinars

This method returns the all the webinars in your portal which use a specific webinar_connection_id.

For example: if you enter a query with the webinar_connection_id for Zoom, the API returns all the webinars which use the Zoom integration in your portal. This same search does not show you webinars that use other integrations in your portal.

Search for ILT Center session details

This method returns the details of a specific session. For classroom sessions, it returns location details, if available. For webinar sessions, it returns the URL to access the webinar.

The training_id and session_id forms part of the URL for this endpoint.

cURL to search for an ILT Center session

curl -X GET -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c 
https://yourdomain.learnupon.com/api/v1/trainings/12345/sessions/11111

Response to search for a specific session

{
{"session":{"id":390349,"portal_id":45678,"training_id":12345,"title":"APIs made easy part 3","description_html":"<p>Stop worrying and love APIs</p>","description_text":"Stop worrying and love APIs","num_enrolled":0,"min_capacity":null,"max_capacity":null,"start_time":"2023-11-14T16:00:00","end_time":"2023-11-14T17:00:00","timezone":"(GMT-05:00) Eastern Time (US & Canada)","session_type":"webinar","location":"Webinar","webinar_url":"https://us02web.zoom.us/j/00000000000?pwd=passwordprovidedbyzoom","completion_requirement":"attendance required", "minimum_attendance_threshold":null,"instructors":[{"pm_id":987654,"user_id":654321,"first_name":"Berengar","last_name":"Hesse","email":"berengar.hesse@yourdomain.com","is_primary":true},{"pm_id":222222,"user_id":123456,"first_name":"Beatrice","last_name":"Dansk","email":"beatrice.dansk@yourdomain.com","is_primary":false}]}}
}

Mandatory parameters for searching for an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
session_id integer Unique numeric identifier for an individual ILT Center session. Find this value from one of the GET /ilts/search? calls. See: Search for ILT Center session

Data attributes returned for search for ILT Center session

Attribute name Type Description
id integer Unique numeric identifier for an individual ILT Center session. This ID is part of the session URL
portal_id integer Unique identifier for the portal where the session exists
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
title string Title of the ILT Center session
description_html string Description of the ILT Center session in HTML
description_text string Description of the ILT Center session in plain text
num_enrolled integer Number of enrolled learners on the session
start_time string Start time of the session, in yyyy-mm-ddThh:m:s format
end_time string End date of the session, in yyyy-mm-ddThh:m:s format
timezone string Timezone of the session. Start and end time are displayed in this timezone. Example: (GMT+1:00) Belgrade
session_type string One of: classroom, webinar
min_capacity integer Minimum number of attendees on this ILT Center session. Advisory only
max_capacity integer Maximum number of attendees on this ILT Center session
completion_requirement string One of attendance optional or attendance required
minimum_attendance_threshold integer A percentage of the session the learner must attend, set in the associated training. Applies only if minimum attendance is turned on at the portal level
instructors object An array containing instructor details
location string Title of the location. Returns webinar for all online sessions, and N/A if no location is selected
webinar_url string URL for accessing a specific session: either a webinar URL, or custom URl
location_id integer Unique numeric identifier for the location. Returns -1 if location is not selected
address1 string First line of physical address. Empty if no location is selected
address2 string Second line of physical address. Empty if no location is selected
address3 string Third line of physical address. Empty if no location is selected

Instructor object attributes

Attribute name Type Description
user_id integer user_id of the instructor
pm_id integer Portal membership ID of the given instructor
is_primary boolean Indicates the primary instructor on the session
first_name string Instructor’s first name
last_name string Instructor’s last name
email string email for the instructor
username string username for the instructor. Available if your portal has usernames as unique identifiers

See Unique identifiers: email or username.

Search for an ILT Center session attendance

After searching for an ILT Center session, you can look up attendance by learners using the returned session_id. The array returns an attendance record for each user, for each session they attend.

Sample search and response for a session's attendance record using the session_id


curl -X GET -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/sessions/123456/attendance

[
    [{"pm_id":111111,"user_id":222222,"session_status":20,"attendance_data":[{"part":333333,"status":10,"minutes":null}],"enrollment_data":[{"enrollment_id":44444444,"course":5555555,"enrollment_status":2,"from_catalog":false,"from_store":false}]}]
]

Mandatory parameter to retrieve attendance

Parameter name Type Description
session_id integer ILT Center: Unique numeric identifier for an individual ILT Center session

Data attributes returned for ILT Center session attendance

Attribute name Type Description
pm_id integer Portal membership ID
user_id integer Unique numeric identifier for a learner attending a session
session_status integer Learner’s enrollment status for the session, 1 of: -10=not_registered, 10=not_started, 20=completed, 30=failed, 40=no_show
attendance_data array List of attendance data for a specific ILT Center session
enrollment_data array List of enrollment data for a specific ILT Center session

attendance_data attributes

Attribute name Type Description
part integer A unique identifier for sessions, for future API development.
status integer Learner’s attendance status for the session, 1 of: 0=unmarked, 5=absent, 10=present
minutes integer Number of minutes for the session

enrollment_data attributes

Attribute name Type Description
enrollment_id integer Unique numeric identifier for a learner’s enrollment, created when you enroll users onto a course
course integer Unique identifier for the published course that contains this ILT Center session
enrollment_status integer See the following enrollment_status definition table
from_catalog string Indicates if the enrollment was generated by enrolling via the catalog or not. Default is false
from_store string Indicates if the enrollment was created by purchasing on the store (paid or free purchase). Default is false

enrollment_status attribute definitions

enrollment_status value Description
-4 waitlisted
-3 partially_attended
-2 cancelled
-1 no_show
1 not_started
2 in_progress
3 completed
4 passed
5 failed
6 pending_review
7 closed
8 past_due

Create an ILT Center module, aka a training

Every training module requires a title and at least 1 owner. Multiple owners are permitted.

For waitlist_status, and minimum_attendance_threshold: you must turn on these features in the portal before you can set these parameters for training modules.

See Identifier options for ILT Center calls for background.

cURL create a new ILT Center module, with response


curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{ "training": {"title" :  "APIs made easy", "owner_user_ids": 123456, "waitlist_status": 1}
}'
https://yourdomain.learnupon.com/api/v1/trainings

{
    "message": "success",
    "training_id": 456789
}

Mandatory parameter for creating an ILT Center module

Parameter name Type Description
training object An object containing the training parameters

Mandatory training object parameters

For identifiers: use one of user ID, email or username.

Parameter name Type Description
title string Title of the training module
owner_user_ids array (integer) user_ids of the training owner(s)
owner_emails array (string) email of the training owner(s)
owner_usernames array (string) username of the training owner(s), available as alternative to email

Optional training object parameters

See ILT Center: overview and features to learn about individual features.

For identifiers: use one of user ID, email or username.

Parameter name Type Description
instructor_user_ids array (integer) user_ids of the named training instructor(s)
instructor_emails array (string) email of the training instructor(s)
instructor_usernames array(string) usernames of the training instructor(s), available as an alternative to email
waitlist_status integer Shows waitlist option is on or off. 0=Disabled (default), 1 =Enabled
description string Training description
completion_requirement integer Training completion requirements: 0=No requirements, 1=Join the session (default), 2=Minimum attendance threshold
minimum_attendance_threshold integer A percentage of the session the learner must attend. Applies only if completion_requirement=2 (Minimum attendance threshold)
additional_attendance_option integer Applies only if completion_requirement=1 (Join the session) or =2 (Minimum attendance threshold). Available options: 0=register on another session (default), 1=do not pass training
session_registration_choice integer Available options: 0=automatic, 1=manual (default)
learner_can_choose_session boolean If set to true learners can self enroll. Default is false
learner_can_cancel_registration boolean If set to true learners can cancel registrations to chosen sessions. Default is false
enabled_notifications array (string) Notifications to owners, instructors and learners. Include the notification in the array to enable: owner_session_scheduled, owner_training_added, instructor_assigned_to_session, instructor_session_updated, instructor_session_canceled, instructor_session_capacity_reached, learner_training_assigned, learner_session_registration, learner_session_updated, learner_session_canceled, learner_cancel_registration, instructor_training_reminder, learner_training_reminder
instructor_reminder_prior_session_days integer Sets the number of days before a session when LearnUpon sends an automated reminder to the instructor. Applies only if enabled_notifications contains instructor_training_reminder
learner_reminder_prior_session_days integer Sets the number of days before a session when LearnUpon sends an automated reminder to the learners. Applies only if enabled_notifications contains learner_training_reminder

Data attributes returned after creating an ILT Center module

Attribute name Type Description
id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL

Update an ILT Center module, aka a training

Update an existing training module from the ILT Center.

Make sure the training retains at least 1 owner, identified by ID, email or username. See Identifier options for ILT Center calls for background.

For waitlist_status, and minimum_attendance_threshold: you must turn on these features in the portal before you can set these parameters for training modules.

cURL update an ILT Center module, with response


curl -X PUT -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{ "training": {"title" :  "APIs made easy", "owner_user_ids": 123456, "waitlist_status": 1}
}'
https://yourdomain.learnupon.com/api/v1/trainings/567890

{
    "message": "success",
    "training_id": 567890
}

Mandatory parameters for updating an ILT Center module

Parameter name Type Description
id integer Unique numeric identifier for the training module
training object An object containing the training parameters

Object parameters to update

For identifiers: use one of user ID, email or username.

Parameter name Type Description
title string Title of the training module
owner_user_ids array (integer) user_ids of the training owner(s)
owner_emails array (string) email of the training owner(s)
owner_usernames array (string) username of the training owner(s), available as alternative to email
instructor_user_ids array (integer) user_ids of the named training instructor(s)
instructor_emails array (string) email of the training instructor(s)
instructor_usernames array(string) usernames of the training instructor(s), available as an alternative to email
waitlist_status integer Shows waitlist option is on or off. 0=Disabled (default), 1 =Enabled
description string Training description
completion_requirement integer Training completion requirements: 0=No requirements, 1=Join the session (default), 2=Minimum attendance threshold
minimum_attendance_threshold integer A percentage of the session the learner must attend. Applies only if completion_requirement=2 (Minimum attendance threshold)
additional_attendance_option integer Applies only if completion_requirement=1 (Join the session), or =2 (Minimum attendance threshold). Available options: 0=register on another session (default), 1=do not pass training
session_registration_choice integer Available options: 0=automatic, 1=manual (default)
learner_can_choose_session boolean If set to true learners can self enroll. Default is false
learner_can_cancel_registration boolean If set to true learners can cancel registrations to chosen sessions. Default is false
enabled_notifications array (string) Notifications to owners, instructors and learners. Include the notification in the array to enable: owner_session_scheduled, owner_training_added, instructor_assigned_to_session, instructor_session_updated, instructor_session_canceled, instructor_session_capacity_reached, learner_training_assigned, learner_session_registration, learner_session_updated, learner_session_canceled, learner_cancel_registration, instructor_training_reminder, learner_training_reminder
instructor_reminder_prior_session_days integer Sets the number of days before a session when LearnUpon sends an automated reminder to the instructor. Applies only if enabled_notifications contains instructor_training_reminder
learner_reminder_prior_session_days integer Sets the number of days before a session when LearnUpon sends an automated reminder to the learners. Applies only if enabled_notifications contains learner_training_reminder

Data attributes returned after updating an ILT Center module

Attribute name Type Description
id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL

Create an ILT Center session

Sessions take place within an ILT Center module, aka a training module.

Every session requires:

Multiple instructors are permitted. You must indicate the primary instructor, whose name goes into the notifications. The primary instructor must be one of the instructors named for the session.

Training owners require user type permissions to create and edit training.

Session instructors require user type permissions to lead sessions.

See Create a user and Update a user about creating accounts with specific user type permissions.

See LearnUpon's Knowledge Base Collection: user types and permissions.

cURL to create a new ILT Center session, with confirmation


curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{ "session": {"title" : "Advanced APIs, part 1", "start_time": "2023-11-04T09:00:00", "end_time": "2023-11-05T09:00:00", "timezone_id": "Eastern Time (US & Canada)", "instructor_user_ids": [111111, 222222], "primary_instructor_user_id":222222 }
}'
https://yourdomain.learnupon.com/api/v1/trainings/361212/sessions 

Response returned for creating a session

{
    "message": "success",
    "session_id": 389843
}

Mandatory parameters for creating an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids
session object An object containing the session parameters

Mandatory session object parameters

For identifiers: use one of user ID, email or username. See Identifier options for ILT Center calls for background.

For timezone_id use GET /timezone: See Search for timezones.

Parameter name Type Description
title string Title of the training session
instructor_user_ids array (integer) user_id of the session instructor(s)
instructor_user_emails array (string) email addresses of the session instructor(s)
instructor_user_emails array (string) username of the session instructor(s), available as alternative to email
primary_instructor_user_id integer user_id of the primary instructor
primary_instructor_email string email address of the primary instructor
primary_instructor_username string username of the primary instructor
start_time date/time The date/time when this ILT session starts, in UTC format
end_time date/time The date/time when this ILT ends, in UTC format
timezone_id string Session timezone. Required for webinar sessions. For in-person sessions the API uses location_id if available to provide a timezone

Optional session object parameters

Parameter name Type Description
location_id integer ID of the session location. If you don't include it, and there is no custom_webinar_url and webinar_connection_id, session is marked as classroom without applicable location
custom_webinar_url string Custom webinar URL string: if present, session is marked as webinar
webinar_connection_id integer ID of an existing webinar account, used for this session. This parameter marks the session as webinar
minimum_attendance_threshold integer Sets an attendance threshold for an individual session, and overrides minimum_attendance_threshold set in the associated training. Requires minimum attendance enabled on the training module. Set to 0 to turn off minimum attendance for an individual session
description string Session’s description
min_capacity integer Minumum session capacity
max_capacity integer Maximum session capacity

Data attributes returned for creating a session

Attribute name Type Description
id integer Unique numeric identifier for the session

Update an ILT Center session

Sessions take place within an ILT Center module, aka a training module.

Update the parameters for a session.

cURL to update an ILT Center session


curl -X PUT -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{ "session": {"title" : "Advanced APIs, part 1", "start_time": "2023-11-04T09:00:00", "end_time": "2023-11-05T09:00:00", "timezone_id": "Eastern Time (US & Canada)", "instructor_user_ids": [111111, 222222], "primary_instructor_user_id":222222 }
}'
https://yourdomain.learnupon.com/api/v1/trainings/361212/sessions/389843 

Response returned for updating a session

{
    "message": "success",
    "session_id": 389843
}

Mandatory parameters for updating an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids
session_id integer Unique identifier for the session
session object An object containing the session parameters

Session object parameters to update

For identifiers: use one of user ID, email or username. See Identifier options for ILT Center calls for background.

For example: To add an instructor, list the current instructors' identifiers and add the new instructor identifier to the list.

See additional sources of parameters:

Not currently editable:

Parameter name Type Description
title string Title of the training session
instructor_user_ids array (integer) user_id of the session instructor(s)
instructor_user_emails array (string) email addresses of the session instructor(s)
instructor_user_emails array (string) username of the session instructor(s), available as alternative to email
primary_instructor_user_id integer user_id of the primary instructor
primary_instructor_email string email address of the primary instructor
primary_instructor_username string username of the primary instructor
start_time date/time The date/time when this ILT session starts, in UTC format
end_time date/time The date/time when this ILT ends, in UTC format
timezone_id string Session timezone. Required for webinar sessions. For in-person sessions the API uses location_id if available to provide a timezone
location_id integer ID of the session location. To remove a location, enter -1
custom_webinar_url string Custom webinar URL string: if present, session is marked as webinar
minimum_attendance_threshold integer Sets an attendance threshold for an individual session, and overrides minimum_attendance_threshold set in the associated training. Requires minimum attendance enabled on the training module. Set to 0 to turn off minimum attendance for an individual session
description string Session’s description
min_capacity integer Minumum session capacity
max_capacity integer Maximum session capacity

Data attributes returned for updating a session

Attribute name Type Description
id integer Unique numeric identifier for the existing session

Add a user to an ILT Center session

This method adds a user to an ILT Center session associated with a specific course. If required, it creates a course enrollment at the same time.

You can add users to both past and future sessions.

The endpoint requires:

For identifiers: use one of user ID, email or username. See Identifier options for ILT Center calls for background.

The session_id forms part of the URL for this call.

cURL Add a user by user_id to a session and create a course enrollment

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"course_id":1614047,
"user_id": 291154}'
https://yourdomain.learnupon.com/api/v1/sessions/200039/add_to_session

cURL Add a user by username to a session and create a course enrollment

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"course_id":1614047,
"username": "jane.doe"}'
https://yourdomain.learnupon.com/api/v1/sessions/200039/add_to_session

cURL Add a user by email to a session and create a course enrollment

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"course_id":1614047,
"email": "jane.doe@yourdomain.com"}'
https://yourdomain.learnupon.com/api/v1/sessions/200039/add_to_session

cURL response for adding a user (any identifier) to a session and creating a course enrollment

{
    "message": "success",
    "enrollment_id": 16310845
}

Requirements to add users to sessions

To add users to ILT Center sessions:

This call does not apply to training that registers users automatically to the first session available.

See ILT Center: overview and features for background about the ILT Center and its features.

You can include a ILT Center module in several courses, with as many sessions as required. As a result, you can enroll users in a training module through more than one course.

This endpoint handles scenarios to make sure that you can add users to available sessions wherever possible, and the call does not affect any existing registrations.

For users not enrolled in the specific course, the endpoint generates the following results:

For users already enrolled in the specific course, the endpoint generates the following results:

This method requires several pieces of data returned by other calls.

Mandatory parameters for adding a user to an ILT Center session

Requires one of user_id or username to identify the learner

Parameter name Type Description
user_id integer Unique numeric identifier for a user. Find this value from one of the GET /users/search? calls. See: Search for users
email string Optional unique identifier for a user
username string Unique identifier for a user, available if you set up your portal with usernames
course_id integer Unique numeric identifier for a course. Find this value from GET /courses call. See: Search for courses
session_id integer Unique numeric identifier for an individual ILT Center session. Find this value from one of the GET /ilts/search? calls. See: Search for ILT Center session

Data attributes returned by adding a user to an ILT Center session

Attribute name Type Description
enrollment_id integer Unique numeric identifier for enrollment, created when you enroll users onto a course. See: Enrollments

Data returned for adding a user to an ILT Center session

HTTP code Message Description
200 success API call was successful
404 Invalid parameters Customer sent invalid parameters
400 Not authorised for that course or course not found Course was not found: the course is deleted, or the customer does not have permissions for that course
400 Not valid session on portal or on course The session was not found for that specific course or training: typically it was cancelled or deleted
400 Failed to find the user specified The user was not found, to add to the session
400 User already registered on session for that training When the user is already registered on a different session for the training
400 There was a problem with the session Some other problem with session: for example, invalid date, session capacity reached, session cancelled
400 There was a problem in enrollment creation Problem in enrollment creation for user when adding them to session, not related to the session
400 Can not add user to session because training has automatic registration for the first available session The training has Automatic registration for the first available session set: adding a user by API isn’t available

Mark attendance for an ILT Center session

This method marks attendance for users for a specific ILT Center session. It does not refer to a course, only the training and session that the user attended.

The training_id and session_id forms part of the URL for this endpoint.

To identify attendees, use one of user_id, email, or username. See Identifier options for ILT Center calls for background.

cURL to mark attendance for an ILT Center session

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"attendance": [{"email": "user1@yourcompany.com", "completion_status": 5}, {"email": "user2@yourcompany.com", "completion_status": 10, "duration": 42}]}' 
https://yourdomain.learnupon.com/api/v1/trainings/123/sessions/223/mark_attendance

Response to mark attendance endpoint

{
    "message": "success"
}

Mandatory parameters for marking attendance for an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
session_id integer Unique numeric identifier for an individual ILT Center session. Find this value from one of the GET /ilts/search? calls. See: Search for ILT Center session
attendance object Object that contains parameters related to users' attendance

Mandatory attendance object parameters

Parameter name Type Description
user_id integer Unique numeric identifier for a user
email string Email address for attendee on the session
username string Available if your portal has usernames as unique identifiers. See Unique identifiers: email or username
completion_status integer Completion status for specific attendee: one of 5=absent, 10=present
duration integer Minutes of attendance. Mandatory if a session’s completion_requirement=2 (Minimum attendance threshold), and completion _status=10(present). Valid values are from 0 to 1400

Cancel a learner's registration to an ILT Center session

This endpoint cancels a user's registration for a session in the ILT Center. This action doesn't cancel the session or the training activity: it does remove the connection between the learner and the session. The learner remains enrolled in the course associated with the training.

The training_id and session_id forms part of the URL for this endpoint.

To identify attendees use one of user_id, email, or username. See Identifier options for ILT Center calls for background.

Cancel a learner's registration for an ILT Center session

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d ' {"user_id": 123123}'
https://yourdomain.learnupon.com/api/v1/trainings/111/sessions/123/cancel_registration

Response to cancellation

{
    "message": "success"
}

Mandatory parameters for cancelling for an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
session_id integer Unique numeric identifier for an individual ILT Center session. Find this value from one of the GET /ilts/search? calls. See: Search for ILT Center session
user_id integer Unique numeric identifier for a user
email string Email address for attendee on the session
username string Available if your portal has usernames as unique identifiers. See Unique identifiers: email or username

Cancel an ILT Center session

This endpoint cancels an ILT Center session, in the future or in the past. This action doesn't cancel training activity or affect course enrollments: it removes the session from the training module. Any learners registered for the session move to the Unregistered learners list. See LearnUpon's Knowledge Base ILT Center: overview and features and associated articles for background.

The training_id and session_id form part of the URL for this endpoint.

cURL to cancel an ILT Center session

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/trainings/111/sessions/123/cancel

Response to cancellation

{
    "message": "success"
}

Mandatory parameters for cancelling for an ILT Center session

Parameter name Type Description
training_id integer Numeric identifier for the ILT Center module. One training_id can be associated with many session_ids. This ID is part of the training URL
session_id integer Unique numeric identifier for an individual ILT Center session. Find this value from one of the GET /ilts/search? calls. See: Search for ILT Center session

Legacy Instructor-led training (ILTs)

See ILT Center: overview and features in LearnUpon's Knowledge Base to learn more.

Legacy ILTs are a module type within a course to run training sessions led by an instructor, either:

For online sessions, you add connection details for a webinar, using a 3rd-party application like Zoom, GoToMeeting, or Cisco WebEx or Microsoft Teams. Your courses can include a single ILT module, or you can create a course with multiple ILTs.

The ILT resource lets you search for (aka list or retrieve) and create legacy ILT sessions for your courses. The resource has multiple parts:

The generic calls search for:

This resource also uses:

See the webinar integrations available in LearnUpon's Knowledge Base: Add webinar tools

Methods for legacy ILTs

Method Description of output
GET /ilts/search?course_id= Searches for ILTs by course_id
GET /ilts/search?location_id= Searches for ILTs by location_id
GET /ilts/search?instructor_pm_id= Searches for ILTs by instructor_pm_id
GET /ilts/search?start_date= Searches for ILTs by start_date
GET /ilts/search?end_date= Searches for ILTs by end_date
GET /ilts/search?course_status= Searches for ILTs by course_status
GET /locations Searches for the course locations available in your portal
GET /timezones Searches for the timezones available in your portal
GET /webinar_connections Searches for the webinar integrations available in your portal
GET /webinars/?webinar_connection_id= Searches for a specific webinar
POST /components/ilt Creates a legacy ILT session

GET /modules returns legacy ILT modules. See Methods: modules.

Search for a legacy ILT session

Use one of the following parameters to search for legacy ILT modules and sessions.

Sample search for legacy ILTs, using course_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?course_id=48122


{"ilts":[{"course_id":48122,"course_name":"LearnUpon University online","session_enrollment_type":2,"component_title":"LearnUpon University online Dublin morning session","description":"<p>Unlock the power of learning with LearnUpon LMS</p>\r\n","start_date":"2021-01-19 09:00:00 UTC","end_date":"2021-01-19 22:00:00 UTC","max_capacity":200,"instructor_name":"Charles Martel","location_id":null,"location_title":null,"timezone":"UTC","session_type":"Webinar","webinar_display_name":"Zoom (support.webinar@yourcompany.com)",{"course_id":48122,"course_name":"LearnUpon University online","session_enrollment_type":2,"component_title":"LearnUpon University online, Philly afternoon session","description":"<p>Unlock the power of learning with LearnUpon LMS</p>\r\n","start_date":"2021-01-23 13:00:00 UTC","end_date":"2021-01-23 14:00:00 UTC","max_capacity":200,"instructor_name":"Charles Martel","location_id":null,"location_title":null,"timezone":"Dublin","session_type":"Webinar","webinar_display_name":"Zoom (support.webinar@yourcompany.com)","webinar_title":null}]}

Sample search for ILTs, using start date and end date together


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?start_date=2021-01-01&end_date=2021-01-10

{"ilts":[{"course_id":48122,"course_name":"LearnUpon University online","session_enrollment_type":2,"component_title":"LearnUpon University online Toronto afternoon session","description":"<p>Unlock the power of learning with LearnUpon LMS</p>\r\n","start_date":"2021-01-07 19:00:00 UTC","end_date":"2021-01-07 20:00:00 UTC","max_capacity":200,"instructor_name":"Charles Martel","location_id":2255,"location_title":"Toronto office","timezone":"Eastern Time (US & Canada)","session_type":"Session","webinar_display_name":null,"webinar_title":"N/A"},{"course_id":42790,"course_name":"Using the API to create users for LearnUpon","session_enrollment_type":2,"component_title":"Using the API to upload users for LearnUpon","description":"<p>Learn how to use the API to upload users in LearnUpon.</p>\r\n","start_date":"2021-01-04 12:00:00 UTC","end_date":"2021-01-04 14:00:00 UTC","max_capacity":5,"instructor_name":"Berengar Hesse","location_id":2254,"location_title":"Dublin office","timezone":"Dublin","session_type":"Session","webinar_display_name":null,"webinar_title":"N/A"}]}

Sample search for legacy ILTs, using instructor_pm_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?instructor_pm_id=1475833

{"ilts":[{"course_id":42790,"course_name":"Using the API to create users for LearnUpon","session_enrollment_type":2,"component_title":"Using the API to upload users for LearnUpon","description":"<p>Learn how to use the API to upload users in LearnUpon.</p>\r\n","start_date":"2021-01-04 12:00:00 UTC","end_date":"2021-01-04 14:00:00 UTC","max_capacity":5,"instructor_name":"Berengar Hesse","location_id":2254,"location_title":"Dublin office","timezone":"Dublin","session_type":"Session","webinar_display_name":null,"webinar_title":"N/A"}]}


Sample search for legacy ILTs, using using course_status: must be one of 1, 2, 3


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?course_status=1

{"ilts":[{"course_id":48122,"course_name":"LearnUpon University online","session_enrollment_type":2,"component_title":"LearnUpon University online Toronto midmorning session","description":"<p>Unlock the power of learning with LearnUpon LMS</p>\r\n","start_date":"2021-01-18 16:00:00 UTC","end_date":"2021-01-18 17:00:00 UTC","max_capacity":200,"instructor_name":"Charles Martel","location_id":2255,"location_title":"Toronto office","timezone":"Eastern Time (US & Canada)","session_type":"Session","webinar_display_name":null,"webinar_title":"N/A"}]}

Sample search for legacy ILTs, using location_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/ilts/search?location_id=2256

{"ilts":[{"course_id":48122,"course_name":"LearnUpon University online","session_enrollment_type":2,"component_title":"LearnUpon University online early afternoon Vancouver session","description":"<p>Unlock the power of learning with LearnUpon LMS</p>\r\n","start_date":"2021-01-20 21:00:00 UTC","end_date":"2021-01-20 22:00:00 UTC","max_capacity":200,"instructor_name":"Berengar Hesse","location_id":2256,"location_title":"Vancouver office","timezone":"Pacific Time (US & Canada)","session_type":"Session","webinar_display_name":null,"webinar_title":"N/A"}]}

Parameter name Type Description
course_id integer Unique numeric identifier for a LearnUpon course. Find this value from GET /courses call. See: Search for courses
start_date string Start date of session to search for, in yyyy-mm-dd format
end_date string End date of session to search for, in yyyy-mm-dd format
instructor_pm_id integer Unique numeric identifier for portal membership id of instructor. Find this value from GET /users/instructor_users call. See: Data attributes returned from instructor_users search
course_status integer One of: 1=published, 2=under revision, 3=archived
location_id integer Classroom only. Find this id from the GET /locations call: see Search for locations
Attribute name Type Description
course_id integer Unique identifier for the course
course_name string Course name
session_enrollment_type integer One of: 0=Enroll learners on all sessions, 1=Learners can choose only 1 session to attend, 2=Learners can choose multiple sessions to attend
component_title string Component title is the title of the ILT module
description string Description of the legacy ILT session
start_date string Start date of the session, requires yyyy-mm-ddThh:m:s format
end_date string End date of the session, requires yyyy-mm-ddThh:m:s format
created_at string Date the session was created, requires yyyy-mm-ddThh:m:s format
max_capacity integer Maximum number of attendees on this ILT session
instructor_name string Session instructor name. Where multiple tutors are available, the API returns only the first tutor listed
location_id integer Optional: unique numeric identifier of location that is set on session. Can be null for online sessions
location_title string Location title. Can be null for online sessions
timezone string Timezone of the session
session_type string One of: classroom, webinar
webinar_connection_name string Webinar connection name. Can be null for session URLs added manually
webinar_title string (Optional) Webinar title. Can be N/A for session URLs added manually

Sample search and response for locations

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/locations


{"locations":[{"id":2254,"title":"Dublin office","address_1":"Ocean House","address_2":"Smithfield","address_3":"D7","timezone":"Dublin","country_code":"IE","notes":"Virtual classroom accessible via Zoom."},{"id":2259,"title":"Belgrade office","address_1":"Grawe Building","address_2":"Bul. Mihajila Pupina 115E","address_3":"11070 Belgrade","timezone":"Belgrade","country_code":"RS","notes":"Conference rooms available for large meetings."},{"id":2260,"title":"Philadelphia office","address_1":"Cast Iron Building","address_2":"718 Arch Street","address_3":"Philadelphia 19106","timezone":"Eastern Time (US & Canada)","country_code":"US","notes":"2 blocks from 8th and Market interchange, 3 blocks from Jefferson Station."}]}

Search for locations

This method returns the list of locations available in your portal. ILT Session Locations is an optional course setting, for classroom training. To add a location to your legacy ILT module in the API call, you need the location id provided by this call.

This method has no additional parameters.

Attribute name Type Description
id integer Unique numeric identifier for the location
title string Name of the location of the ILT
address1 string First line of physical address
address2 string Second line of physical address
address3 string Third line of physical address
timezone string Refers to UTC time zone
country_code string country code, ex: "IE" for Ireland, "US" for United States, "GB" for Great Britain
notes string Free text field for details about the location

Sample search and response for timezones: timezone response is excerpt only

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/timezones

{"timezones":[{"id":"Pacific Time (US & Canada)","name":"(GMT-08:00) Pacific Time (US & Canada)"},{"id":"Tijuana","name":"(GMT-08:00) Tijuana"},{"id":"Mountain Time (US & Canada)","name":"(GMT-07:00) Mountain Time (US & Canada)"},{"id":"Central America","name":"(GMT-06:00) Central America"},{"id":"Central Time (US & Canada)","name":"(GMT-06:00) Central Time (US & Canada)"},{"id":"Guadalajara","name":"(GMT-06:00) Guadalajara"},{"id":"Mexico City","name":"(GMT-06:00) Mexico City"},{"id":"Monterrey","name":"(GMT-06:00) Monterrey"},{"id":"Saskatchewan","name":"(GMT-06:00) Saskatchewan"},{"id":"Bogota","name":"(GMT-05:00) Bogota"},{"id":"Eastern Time (US & Canada)","name":"(GMT-05:00) Eastern Time (US & Canada)"},{"id":"Lima","name":"(GMT-05:00) Lima"},{"id":"Quito","name":"(GMT-05:00) Quito"},{"id":"Atlantic Time (Canada)","name":"(GMT-04:00) Atlantic Time (Canada)"}]}

Search for timezones

This method returns a list of timezones available in your portal. To add a timezone to your ILT module, you need the timezone id provided by this call.

This method has no additional parameters.

Attribute name Type Description
id string Unique identifier for the timezone
name string Description which appears in the application

Sample search and response for webinar connections

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/webinar_connections

{"webinar_connections":[{"id":679,"name":"Zoom (zoom.webinar@yourcompany.com)","has_default_password":false}]}

Search for webinar connections

This method returns a list of of the supported 3rd party integrations available in your portal, which provide webinar services, like Zoom, Adobe Connect and WebEx. Each integration gets a unique webinar connections id on your portal. To add a webinar session to your ILT, you need the webinar_connection_id provided by this call.

This method has no additional parameters.

For how-tos on setting up 3rd party integrations see the LearnUpon Knowledge Base: Add webinar tools.

Attribute name Type Description
id string Unique identifier for the webinar connection
name string Description of the 3rd party webinar provider
has_default_password boolean Default is false. This setting depends on your 3rd party integration. WebEx and Adobe Connect offer default password settings, when you add the integration to LearnUpon.

Sample search and response for webinars with a given webinar_connection_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/webinars?webinar_connection_id=679

{"webinars":[{"id":"1964468268","title":"Zoom 1" },{"id":"1964442145","title":"Zoom 2"},{"id": "1963989527","title":"Zoom 3"}]}

Sample error message for search for a webinar_connection_id for MS Teams

curl -X GET -H  "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c https://yourdomain.learnupon.com/api/v1/webinars?webinar_connection_id=678

{"response_type":"ERROR","response_code":400,"message":"This endpoint is currently not supported for MS Teams accounts"}

Search for webinars

This method returns the all the webinars in your portal which use a specific webinar_connection_id.

For example: if you enter a query with the webinar_connection_id for WebEx, the API returns all the webinars which use the WebEx integration in your portal. This same search does not show you webinars which use Zoom or Adobe Connect in your portal.

Parameter name Type Description
webinar_connection_id integer Unique identifier for the 3rd party webinar provider on your portal
Attribute name Type Description
id integer Unique numeric identifier for the webinar
title string Name of the webinar in the ILT

Create a legacy ILT session

This method requires several pieces of data returned by other calls.

Creating a legacy ILT session, classroom session_type

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c


{
    "course_id": 48122,
    "component": {
        "session_type": "classroom",
        "title": "LearnUpon University  Hawaii session",
        "description": "<p>Unlock the power of learning with LearnUpon LMS</p>\r\n",
        "tags": "Classroom, LearnUpon,",
        "timezone_id": "Hawaii",
        "location_id": 2345,
        "start_at": "2020-12-29T09:00:00",
        "end_at": "2020-12-29T09:10:00",
        "max_capacity": 25
    }
}
https://yourdomain.learnupon.com/api/v1/components/ilt

Content returned for creating a legacy ILT session, classroom session type

{
    "id": 105
}

Creating a legacy ILT session, webinar session_type, for Zoom integration, zoom_type webinar


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
{
    "course_id": 48122,
    "component": {
        "session_type": "webinar",
        "title": "LearnUpon University  Hawaii session",
        "description": "<p>Unlock the power of learning with LearnUpon LMS</p>\r\n",
        "tags": "Classroom, LearnUpon,",
        "timezone_id": "Hawaii",
        "location_id": 2345,
        "start_at": "2020-12-29T09:00:00",
        "end_at": "2020-12-29T09:10:00",
        "max_capacity": 25
    }
    "webinar":{
        "webinar_id": "_new_webinar",
        "webinar_connection_id": 679,
        "new_webinar_data":{
            "use_default_password": false,
            "password": "Test2021!",
            "title": "LU Hawaii over Zoom",
            "zoom_type": "webinar"
        }
    }
}
https://yourdomain.learnupon.com/api/v1/components/ilt

Content returned for creating a legacy ILT session, webinar session type, Zoom integration, zoom type webinar

{
    "id": 106
}

Creating a legacy ILT session, webinar session_type, with an existing WebEx webinar_id, default password

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c

{
    "course_id": 48122,
    "component": {
        "session_type": "webinar",
        "title": "Webinar ILT existing webinar test",
        "description": "This is the existing ILT session description",
        "course_instructor_id": 24093,
        "tags": "webinar, new-webinar",
        "timezone_id": "London",
        "start_at": "2020-12-31T09:00:00",
        "end_at": "2020-12-31T09:15:00",
        "max_capacity": 30
    },
    "webinar":{
        "webinar_id": "1263042514",
        "webinar_connection_id": 789
    }
}
https://yourdomain.learnupon.com/api/v1/components/ilt


Content returned for creating a legacy ILT session, webinar session_type, with an existing WebEx webinar_id, default password

{
    "id": 103
}

Legacy ILT: mandatory parameters for all sessions

Parameter name Type Description
course_id integer Unique numeric identifier for a LearnUpon course
component object Data required to create an ILT session

Legacy ILT: mandatory parameters for webinars only

Parameter name Type Description
webinar object Data required to create a webinar within an ILT

Legacy ILT: component mandatory parameters

Parameter name Type Description
session_type string One of classroom, webinar
description string ILT description, visible to users
title string Title of the ILT session
timezone_id string Find this id from the GET /timezones call: see Search for timezones
start_at date/time The date/time when this ILT starts, in UTC format, YYYY-MM-DDTHH:MM:SS. Example: 2024-04-11T09:30:00
end_at date/time The date/time when this ILT ends, in UTC format
max_capacity integer Max number of learners who can enroll: cannot be empty

Legacy ILT: component optional parameters for ILT sessions

Parameter name Type Description
location_id integer Classroom only. Find this id from the GET /locations call: see Search for locations
tags string A comma-separated list of tags for this module, to help users find courses. Can be empty, 1 tag, or a CSV list of tags. Example: "sales,finance,support"
course_instructor_id integer Course instructor id: find this id from GET /course_instructors?course_id=: see Search for CourseInstructors

Legacy ILT: webinar mandatory parameters

new_webinar_data is required only if you are creating a new webinar, rather than using an existing webinar_id for your session.

Parameter name Type Description
webinar_id string Webinar only: either _new_webinar OR an existing webinar_id. Find webinar_ids, returned by the GET /webinars/?webinar_connection_id= call: see Search for webinars
webinar_connection_id string Webinar only: specific webinar (integration) id. Find this id from the GET /webinar_connections call: see Search for webinar connections
new_webinar_data object New webinars only: data required to create a new webinar session

Create legacy ILT: mandatory new webinar parameters

These parameters are required to create a new webinar using a 3rd party integration.

Parameter name Type Description
use_default_password boolean Default is false. Set to true for WebEx and Adobe, and if has_default_password=true in your 3rd party integration: see Search for webinar connections . Set to false for other integrations
title string Title of the webinar, shown on the webinar integration
password string If use_default_password=false, password is mandatory. Can be empty
zoom_type string Zoom integration only: one of meeting or webinar. Cannot be empty

Data attributes returned by create legacy ILT

Attribute name Type Description
id integer Unique numeric identifier for the ILT session

Groups

Groups in LearnUpon give you a means to invite and enroll multiple users together: make groups like Engineering, Marketing, or to reflect your business locations, like Dublin and Philadelphia.

The groups resource lets you search (aka list, retrieve), create, update and delete your groups.

Methods: groups

Method Description of output
GET /groups Lists all the groups on your portal
GET /groups?title= Searches for groups by name
POST /groups Creates a new group, with required parameters
PUT /groups/{id} Update a group: requires group_id
DELETE /groups/{id} Delete a group: requires group_id

Search for groups

Listing your groups

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/groups

Optional parameter name Type Description
title string Title of the group. Requires URL encoding to submit over a QueryString. The search uses pattern matching, not exact matching. All searches are case insensitive

Retrieve groups by title


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/groups?title=Sales

Groups data attributes returned

Attribute name Type Description
id integer Unique numeric identifier for the group
title string The title of the group
description text The description for the group
created_at date/time Date/time for when the group was created, in UTC format
updated_at date/time Date/time for when the group was last updated, in UTC format
number_of_members integer Number of users currently assigned to the group

Create a new group

Some string fields for names and descriptions have character limits. Exceeding these limits cause your POST calls to fail. See Portal: character limits of frequently-used fields in the application user documentation.

Create group with a name and description


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"Group" : { "title" : "New Title", "description" : "New description" }}'
 https://yourdomain.learnupon.com/api/v1/groups

Mandatory parameters to create a group

Parameter name Type Description
title string Title of the new group: this title must be unique to your portal

Optional parameters to create a group

Parameter name Type Description
description string Description of the new group
sso_sync boolean For SAML-SSO-configured portals only: determines if the group's Sync group with SAML SSO setting is enabled. If true, any SAML assertion indicating this group name assigns a user to this group. If false (default), this group isn't queried within the SAML assertion, and the user isn't automatically assigned to a group, regardless of the group list in the assertion. Requires an exact match for the group name.

Data attributes returned for creating a group

Attribute name Type Description
id integer Unique numeric identifier for the new group

Update a group

To update a group, you need the group_id, and at least one of: title or description parameters.

Update Group


curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"Group" : { "title" : "Updated Title", "description" : "Updated description" }}'
https://yourdomain.learnupon.com/api/v1/groups/12345

Mandatory parameters to update a group

Parameter name Type Description
id integer Unique numeric identifier of the group (12345 in the example call)
title string Title of the new group: this title must be unique to your portal
description string Description of the new group

Optional parameters to update a group

Parameter name Type Description
sso_sync boolean For SAML SSO configured portals only: determines if the group's Sync group with SAML SSO setting is enabled. If true, any SAML assertion indicating this group name assigns a user to this group. If false (default), this group isn't queried/searched within the SAML assertion, and the user isn't automatically assigned to it (regardless of the group list in the assertion). Requires an exact match for the group name

Delete a group

Delete Group requires a group_id


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"delete_enrollments" : "true"}' https://yourdomain.learnupon.com/api/v1/groups/12345

Mandatory parameters to delete a group

Parameter name Type Description
id integer Unique numeric identifier of the group (12345 in the example call)

Optional parameters to update a group

Parameter name Type Description
delete_enrollments boolean Indicates if you want to delete any enrollments created for learners when they joined this group. Set to true to delete Not Started and In progress enrollments. Completed enrollments remain, regardless of this setting

Portals

The portals resource lets you create sub-portals within the same realm as your top-level portal. It includes endpoints to search for (list, retrieve), create, update and delete your portals.

Methods: portals

Method Description of output
GET /portals Search for (list) existing sub-portals
GET /portals?title= Search for a specific sub-portal, by name
POST /portals Create a new sub-portal with required parameters
GET /portals/{id}/generate_keys Generate API keys for a sub-portal
PUT /portals/{id} Update a sub-portal and change its features
GET /portals/membership_types Search for association membership types and IDs
DELETE /portals/{id} Delete a sub-portal

Search for a portal

List all portals


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/portals

Search for a portal by name


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/portals?title=company%20x

Parameter name Type Description
title string Portal name or title. Requires URL encoding to submit the name over a QueryString. The search uses pattern matching, not exact matching. All searches are case insensitive.

Data attributes for portals returned

Attribute name Type Description
id integer Unique numeric identifier for the portal
title string Portal name or title. Requires URL encoding to submit the name over a QueryString. The search uses pattern matching, not exact matching. All searches are case insensitive
subdomain string The subdomain of the portal
created_at date/time Date/time for when the portal was created, in UTC format
updated_at date/time Date/time for when the portal was last updated, in UTC format
allow_course_authoring boolean Permissions: indicates if admins in a sub-portal can edit courses in that portal. Default is true, gives permissions to edit courses
number_of_members integer Number of users currently assigned to the portal
number_licenses_purchased integer For portal licensing: indicates the number of licenses purchased for a specific portal
number_licenses_used integer For portal licensing: indicates the number of licenses currently used for a specific portal
logo_image_url string URL of the logo image of the new portal
header_color string Hexadecimal code for the portal's header color, default (#419BBD)
navigation_color string Hexadecimal code for the portal's tab navigation color, default (#256188)

Create a new portal

Create portal


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"Portal" : { "subdomain": "clientx", "title" : "New Title", "description" : "New description", "logo_image_url" : "Image url", "banner_image_url" : "Image url", "store_banner_image_url" : "Image url", "favicon_image_url" : "Image url", "header_color" : "#419BBD", "navigation_color" : "#256188" }}' https://yourdomain.learnupon.com/api/v1/portals

Mandatory parameters for creating a portal

Parameter name Type Description
subdomain string Subdomain of your portal
title string Title of the new portal

Optional parameters for creating a portal

Parameter name Type Description
logo_image_url string URL of the logo image of the new portal
store_banner_image_url string URL for an image, to use as store banner image of the new portal
header_color string Hexadecimal code for the portal's header color, default (#419BBD)
navigation_color string Hexadecimal code for the portal's tab navigation color, default (#256188)
number_licenses_purchased integer For portal licensing: you can specify the number of purchased licenses for a given portal
copy_from_parent boolean If set to true, the new portal copies many settings from the top-level portal: includes any custom email templates, custom welcome messages, SSO settings, categories, and catalog settings. If SQSSO is set up on the top-level portal, this call generates a new SQSSO secret key, while copying other settings. This key appears in the response
allow_course_authoring boolean Permissions: indicates if admins in a sub-portal can edit courses in that portal. Default is true, gives permissions to edit courses

Data attributes returned from creating a portal

Attribute name Type Description
id integer Unique numeric identifier of the new portal
client_sqsso_secret_key string If copy_from_parent is true in the portal create, and if SQSSO was enabled on the top-level portal, the API returns a new Secret Key for the new portal's SQSSO, and copies all other SQSSO settings. Otherwise, this element will not be present in the result

Generate Keys

Generate portal keys


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/portals/12345/generate_keys

Once you create a new portal, you need new API keys to interact with it via the API.

These keys are not the same as the SQSSO secret key.

Mandatory parameters for generating API keys

Parameter name Type Description
id integer Unique numeric identifier for the portal (12345 in the example call)

Data attributes returned for generating API keys

Attribute name Type Description
id integer Unique numeric identifier for the portal (12345 in the example call)
username string the new API keys username that was generated for the portal
password string the new API keys secret key or username that was generated for the portal

Update a portal

When updating a portal, you cannot leave title or subdomain blank.

Update Portal


curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"Portal" : { "subdomain": "clienty", "title" : "Updated Title", "description" : "Updated description", "logo_image_url" : "Image url", "banner_image_url" : "Image url", "store_banner_image_url" : "Image url", "favicon_image_url" : "Image url", "header_color" : "#419BBD", "navigation_color" : "#256188" }}' https://yourdomain.learnupon.com/api/v1/portals/12345

Mandatory parameters for updating a portal

Parameter name Type Description
id integer Unique numeric identifier for the portal you are updating (12345 in the example call)

Optional parameters for updating a portal

Attribute name Type Description
title string New title of your portal
subdomain string New subdomain of your portal
logo_image_url string URL of the logo image of the new portal
store_banner_image_url string URL for an image, to use as store banner image of the new portal
header_color string Hexadecimal code for the portal's header color, default (#419BBD)
navigation_color string Hexadecimal code for the portal's tab navigation color, default (#256188)
number_licenses_purchased integer For portal licensing: you can specify the number of purchased licenses for a given portal
allow_course_authoring boolean Permissions: indicates if admins in a sub-portal can edit courses in that portal. Default is true, gives permissions to edit courses

Search for association membership types in a portal

Search for membership types


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/portals/membership_types

Sample response to a membership type search

{
    "membership_types": [
        {
            "id": 510,
            "label": "Member"
        },
        {
            "id": 511,
            "label": "Non-Member"
        },
        {
            "id": 11554,
            "label": "Students and retired members"
        }
    ]
}

Attribute name Type Description
id integer Unique numeric identifier for the membership type in that portal
label string Name of the membership type, as shown in the interface

For background see Associations and membership types articles in the LearnUpon Knowledge Base.

For portals that use association membership types: search for the membership type IDs, so you can set prices for individual courses through the API. These IDs remain stable across the portal.

By default every portal comes with Member and Non-member types. You add new membership types through the user interface.

Delete a portal

Delete Portal


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/portals/12345

Mandatory parameters to delete a portal

Parameter name Type Description
id integer Unique numeric identifier for the portal you are deleting (12345 in the example call)

Group memberships

Using the group_memberships resource you can:

Users can belong to more than one group at once.

These endpoints do not create or modify groups, or users: they associate existing users with existing groups. To create new groups, see Create a new group.

Methods: GroupMemberships

Method Description of output
GET /group_memberships?group_id={id} Search for users in a group
GET /group_memberships?group_id={id}&version_id=1.1 Search for users in a group, including group membership ID
GET /group_memberships?user_id={id} Find a user's group memberships, aka which groups a user belongs to
POST /group_memberships Create a GroupMembership, aka assign users to a group
DELETE /group_memberships/{groupmembership_id} Delete GroupMemberships, aka remove users from a group

Search for GroupMemberships, by group or by user

Retrieve a group's membership, by group_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/group_memberships?group_id=1235

Retrieve a group's membership, including group membership ID, by group_id and version_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/group_memberships?group_id=1235&version_id=1.1

Mandatory parameters to search for GroupMemberships

A search of GroupMemberships requires either the group_id or user_id.

Parameter name Type Description
group_id integer Unique numeric identifier for a group. You find the identifier from the GET /groups call: see Search for groups
user_id integer Unique numeric identifier for individual user. You find the identifier from the GET /users call: see Search for users

Optional parameter to search for Group Membership ID

Parameter name Type Description
version_id numeric Default is 1.1. Together with group_id search, this call returns the group_membership_id

Data attributes for GroupMembership users returned

A search by group_id returns a a list of user objects, which contains the following attributes. See more detailed data on users

Attribute name Type Description
id integer Unique numeric identifier for the user
first_name string The first name of the user
last_name string The last_name of the user
email string The email address for the user: LearnUpon's default unique user identifier
username string The username of the user: appears only if you enable usernames. See Unique identifiers: email or usernames
created_at date/time Date/time for when the user was created, in UTC format
locale string The ISO language code of the user. See language-codes

Data attributes for GroupMembership groups returned

A search by group_id and version_id returns a list of user objects, including the group membership ID for each user.

Attribute name Type Description
id integer Unique numeric identifier for user's group membership
user_id integer Unique numeric identifier for the user
first_name string The first name of the user
last_name string The last_name of the user
email string The email address for the user: LearnUpon's default unique user identifier
username string The username of the user: appears only if you enable usernames. See Unique identifiers: email or usernames
created_at date/time Date/time for when the user was created, in UTC format
locale string The language ISO locale of the user

Data attributes for GroupMembership groups returned

A search by user_id returns a list of group objects, containing the following attributes. See more detailed data on groups.

Attribute name Type Description
id integer Unique numeric identifier for the group
title string The title of the group
description string The description of the group
created_at date/time Date/time when the group was created, in UTC format
updated_at date/time Date/time when the group was last updated, in UTC format

Create a GroupMembership

Create a group membership


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"GroupMembership": { "group_id" : 6789, "user_id" : 1234 }}' https://yourdomain.learnupon.com/api/v1/group_memberships

Mandatory parameters for creating a GroupMembership

Parameter name Type Description
group_id integer The group that you want to assign a user to
user_id integer The user that you want to assign to the group

Optional parameters for creating a GroupMembership

Parameter name Type Description
process_enrollments boolean If set to (default) true, assigning a user to a group automatically enrolls the user into any learning paths or courses associated with the group. Set to false if you don't need automatic enrollments

Attributes returned from GroupMembership create

Attribute name Type Description
id integer Unique numeric identifier for the group membership

Delete a GroupMembership

This endpoint does not delete users or groups: it removes users from groups.

GroupMembership delete using the groupmembership_id


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/group_memberships/1234

Group Membership Delete using the group_id and user_id


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"GroupMembership": { "group_id" : 6789, "user_id" : 1234 }}' https://yourdomain.learnupon.com/api/v1/group_memberships/0

Identify the membership to delete

You have two options to delete the correct membership:

Mandatory parameters for deleting a GroupMembership, second method

Parameter name Type Description
group_id integer The group with the membership you want to delete
user_id integer The user that you want to remove from the group

Optional parameters for deleting a GroupMembership

Parameter name Type Description
process_unenrollments boolean If set to (default) true, deleting a user from a group automatically unenrolls the user from any learning paths or courses associated with the group. Set to false if you don't need automatic unenrollments.

Group Invites

The group_invites resource lets you invite multiple users into a portal or group, in one API call. When this API call is successful, LearnUpon sends an invite email to each email address. The receiver must click the invite link contained in the email to accept the invite.

The Portal Invites resource also lets you invite users into a portal or group. The main differences between the Group Invites and Portal Invites API endpoints are:

If you need to issue invites and enroll users onto courses at the same time, see the Group Invite Course Enrollment.

Methods: GroupInvites

Method Description of output
GET /group_invites Search for invites sent to users, within a portal
GET /group_invites?group_id={group_id} Search for invites sent to users, to join a specific group, by group_id
GET /group_invites/{group_invite_id} Search for a group invite by ID
POST /group_invites Create invites for users by their unique identifier
DELETE /group_invites/{group_invite_id} Delete a group invite by ID

Search for GroupInvites

List GroupInvites, filtered by group_id and by invite_email_address


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_invites?group_id=123&invite_email_address=someone@samplelearningco.com

Find a set of invites, by group_invite_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_invites/123

Optional parameters for searching for GroupInvites

Parameter name Type Description
group_id integer Unique numeric identifier for a group that you want the list of invites for
invite_email_address string The destination email address, where you send the invite
group_invite_id integer Unique numeric identifier for a group invite already issued. You find the group_invite_id when you create a GroupInvite

Data objects returned by search for GroupInvites

Attribute name Type Description
group_invite object An object containing the list of invites. See the following section for the object details
customDataFieldDefinitions object An object containing the list of custom user data field definitions: available only if custom user data fields are defined. See the descriptions as part of the Users object

GroupInvite object attributes

Attribute name Type Description
id integer Unique numeric identifier for the invite in LearnUpon
created_at date/time The date the invite was created, in UTC format
expires_at date/time The expiry date for the user's account after they accept their invite
num_reminders_sent integer The number of reminders sent to the user: maximum is 5 spread over 5 weeks
last_reminder_sent_at date/time The last date the invite was sent as a reminder to the user, in UTC format
invite_status string Indicates the status of the invite, can be one of: sent, accepted, rejected, canceled
invite_email_address string The destination email address, where you send the invite
last_name string The last name of the invited user
first_name string The first name of the invited user
username string The username of the user: appears only if you have implemented usernames on the portal, and if you used batch user uploads to create the invite. See Unique identifiers: email or username.
user_type string Indicates the user type assigned to the user, once the invite is accepted: one of learner, instructor, manager, admin
accept_url string The URL that the user was sent allowing them to accept the invite. This URL does not contain the host or domains, only the URL parts. The API user needs to build the URL with the correct HTTP protocol and host
group_id integer The group you invite the user to join. Typically this value is the portal_id. If you are implementing groups, group_id helps determine which group the invite was issued for: see GroupMemberships
sf_contact_id string Salesforce only: Salesforce Contact ID. Returns null if user record doesn’t have a Salesforce Contact ID
sf_user_id string Salesforce only: Salesforce User ID. Returns null if user record doesn’t have a Salesforce user ID
customDataFieldValues object An object containing Custom User Data details: see the descriptions as part of the Users object

Create a GroupInvite

Create Group Invite


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"GroupInvite": { "email_addresses": "someone@samplelearningco.com", "group_id" : 6789, "group_membership_type_id": 1 } }'
 https://yourdomain.learnupon.com/api/v1/group_invites

Mandatory parameters for a GroupInvite

Attribute name Type Description
email_addresses string The user(s) you are inviting: for more than one user, enter a comma-separated list

Optional parameters

Attribute name Type Description
group_id integer Unique numeric identifier for the group you are inviting users to join. If no group_id is specified then the user is invited to the main portal
group_membership_type_id integer The user type assigned to invited users: one of 1=learner (default), 2=admin, 3=instructor, 4=manager

Attributes returned from creating a GroupInvite

When you create a GroupInvite you get an array of group_invites back, with each element of the array representing a group_invite that you created/sent. Each invite contains the group_invite_id and the email address that was used for that invite.

Delete a GroupInvite

Deleting a GroupInvite does not delete the group, or the users: it deletes the invitation, and the (pending) association with the group for the user.

Delete Group Invite


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/group_invites/1234

Mandatory parameters to delete a GroupInvite

Parameter name Type Description
group_invite_id integer Unique numeric identifier for the GroupInvite you created

Group Invite Course Enrollment

You send invites or GroupInvites to users, to ask them to join a portal, or group within a portal. An invite goes to the designated user/email address. The recipient clicks the invite link in the email to accept that invite.

You can create invites

In addition to inviting a user to a group or portal, you can also invite a user to join a course. Adding an invite to a course creates a GroupInvite Course Enrollment. Effectively, it places the pending invite or user on that course as an enrollment. When the user accepts their invite, they are automatically enrolled on the course.

To view pending enrollments in LearnUpon, log in as an admin and access Enrollments > Pending enrollments.

Methods: GroupInviteCourseEnrollment

Method Description of output
GET /group_invite_course_enrollments Search for all GroupInvite course enrollments on the portal
GET /group_invite_course_enrollments/{id} Search for GroupInvite course enrollments by group_course_enrollment_id
GET /group_invite_course_enrollments?course_id={course_id} Search for GroupInvite course enrollments by course_id
GET /group_invite_course_enrollments?group_id={group_id} Search for GroupInvite course enrollments by group_id
GET /group_invite_course_enrollments?course_name={course_name} Search for GroupInvite course enrollments by course_name
POST /group_invite_course_enrollments Create a GroupInvite course enrollment: requires group_invite_id and one other identifier
DELETE /group_invite_course_enrollments/{id} Delete a GroupInvite course enrollment: requires a group_invite_course_enrollments_id

Search for all GroupInviteCourseEnrollments

List All GroupInviteCourseEnrollments


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_invite_course_enrollments

List a specific GroupInviteCourseEnrollments


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_invite_course_enrollments/123

Optional parameters to list GroupInviteCourseEnrollments

Parameter name Type Description
course_id integer Unique numeric identifier for a course
course_name string The exact title of the course, using the most recent published course title
group_id integer Unique numeric identifier for a group: to list invites in a portal, omit this parameter
group_invite_course_enrollment_id integer Unique numeric identifier for a GroupInviteCourseEnrollments

Data attributes returned for listing GroupInviteCourseEnrollments

Attribute name Type Description
id integer Unique numeric identifier for the GroupInviteCourseEnrollments
created_at date/time The date the invite was created, in UTC format
expires_at date/time The expiry date for the user's account after they accept their invite
num_reminders_sent integer The number of reminders sent to the user, maximum is 5 spread over 5 weeks
last_reminder_sent_at date/time The last date the invite was sent as a reminder to the user, in UTC format
invite_status string Indicates the status of the invite, can be one of: sent, accepted, rejected, canceled
invite_email_address string The destination email address, where you send the invite
last_name string The last name of the user you invited to a group or portal
first_name string The first name of the user you invited to a group or portal
username string The username of the user: only appears if you have implemented usernames on the portal, and if you used batch user uploads to create the invite. See Unique identifiers: email or username.
user_type string Indicates the user type assigned to the user, once the invite is accepted: one of learner, instructor, manager, admin
accept_url string The URL that the user was sent allowing them to accept the invite. This URL does not contain the host or domains, only the URL parts. The API user needs to build the URL with the correct HTTP protocol and host.
group_id integer Unique numeric identifier for the group you invite the user to join. Typically this value is the portal_id. If you are implementing groups, group_id helps determine which group the invite was issued for: see GroupMemberships
group_invite_id integer Unique numeric identifier for the GroupInvite associated with the enrollment invite
course_id integer Unique numeric identifier for the course associated with the enrollment invite
course_name string The exact title of the course, using the most recent published course title

Create a GroupInviteCourseEnrollment

Create GroupInvite course enrollment


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"GroupInviteCourseEnrollment": { "group_invite_id": 12345, "course_id": 6789 } }'
 https://yourdomain.learnupon.com/api/v1/group_invite_course_enrollments

Mandatory parameters for creating a GroupInviteCourseEnrollment

To enroll users with a GroupInvite, you need the group_invite_id and one of the course_id or the course_name. If you provide both in the payload, the course_id takes precedence.

Parameter name Type Description
group_invite_id integer Unique numeric identifier for the GroupInvite
course_id integer The course that you are enrolling the GroupInvite onto
course_name string The exact title of the course, using the most recent published course title

Data attributes returned for creating a GroupInviteCourseEnrollments

Attribute name Type Description
id integer Unique numeric identifier for the GroupInviteCourseEnrollment

Delete a GroupInviteCourseEnrollment

Delete a GroupInviteCourseEnrollment


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_invite_course_enrollments/1234

Mandatory parameters to delete a GroupInviteCourseEnrollment

Parameter name Type Description
id integer Unique numeric identifier for the GroupInviteCourseEnrollment

Group Courses

The group_course resource lets you associate a course with a user group in LearnUpon. By linking a course to a group you initiate two actions:

Methods: GroupCourses

Method Description of output
GET /group_courses Searches for all GroupCourses, by date they were created
GET /group_courses?group_id={group_id} Searches for courses which a specific group takes
GET /group_courses?course_id={course_id} Searches for groups which a take a specific course
POST /group_courses Creates a GroupCourse: requires group_id and course_id
DELETE /group_courses/{group_courses_id} Deletes a GroupCourse: requires group_course_id

List your GroupCourses

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_courses

Search GroupCourses by group_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_courses?group_id=12345

Search GroupCourses by course_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_courses?course_id=12345

Optional parameters to search for GroupCourses

Parameter name Type Description
group_id integer Unique numeric identifier for a group
course_id integer Unique numeric identifier for a course

Data attributes returned for GroupCourses

Attribute name Type Description
id integer Unique numeric identifier for the GroupCourse
group_id integer Unique numeric identifier for the group
course_id integer Unique numeric identifier for the course
group_title string Title of the group
course_name string The exact title of the course, using the most recent published course title

Create a GroupCourse

To create a GroupCourse, you need the ids for both the group and the course, and you need to indicate if LearnUpon must re-enroll groups automatically.

Create a group course


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"GroupCourse": {"group_id" : "5127", "course_id" : "12360"}, "re_enroll_completed" : "true"}'
 https://yourdomain.learnupon.com/api/v1/group_courses

Mandatory parameters to create GroupCourses

Parameter name Type Description
group_id integer Unique numeric identifier for the group
course_id integer Unique numeric identifier for the course
re_enroll_completed boolean Re-enroll users in this group to the specified course, if they previously completed the specified course

Delete a GroupCourse

This endpoint does not delete a course or a group: it removes the association between a group and a course.

Delete a GroupCourse

curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"delete_enrollments": "true"}' https://yourdomain.learnupon.com/api/v1/group_courses/12345

Mandatory parameters to delete GroupCourses

Parameter name Type Description
id integer Unique numeric identifier of the GroupCourse to delete (12345 in the example call)

Optional parameters to delete GroupCourses

Parameter name Type Description
delete_enrollments boolean Set to true to delete incomplete enrollments: applies only to enrollments you set up via the group_course endpoint. Default is false

Group Managers

The group_managers resource connects a user, with user type manager, with a user group in LearnUpon. You are not creating a new usertype, or a new group: you're creating a relationship between a user and a group.

By linking a manager user to a group, you initiate two actions in LearnUpon:

Methods: GroupManagers

Method Description of output
GET /group_managers Searches for (lists) all the GroupManagers on a portal
GET /group_managers?group_id={group_id} Searches for GroupManagers by group_id
GET /group_managers?user_id={user_id} Searches for a GroupManager by user_id
GET /group_managers?username={username} Searches for a GroupManager by username
GET /group_managers?email={email} Searches for a GroupManager by email
POST /group_managers Creates a GroupManager: requires group_id and user_id
DELETE /group_managers/{id} Deletes a GroupManager by groupmanager_id

List your GroupManagers

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/group_managers

Optional parameters to search for GroupManagers

Parameter name Type Description
group_id integer Unique numeric identifier for the group
user_id integer Unique numeric identifier for the manager user
email string Default unique identifier for the user
username string Unique username of the manager. Appears only if you set up username in place of email as unique identifier: see Unique identifiers: email or username

Example search by group

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_managers?group_id=12345

Example search by user identifiers


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/group_managers?user_id=6789

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_managers?username=api.user

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_managers?email=api.user@samplelearningco.com

Data attributes returned for GroupManager

Attribute name Type Description
id integer Unique numeric identifier for the GroupManager
created_at date/time Date/time that the GroupManager was created, in UTC format
updated_at date/time Date/time that the GroupManager was last updated, in UTC format
can_create_users boolean Describes if this GroupManager can create users in this group, or within LearnUpon (they may manage other groups where this attribute is not set): default is false
group_id integer Unique numeric identifier for the group
group_title string Title of the group
group_description string Description of the group
number_of_members integer The number of users in this group
number_of_courses integer The number of courses that are linked to this group, by way of group course associations, that automatically create enrollments when a user joins this group
user_id integer Unique numeric identifier of the manager user
email string The email address of the manager: default unique identifier for users
username string The username of the manager. Appears only if you set up username in place of email as unique identifier: see Unique identifiers: email or username
first_name string The first name of the manager
last_name string The last name of the manager

Create GroupManager

Create a GroupManager

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"GroupManager": {"group_id" : "5127", "user_id" : "12360", "can_create_users": true}}' https://yourdomain.learnupon.com/api/v1/group_managers

Mandatory parameters for creating a GroupManager

Parameter name Type Description
group_id integer Unique numeric identifier for the group
user_id integer Unique numeric identifier for the user
can_create_users boolean Describes if this GroupManager can create users in this group, or within LearnUpon: they may manage other groups where this attribute is not set. Default is false

Data attributes returned for creating a GroupManager

Attribute name Type Description
id integer Unique numeric identifier for the GroupManager
created_at date/time Date/time you created the GroupManager, in UTC format

Delete a GroupManager

This endpoint does not delete a group or a manager user: it deletes the connection between them.


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/group_managers/12345

Mandatory parameters for deleting a GroupManager

Parameter name Type Description
id integer Unique identifier of the GroupManager to delete (12345 in the example call). You find this id when creating or searching for GroupManagers

Course Instructors

A course instructor is a user, with the user type instructor, who leads a course within LearnUpon. The instructor user type has different permissions from learner, manager and admin.

The course_instructor resource lets you associate an instructor user with a course in LearnUpon. You are not creating a new usertype, or a new course, but are creating a relationship between a user and a course. By linking an instructor user to a course to lead, you initiate two actions:

Methods: CourseInstructor

Method Description of output
GET /course_instructors Searches for (list) all CourseInstructors on a portal
GET /course_instructors?course_id={course_id} Searches for CourseInstructor by course_id
GET /course_instructors?user_id={user_id} Searches for CourseInstructor by user_id
GET /course_instructors?username={username} Searches for CourseInstructor by username
GET /course_instructors?email={email} Searches for CourseInstructor by email
POST /course_instructors Creates a CourseInstructor: requires a user_id, and course_id
DELETE /course_instructors?{id} Deletes a CourseInstructor: requires courseinstructor_id

Search for CourseInstructors

Listing all CourseInstructors


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/course_instructors


Search for CourseInstructors by course


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/course_instructors?course_id=12345

Search for CourseInstructors by user_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/course_instructors?user_id=6789

Search for CourseInstructors by username


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/course_instructors?username=api.user

Search for CourseInstructors by email address


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/course_instructors?email=api.user@samplelearningco.com
Parameter name Type Description
course_id integer Course's unique numeric identifier
user_id integer The unique identifier of the instructor user
email string The email of the user, used as default unique identifier
username string Alternate unique identifier for users: available only if you set up usernames in place of email as unique identifier. See Unique identifiers: email or username
Attribute name Type Description
id integer Unique numeric identifier for the CourseInstructor
created_at date/time Date/time that the CourseInstructor was created, in UTC format
updated_at date/time Date/time that the CourseInstructor was last updated, in UTC format
enrollment_count integer The number of learners that are assigned to this instructor for the given course
course_id integer Unique numeric identifier for the course
course_name string The exact title of the course, using the most recent published course title
version integer The version of the course
course_created_at date/time Date/time that the course was created in UTC format
sellable boolean If set to true, indicates the course is published to the store: default is false
cataloged boolean If set to true, indicates if the course is published to the catalog: default is false
date_published date/time Date/time when the course was published, in UTC format
keywords string Keywords you provide, to help users find your course
reference_code string A customer reference code, to help you find your courses in the library in search, and use in reports: not generated by LearnUpon
manager_can_enroll boolean If set to true, indicates the manager can enroll their team members on this course: default is false
allow_users_rate_course boolean If set to (default)true, indicates learners can rate this course
number_of_reviews integer Number of reviews/ratings recorded for this course: use in combination with number_of_stars to calculate an average rating
number_of_stars integer Number of stars awarded to the course: use this in combination with number_of_reviews to calculate an average rating
minute_length float The course length, if specified, that appears in your store or catalog
course_length_unit string The length unit for your course: hours or minutes
price integer Price in cents for your course
published_status_id string The current published status of the course: one of published, draft, archived or under_revision
difficulty_level string The difficulty level set on your course: one of not_applicable, basic, intermediate or advanced
description_html string Course description, with full HTML markup
description_text string Course description, raw text
objectives_html string Course objectives, with full HTML markup
objectives_text string Course objectives, raw text

Create a CourseInstructor

To associate an instructor user with a course, you need their user_id and the course_id for the course they are leading.

Create a CourseInstructor

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{CourseInstructor: {"course_id" : "5127", "user_id" : "12360" }}' https://yourdomain.learnupon.com/api/v1/course_instructors

Mandatory parameters to create a CourseInstructor

Parameter name Type Description
course_id integer Unique numeric identifier for the course
user_id integer Unique numeric identifier for the user

Attributes returned from creating a CourseInstructor

Attribute name Type Description
id integer Unique numeric identifier for the CourseInstructor
created_at date/time Date time you created the CourseInstructor, in UTC format

Delete a CourseInstructor

This operation does not delete the instructor user, or the course: it deletes the association between the instructor user and the course.

Delete a course instructor


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/course_instructors/12345

Mandatory parameters to delete a CourseInstructor

Parameter name Type Description
id integer Unique numeric identifier for the course instructor (12345 in the example call). You find this id when creating or listing a CourseInstructor

Learning paths

A learning path is a customized collection of courses, akin to a curriculum. Learners follow the path to attain specific subject matter knowledge and/or certification or accreditation.

The learning_path resource lets you search for existing learning paths.

Method: learning paths

Method Description of output
GET /learning_paths Search for learning paths on a portal

Search for learning paths

List all learning paths on a portal

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c https://yourdomain.learnupon.com/api/v1/learning_paths

Optional parameters for search

Parameter name Type Description
name string Learning path name/title. Use URL encoding to submit over a QueryString. The search for learning paths uses pattern matching, not exact matching, and are case insensitive
id integer Unique numeric identifier for the learning path. Set include_draft to false, so that you do not negate an ID search
include_draft boolean Set to true to return both draft and published versions. Default false returns only published versions
include_courses boolean Set to true to return a list of courses for each learning path. Default is false

Attributes returned for listing learning paths

Attribute name Type Description
id integer Unique numeric identifier for the learning path
name string Title of the learning path
created_at date/time Date/time when the learning path was created, in UTC format
sellable boolean If set to true, indicates the learning path is published to the store. Default is false
cataloged boolean If set to true, indicates if the learning path is published to the catalog. Default is false
date_published date/time Date/time when the learning path was published, in UTC format
keywords string Keywords you provide to help users find the learning path
minute_length float Learning path length, if specified, that appears in your store
path_length_unit string Length unit for your learning path: hours or minutes
price integer Price in cents for your learning path
published_status_id string The current published status of the learning path: one of published, draft, archived
difficulty_level string The difficulty level set on your learning path: one of not_applicable, basic, intermediate or advanced
description_html string Learning path description, with full HTML markup
description_text string Learning path description, raw text
credits_to_be_awarded string Comma-separated list of credits the learner earns by completing or passing the learning path. e.g. "CEU:2.00,CPE:3.00"
due_days_after_enrollment integer The number of days after enrollment, when the learner is due to complete the learning path
due_date_after_enrollment date/time The date/time in UTC format, when this learning path is due for completion
send_due_date_reminders boolean If set to true, indicates that due date reminders are enabled on this learning path. Default is false
due_date_reminder_days integer For the first reminder LearnUpon sends: number of days before the learning path is due for completion
due_date_reminder_days_2 integer For the second reminder LearnUpon sends: number of days before the learning path is due for completion
thumbnail_image_url string Public URL for the learning path thumbnail image. Returns null if the learning path has no thumbnail
courses array Array containing list of courses for the learning path. See the data attributes in the following table

Course list data attributes

Attribute name Type Description
id integer Unique numeric identifier for the course
name string Title of the course
sequence integer Indicates the order that the courses appear in the learning path

Learning path enrollments

In LearnUpon terminology, enrolling a user is the process of connecting a user to a learning path (or course), which gives the user access to a learning path and its assets.

The learning_path_enrollments resource lets you:

Methods: learning path enrollments

Method Description of output
GET /learning_path_enrollments/{id} Search for a learning path enrollment by its id
GET /learning_path_enrollments/search?user_id={user_id} Search by user_id
GET /learning_path_enrollments/search?email={email} Search by email
GET /learning_path_enrollments/search?username={username} Search by username
GET /learning_path_enrollments/search?lp_id={lp_id} Search for enrollments in a path by learning path ID
GET /learning_path_enrollments/search?lp_name={lp_name} Search for enrollments by learning path name
POST /learning_path_enrollments Create a new enrollment: requires user and learning path identifiers

Search for learning path enrollments

Retrieve a single learning path enrollment by id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/2757

Retrieve learning path enrollments for a user by id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?user_id=1234

Retrieve learning path enrollment for a user by email

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?email=learnuponapi@samplelearningco.com

Retrieve learning path enrollment for a user by username

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
 https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?username=learnupon

Retrieve learning path enrollments by learning path identifier

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?lp_id=1234

Retrieve learning path enrollments by learning path name

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?lp_name=Hello%20API

Use date based filtering for learning path enrollments, with "date_from" and "date_to" parameters.

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c

https://yourdomain.learnupon.com/api/v1/learning_path_enrollments/search?lp_name=Hello%20API&date_from=YYYY-MM-DD&date_to=YYYY-MM-DD

Mandatory parameters for listing learning path enrollments

You need to provide one of the following parameters to search learning path enrollments.

Parameter name Type Description
id integer Unique numeric identifier for the learning path enrollment
email string Email address: default unique identifier for users
username string Alternate unique identifier for users in LearnUpon. Available only if you set up username in place of email as unique identifier: see Unique identifiers: email or username
lp_name string The name of a learning path
lp_id integer Unique numeric identifier for a learning path

Optional parameters for listing learning path enrollments

Parameter name Type Description
date_from date/time A start date to filter enrollment results by, in UTC format: based on the enrollment's updated_at timestamp
date_to date/time An end date to filter enrollment results by in UTC format: based on the enrollment's updated_at timestamp

Data attributes returned for learning path enrollment

Attribute name Type Description
id integer Unique numeric identifier for the learning path enrollment
percentage integer Score achieved by the learner for their learning path enrollment
date_started date/time Date/time when the learner started their course, in UTC format
date_completed date/time Date/time when the learner completed their learning path, in UTC format
date_lastaccessed date/time Date/time when the learner last accessed their learning path, in UTC format
date_enrolled date/time Date/time when the learner was enrolled on the learning path, in UTC format
lp_id integer Unique numeric identifier for the learning path, for this learning path enrollment
lp_name string Name/title of the learning path, for this learning path enrollment
user_id integer Unique numeric identifier for the user
first_name string First name of the user enrolled
last_name string Last name of the user enrolled
email string Email address: default unique identifier for user enrolled
username string Alternate unique identifier for users in LearnUpon. Appears only if you set up username in place of email as unique identifier: see Unique identifiers: email or username
due_date date/time Date/time in UTC format the learning path is due to be completed by the learner, if set
status string The learning path enrollment status of the learner, can be one of: not_started, in_progress, completed
certificate_name string If the user receives a certificate for completing a learning path enrollment, then this is the title of that certificate
cert_expires_at date/time Date/time in UTC format of the certification expiry, if set
was_recertified boolean If set to true, it indicates that recertification policies on your learning path certificate were applied For users who complete a learning path that has automatic recertification rules enabled, when they repeat the learning path, they are automatically recertified by LearnUpon. Default is false
unenrolled boolean Indicates if a learning path enrollment was previously unenrolled from this learning path. Previous enrollment is hidden from the learners' views, but appears in the course history report, in audit/learning history data. Default is false

Create a learning path enrollment

Create a learning path enrollment


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
 '{"Enrollment": { "email" : "learnuponapi@samplelearningco.com", "lp_name" : "Hello API"}}' https://yourdomain.learnupon.com/api/v1/learning_path_enrollments

Mandatory parameters to create a learning path enrollment

To enroll a user on a learning path, you need to specify:

Parameter name Type Description
user_id integer Unique numeric identifier for the user
email string Email of the user you are enrolling
username string Username of the user you are enrolling. Applicable only if you set up username in place of email as unique identifier. See Unique identifiers: email or username
lp_name string Exact title of the learning path you are enrolling a user on. When selecting by learning path name, LearnUpon uses the latest (published) version of the learning path
lp_id integer Unique numeric identifier of the learning path you are enrolling a user on

Optional parameters to create a learning path enrollment

Parameter name Type Description
re_enroll_if_completed boolean Set to true to re-enroll the user on the learning path, if they have previously completed the learning path: default is false

Data attributes returned for creating a learning path enrollment

Attribute name Type Description
id integer Unique numeric identifier for the learning path enrollment
created_at date/time Date/time when the learning path enrollment was created in UTC format

Gamification

Gamification helps motivate your learners by offering badges for their activity in your portal. LearnUpon provides a set of badges by default. You can upload your own badge designs if required.

The badges resource lets you list the badges available on a portal. The leaderboard resource lets you search for results, filtered by user, group or other parameters.

Method: badges

Method Description of output
GET /badges Searches for (list) all badges on the portal
GET /badges?version_id=1.1 Searches for all badges, and includes a path to the badge image

Search for gamification badges

List gamification badges: these results help you build leaderboard queries


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c https://yourdomain.learnupon.com/api/v1/badges

Data attributes returned for searching for badges

Attribute name Type Description
id integer Unique numeric identifier for the gamification badge
name string Name of the learning badge
points integer Number of points the user is awarded for the badge
is_used boolean Indicates the badge being in use: default is true
badge_type_id integer Unique numeric identifier for the type of badge type
badge_type string Title of the badge type, for example: "level_badge", "learning_badge", "activity_badge"
created_by integer Unique numeric ID of the user who created the badge
updated_by integer Unique numeric ID of the user who last updated the badge
created_at date/time Date/time the gamification badge was created, in UTC format
updated_at date/time Date/time the gamification badge was last updated, in UTC format
image_url string URL for the badge image

Methods: leaderboards

Method Description of output
GET /leaderboard Search for (list) leaderboards data for the portal
GET /leaderboard?user_id= Search for leaderboard results by user_id. Returns the learner's results within their leaderboard
GET /leaderboard?group_id= Search for leaderboard results by group_id

List Gamification leaderboards

Search for all leaderboards on a portal

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/leaderboard

Retrieve leaderboard results by user

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/leaderboard?user_id=1234

Retrieve leaderboard by group

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/leaderboard?group_id=123

Optional parameters

Parameter name Type Description
group_id integer Unique numeric identifier for a specific group
user_id integer Unique numeric identifier for a specified user
points_over integer Minimum number of points
points_under integer Maximum number of points
date_from date/time Starting date/time for a query
date_to date/time Ending date/time for a query
level_name string Name of a particular level, for filtering users

Data attributes returned for gamification leaderboard

Attribute name Type Description
user_id integer Unique numeric identifier for the user on the leaderboard
login string Username or email address of the user
name string Display name of the user on the leaderboard
position integer Position of the user on the leaderboard
level string If levels are enabled: name of the level the user is on
total_points integer Total gamification points of the user on the leaderboard
total_badges integer Total count of badges for the user on the leaderboard

Batch user upload

The batch/upload endpoint automatically creates or invites users to a portal, based on the user data you provide in a CSV file. The CSV file can contain user details such as custom user data and group assignments. See Users > Batch Upload on your portal for a CSV template file, or see the application's Knowledge Base articles about batch user upload.

The batch/upload_and_sync endpoint creates or invites users to a portal, based on a CSV file: first it compares the new file to the previous file from you, and performs a differential, so it only updates the learners who have changed from the previous file. If this is your first batch upload, the endpoint creates or invites all users.

Methods: batch user upload

Method Description of output
POST /batch/upload Uploads a CSV file of user data, to create or invite new users, and update existing ones
POST /batch/upload_and_sync Uploads a CSV file of user data, compares it to your previous file: creates or invites only new users, and updates only changed users

Batch user upload


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"user_id" : "12345", "sftp_username" : "example_username", "sftp_password" : "example_password", "file_url":
"sftp://198.51.100.1:22/example_file.csv", "batch_params": {"invite_users": false, "update_users": false, "group_sync": false} }'
https://yourdomain.learnupon.com/api/v1/batch/upload

Batch user upload and sync with previous file

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"user_id" : "12345", "sftp_username" : "example_username", "sftp_password" : "example_password", "file_url":
"sftp://198.51.100.1:22/example_file.csv", "batch_params": {"invite_users": false, "group_sync": false} }'
https://yourdomain.learnupon.com/api/v1/batch/upload_and_sync

Batch user upload procedure

This process requires you to provide a CSV file from your own SFTP server. Make sure:

You make the API call including the SFTP server details. When successful, the batch user upload job connects to your SFTP server to get the CSV file and to begin the upload.

LearnUpon sends an email to the admin address provided, if any of the following types of errors happen:

LearnUpon sends a summary email to the provided LearnUpon admin user after the application completes the job.

The upload job may be queued, and so may not run immediately even after a successful API call.

Batch user upload and sync procedure

This feature works in the same way as the batch user upload. The differences:

Prerequisites

  1. To use these API calls, LearnUpon must add your SFTP server IP address(es) to the allow list. Contact the LearnUpon Support team with the IP address(es) of your SFTP server.
  2. The CSV file format must be the same as is currently used in LearnUpon’s batch user upload feature.
  3. LearnUpon supports SFTP versions 3 and above.
  4. The CSV file cannot be larger than 50MB.
  5. Only one batch import can be processed at any one time.

Mandatory parameters for batch upload endpoints

Parameter name Type Description
user_id string The unique numeric identifier of a LearnUpon admin user, who receives the summary email: see the Search for users endpoints
sftp_username string The username for the SFTP server
sftp_password string The password of the SFTP user
file_url string The SFTP URL for the file in format sftp://ip_address:port_number/file_name Example: sftp://198.51.100.1:22/example_file.csv

Optional parameters for batch upload endpoints

Parameter name Type Description
batch_params object An object with additional settings to control the batch import, sent as a JSON object. See the next section for the object definition

batch_params object attributes for batch upload

Attribute name Type Description
invite_users boolean If set to true, indicates you are inviting, not creating, users: default is false, to create users
update_users boolean If set to true, indicates you are updating existing users, as well as creating/inviting new users: default is false to create/invite new users only
group_sync boolean If set to true, indicates you want a full group sync: default is false
process_unenrollments boolean If set to true, the attribute unenrolls users from courses and paths, when you remove users from groups. Default is false. Requires group_sync set to true

batch_params object attributes for batch upload and sync

Attribute name Type Description
invite_users boolean If set to true, indicates you are inviting, not creating, users: default is false, to create users
group_sync boolean If set to true, indicates you want a full group sync: default is false
process_unenrollments boolean If set to true, the attribute unenrolls users from courses and paths, when you remove users from groups. Default is false. Requires group_sync set to true

Data returned for batch user upload, and for upload and sync

HTTP code Message Description
200 --- API call was successful
400 invalid request A batch import is already in progress: only one batch import can be processed at any one time
400 problem with SFTP server Indicates one of the following: SFTP server connection issue; SFTP server doesn’t support version 6; file is bigger than 100K rows; file is bigger than 50MB; file doesn’t exist
400 group sync not chosen, cannot process unenrollments group_sync must be set to true to use process_unenrollments
401 not authorised The provided LearnUpon user_id isn’t a portal admin
404 invalid request Missing or invalid attributes in the API call
429 exceeded limit on API requests LearnUpon received too many API requests per minute, or per week, from your portal. Further requests get an error until the limit on API requests expires

Appendix

Language codes

Possible values for language attribute of users when creating or updating

Value Description
en US English (Default)
en_gb UK English
zh_cn Chinese (Simplified)
zh_tw Chinese (Traditional)
cs Czech
da Danish
nl Dutch
nl_be Flemish
fr French
fr_ca French (Canadian)
de German
hu Hungarian
it Italian
ja Japanese
nb_no Norwegian
pl Polish
pt Portuguese
pt_br Portuguese (Brazilian)
ru Russian
sk Slovak
es Spanish
sv Swedish
tr Turkish
ko Korean
fi Finnish