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:

JSON API development
using a framework/SDK for your preferred language
encoding and decoding JSON data
general HTTP request types
HTTP response codes

API access and authentication

The full URL for accessing the API is

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

yourdomain represents your own unique subdomain/portal in LearnUpon
resource represents the path to the resource you are accessing

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

Log in to your LearnUpon portal as an admin
Select Settings > Integrations > API Keys
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:

batch processing a lot of data, which is not urgent. In such cases, use throttling, as simple as introducing a "sleep" between every few requests, to spread the number of calls over a longer period. For example: run 5 requests, wait 3 seconds, run the next 5 requests.
create or update a lot of data immediately and urgently: for example, creating a sub-portal, cloning 10 courses and adding 200 users, as soon as you receive a customer payment. Explain a slight delay to your customer ("We will email you when your portal is ready"), or split the API calls into categories of urgency. In this example, you could
- create the client portal
- add the admin user (who initiated the process, or payment)
- clone courses as next priority (with a "we will email you" message, because course cloning takes time)
- add all the other users over time

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.

The API assumes all data sent is in JSON format, except for GET requests. Use standard Query String parameter formats for GET requests.
The API delivers all responses in JSON format.
For any data requiring URL Encoding on a GET command, you must URL-encode your data before reaching the API entry point on the LearnUpon side.
All requests assume a content type of "application/json", following the ISO standard.
All date/time parameters in returned data use the UTC format YYYY-MM-DDTHH:MI:SSZ, unless otherwise specified.

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'}"

JSON and UTF-8 syntax

For user data that includes special characters, make sure characters such as apostrophes and fadas are commented out appropriately.

If your source data uses different commenting conventions, test first to confirm the commenting works correctly for uploads.

Example:

"James O'Connor" generates a 400 error in cURL

"James O'\''Connor" is accepted as text in a cURL command

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:

6-30 characters by default
any Unicode alphanumeric character
can use + - . , $ # @ _ .

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

Usernames, set up with customers, are distinct from the user_id, the unique numeric identifier which LearnUpon returns as an attribute when you create a user.

User timezones

The portal's default timezone applies to user profiles for their courses and sessions.

Users can change their timezone manually through their profiles in the portal, to that their courses and sessions show dates and times different form the portal default. See LearnUpon Knowledge Base Your profile: the learner view.

You can also set a user's timezone when you create or update a user, by setting timezone_id. Find the valid timezone IDs from Search for timezones.

Any time someone sets a timezone_id for a user's account, through the UI or through the API, GET /users methods with the optional parameter version_id=1.2 will display the selected timezone in the returned call, even when the timezone matches the portal default.

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.

See JSON and UTF-8 syntax for tips about working with user data containing special characters.

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?version_id=1.2`	Lists all users on the portal, plus `timezone_id` 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/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 attribute


 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 all users: user object includes timezone_id attribute


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

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" }] }

Sometimes called list, or find.

Mandatory parameters for search

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

Optional parameters for search

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
version_id=1.2	string	Includes `timezone_id`in the user object attributes, to indicate a set timezone
login_enabled	boolean	Set to `true` to return enabled users only, set to `false` to return disabled users only

Data objects returned by search

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 of`email`, `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 2026-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2025
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`
timezone_id	string	If set, indicates a timezone for displaying dates and times of courses and sessions. This timezone can match, or be different, from the portal default
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 live learning events. Default is `false`
can_manage_sessions	boolean	Instructor user type only: indicates if the instructor can create and edit sessions within live learning events. 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

A Salesforce Contact is a user who has a sf_contact_id value which matches a Contact record in the Salesforce Organization integrated in the portal.

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"

Data attributes returned from user_id search

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)

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.

Use the definition label as a custom key. For example:

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

Use the definition type_id as the custom data key. In this case, you would use the following flag: use_definition_ids. Example:

"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

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" }}'
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 2026-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2025
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
timezone_id	string	Sets a user's timezone to display dates and times of courses and sessions. Find the valid timezone IDs from Search for timezones
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 live learning events. Default is `false`
can_manage_sessions	boolean	Instructor user type only: indicates if the instructor can create and edit sessions within live learning events. 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	Include 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

You can enter both a sf_contact_id and sf_user_id value if the contact and user records are associated with each other within Salesforce.

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

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" }}'
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 live learning events and sessions


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

Find a user using their user_id, which the API returns when you create a user OR
Enter 0 as user_id, but include email (or username) in the JSON payload, and the API updates the user based on email or username

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:

their associated permissions
their ownership of courses, or live learning events or sessions

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 2026-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2025
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
timezone_id	string	Sets a user's timezone to display dates and times of courses and sessions. Find the valid timezone IDs from Search for timezones
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 live learning events. Default is `false`
can_manage_sessions	boolean	Instructor user type only: indicates if the instructor can create and edit sessions within live learning events. 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

You can enter both a sf_contact_id and sf_user_id value if the contact and user records are associated with each other within Salesforce.

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:

the Portal Invites API endpoint lets you provide additional user attributes; you need a separate API request for each invited user
the Group Invites API endpoint does not allow additional user attributes, like user first and last name; and it lets you invite multiple users in a single API request

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

You can enter both a sf_contact_id and sf_user_id value if the contact and user records are associated with each other within Salesforce.

The expires_at attribute applies to the user account after the user accepts the invite. Required format is yyyy-mm-dd like 2026-04-11. The user's account expires at midnight (UTC) on the date specified, thus: midnight on 11th Apr 2026.

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:

create new enrollments for learners
search for (also called list, find or retrieve) existing enrollments
delete learner enrollments, aka unenroll learners from courses

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
`PATCH /enrollments/{id}`	Update a user's enrollment details. Requires enrollment `id`
`GET /enrollments/{id}`	Searches for a user's enrollments, by enrollment `id`
`GET /enrollments/{id}/modules`	Searches for the modules for a given 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.

For users, you must specify either email or username, as a unique identifier. See Unique identifiers: email or username.
For courses, you must provide either a course name, or a course ID.

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

For course enrollments:

a due date is advisory - the date when the learner should finish the course. After a due date passes, learners can still access the course
an expiry date is a hard requirement. After an expiry date passes, learners lose access to the course

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
due_date	date/time	Set the due date for the enrollment in UTC format of YYYY-MM-DD
expires_at	date/time	Set the expiry date, aka valid period, for the enrollment in UTC format of YYYY-MM-DD

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
user_id	integer	Unique numeric identifier for the user you enrolled

Update an enrollment's details

Updating a user's course enrollment requires the enrollment_id


curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
' { "due_date" : "2025-12-01", "expiry_date" : "2026-04-11"}'
https://yourdomain.learnupon.com/api/v1/enrollments/345678

For existing individual enrollments you can change the enrollment's due date and the expiry date.

Parameter name	Type	Description
due_date	date/time	Set the due date for the enrollment in UTC format of YYYY-MM-DD
expires_at	date/time	Set the expiry date, aka valid period, for the enrollment in UTC format of YYYY-MM-DD

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 list of modules 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/modules

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
modules	string	Returns a list of modules for the enrollment. Requires `{enrollment_id}`

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
calculated_due_date	date/time	In cases of 2 different due dates set through `days_after_enrollment` (number of days) and `date_after_enrollment` (a fixed calendar date), this field defines the correct earliest due date, as shown in the user interface
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
modules	array	A list of module details for the given `{enrollment_id}`

modules data attributes returned by enrollment_id

Attribute name	Type	Description
id	integer	Unique numeric identifier for the module
title	string	Name of the module that appears to learners in the interface
sequence	integer	Order in which the module appears in the enrollment
date_started	date/time	The date the learner started the module, in UTC format
date_completed	date/time	The date the learner finished the module, in UTC format
date_lastaccessed	date/time	The date the learner last accessed the module, in UTC format
status	string	Current status of the module, one of `not_started`, `in_progress`, `completed`, `passed`, `failed` or `pending_review`

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):

exam and survey settings
exam questions, and answers by learners
exam specific enrollment data

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,
            "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
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 search for, view and 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

Sample returned attributes for Mark Completes

{
    "markcompletes": [
           {
            "id": 565479,
            "percentage": 100,
            "user_id": 291165,
            "notes": "Test course completion email",
            "enrollment_id": 20815595,
            "status": "passed",
            "action_source_type": "UI",
            "created_at": "2025-04-08T15:17:53Z",
            "date_completed": "2025-04-07T15:00:00Z"
        },
        {
            "id": 654479,
            "percentage": null,
            "user_id": 291165,
            "notes": "Completion to test learning journey",
            "enrollment_id": 19723966,
            "status": "completed",
            "action_source_type": "UI",
            "created_at": "2025-09-12T20:58:57Z",
            "date_completed": "2025-09-12T15:00:00Z"
        },

    ]
}

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
enrollment_id	integer	Unique numeric identifier for enrollment, created when you enrolled users onto a course. See Enrollments
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

Assignments and assignment answers

The assignments resource let you search (list):

all answers for a specific assignment
individual answers for a specific assignment

LearnUpon assignment settings let instructors set up automated acknowledgements and feedback when learners submit an assignment. See Assignments: create an assignment for a course in the Knowledge Base.

Methods: assignments and assignment answers

Method	Description of output
`GET /assignments/{assignment_id}/answers`	Searches for all the answers for a specific assignment
`GET /assignments/{assignment_id}/answers/{answer_id}`	Searches for specific answers on a specific assignment

Find all answers for a given assignment

Retrieve the answers all learners have submitted for a specific assignment. This endpoint includes the user_id for each learner and for the instructor reviewing assignments, but no names or email addresses.

For assignment modules, the assignment_id is the same as the module_id.

Use GET /modules to find the relevant module ID. See Search for modules.

Alternately, from webhooks v 2.0, the module completion webhook provides a moduleID that serves as assignment_id for this API endpoint.

Retrieve all answers for an assignment by assignment_id

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

Sample returned attributes for an assignment. This assignment included auto-feedback and marking

{
    "assignment_answers": [
        {
            "id": 165108,
            "answer": "<p>Please see attached document for full response</p>\n",
            "feedback": "<p>Thanks for submitting your assignment.</p>\n",
            "score": 100,
            "status": "passed",
            "user_id": 290809,
            "reviewed_at": "2024-08-01T19:29:21Z",
            "assignment_id": 3606955,
            "answer_submitted_at": "2024-08-01T19:29:21Z",
            "was_rejected": false,
            "rejected_at": null,
            "was_autocompleted": true,
            "reviewed_by_user_id": null,
            "rejected_by_user_id": null
        },
        {
            "id": 165807,
            "answer": "<p>I've attached a CSV with my answers included.</p>\n",
            "feedback": "<p>Thanks for submitting your assignment.</p>\n",
            "score": 100,
            "status": "passed",
            "user_id": 2859329,
            "reviewed_at": "2024-08-06T14:54:37Z",
            "assignment_id": 3606955,
            "answer_submitted_at": "2024-08-06T14:54:37Z",
            "was_rejected": false,
            "rejected_at": null,
            "was_autocompleted": true,
            "reviewed_by_user_id": null,
            "rejected_by_user_id": null
        }
    ]
}

Assignment attributes returned

Attribute name	Type	Description
assignment_answers	object	An object containing the data about each asssignment answer

assignment_answers object attributes

Attribute name	Type	Description
id	integer	Unique identifier for the learner's answer to this assignment
answer	string	Text of the answer provided by the learner
feedback	string	Text of the feedback provided by the instructor, or the automated acknowledgement
score	integer	Numeric result for the assignment
status	string	Module status for the assignment, one of `not_started`, `in_progress`, `completed`, `passed`, `failed` or `pending_review`
user_id	integer	Unique numeric identifier for the learner creating the assignment
reviewed_ at	date/time	The date when the assignment was reviewed by the instructor, in UTC format
assignment_id	integer	Unique numeric identifier for each assignment. For assignment modules, the `assignment_id` is the same as the `module_id`
answer_submitted_at	date/time	The date when the learner submitted the assignment
was_rejected	boolean	Indicates if a learner's assignment is rejected. Default is `false`
rejected_at	date/time	The date when an assigment is rejected by an instructor, if applicable. Can be `null`
was_autocompleted	boolean	Indicates if an assignment's review was was autocorrected, aka assigned a default score and sent an automated acknowledgement for submitting the assignment. Default is `false`
reviewed_by_user_id	integer	Unique numeric identifier for the instructor reviewing the assignment, if applicable. Can be `null`
rejected_by_user_id	integer	Unique numeric identifier for the instructor who rejected the assignment, if applicable. Can be `null`

Find an individual learner's answer to an assignment

Retrieve an individual learner's answer to an assignment. This endpoint includes the user_id for the learner and for the instructor reviewing assignments, but no names or email addresses.

The answer_id is available from the GET /assignments/{assignment_id}/answers endpoint.

Retrieve one answer for an assignment by answer_id

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

Sample returned attributes for a single learner's answer

{
    "assignment_answer": {
        "id": 165108,
        "answer": "<p>Please see attached document for full response</p>\n",
        "feedback": "<p>Thanks for submitting your assignment.</p>\n",
        "score": 100,
        "status": "passed",
        "user_id": 290809,
        "reviewed_at": "2024-08-01T19:29:21Z",
        "assignment_id": 3606955,
        "answer_submitted_at": "2024-08-01T19:29:21Z",
        "was_rejected": false,
        "rejected_at": null,
        "was_autocompleted": true,
        "reviewed_by_user_id": null,
        "rejected_by_user_id": null
    }
}

assignment_answer attributes returned

Attribute name	Type	Description
assignment_answer	object	An object containing the data about a single asssignment answer

assignment_answer object attributes

Attribute name	Type	Description
id	integer	Unique identifier for the learner's answer to this assignment
answer	string	Text of the answer provided by the learner
feedback	string	Text of the feedback provided by the instructor, or the automated acknowledgement
score	integer	Numeric result for the assignment
status	string	Module status for the assignment, one of `not_started`, `in_progress`, `completed`, `passed`, `failed` or `pending_review`
user_id	integer	Unique numeric identifier for the learner creating the assignment
reviewed_ at	date/time	The date when the assignment was reviewed by the instructor, in UTC format
assignment_id	integer	Unique numeric identifier for each assignment. For assignment modules, the `assignment_id` is the same as the `module_id`
answer_submitted_at	date/time	The date when the learner submitted the assignment
was_rejected	boolean	Indicates if a learner's assignment is rejected. Default is `false`
rejected_at	date/time	The date when an assigment is rejected by an instructor, if applicable. Can be `null`
was_autocompleted	boolean	Indicates if an assignment's review was was autocorrected, aka assigned a default score and sent an automated acknowledgement for submitting the assignment. Default is `false`
reviewed_by_user_id	integer	Unique numeric identifier for the instructor reviewing the assignment, if applicable. Can be `null`
rejected_by_user_id	integer	Unique numeric identifier for the instructor who rejected the assignment, if applicable. Can be `null`

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`
`POST /courses/{id}/assign_certificate`	add a certificate to a course. Requires `course_id` and `certification_guid`
`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

Data objects returned by search

Attribute name	Type	Description
courses	object	An object containing the list of courses.
customDataFieldDefintions	array	An array containing the list of custom course data field definitions. Returned only when the portal admin has defined 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.

Note: The returned attributes include data about how many users are on a particular course status. The course status numbers tell you how many users are on a single status: for example, num_enrolled and num_in_progress refer to users in Enrolled and In Progress statuses only, and do not include deleted users.

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
course_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	array	An array containing the list of custom course data fields

customDataFieldDefintions array definitions for course data

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

For setting valid dates for courses with date_after_enrollment parameter: access to the course expires at 11 AM on the date specified, in the timezone of the person who sets the date.

When someone with course permissions sets or edits the date, their timezone applies to the valid period for this course.

To create courses for use across a number of timezones, like across Europe or across the continental US, look carefully at your timezone, and consider when you want courses to expire for learners.

See LearnUpon's Knowledge Base Manage course due dates and valid periods for background.

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
course_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
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
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.

For the in_progress_logic attribute: if you move users with In Progress status to a new version of a course, they must restart their courses. Their progress is not retained.

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:

from a top-level portal to a sub-portal
within a single portal - for example, make copies of a one course you're using as a template

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

Add a certificate to a course

Assign existing certificates, previously created through the interface, to your courses.

This option requires Certificate Editor Redesign turned on in the portal. Contact the support team as required.

Add a certificate to a course

curl  -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{"certification_guid": "6377075f-4abd-11ef-97d5-06c3fede0100", "certification_expires_days": 180, 
"recertify_when_expires": true, "recertify_days_before_expires": 30}'
https://yourdomain.learnupon.com/api/v1/courses/345678/assign_certificate

Confirmation of adding certificate to a course

{
    "message": "Certificate assigned successfully"
}

Mandatory parameters to add certificates 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
certification_guid	string	Unique alphanumeric identifier for the certificate. Find this value from `GET /certifications` endpoint. See: Certifications

Optional parameters to add certificates to courses

Parameter name	Type	Description
certification_expires_days	integer	Number of days before the certificate expires
recertify_when_expires	boolean	Indicates if the application will automatically re-enroll the learner for this certification. Default is `false`
recertify_days_before_expires	integer	Number of days to re-enroll the learner before the certificate expries. Default `0`
certification_guid	string	Globally unique alphanumeric identifier for the certificate

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:

get learner enrollments by course ID, to find each learner's enrollment ID. See Search for enrollments
unenroll learners based on their enrollment ID. See Delete enrollments
delete the course

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:

list the modules that are in your content library: this action provides id for other API calls
list the modules associated with a specific course
for live learning events, list the individual sessions associated with a module
create modules with audio and video attachments and publish them. To add these modules to a course see Add a module to a course
clone a module from one course to another

Note: From 7 March 2022, LearnUpon is changing the way moduleid works, to support live learning. When used with live learning events only, the module id identifier will not be unique. The API will provide the same module id to multiple sessions within an event.

See Live learning: overview and features in LearnUpon's Knowledge Base to learn more.

For all other module types, 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 a live learning event
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	Live learning events: if the session has a location specified, this field holds a unique numeric identifier for that location
location	string	Live learning events: if the session has a location specified, this field holds the name of that location
address_1	string	Live Learning events: location address field 1
address_2	string	Live Learning events: location address field 2
address_3	string	Live Learning events: location address field 3
location_state_code	string	Live Learning events: location state code
location_country_code	string	Live Learning events: country code, ex: "IE" for Ireland, "US" for United States, "GB" for Great Britain
start_at	date/time	Live Learning events: UTC starting date/time for ILT session
end_at	date/time	Live Learning events: UTC ending date/time for ILT session
timezone	string	Live Learning events: 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	Live Learning events: number of learners enrolled
max_capacity	integer	Live Learning events: max number of learners who can enroll
session_tutor_id	integer	Live Learning events: 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	Live Learning events: First name of the tutor
tutor_last_name	string	Live Learning events: Last name of the tutor
tutor_email	string	Live Learning events: Email of the tutor
tutor_username	string	Live Learning events: Username of the tutor: appears only if your portal uses usernames. See Unique identifiers: email or usernames
training_id	integer	Live learning: Numeric identifier for the live learning event. One `training_id` can be associated with many `session_id`. Value can be null, for sessions not created through live learning
session_id	integer	Live learning: Unique numeric identifier for an individual live learning session. Value can be null, for sessions not created through live learning

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

Note: You must provide one of the video_url or audio_url parameters. If you provide both parameters, then the created module contains video only.

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:

list the resources that are in the portal library: this action provides id for other API calls
create linked resources from a top level portal to a sub-portal
remove linked resources from sub-portals

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
        }
    ]
}

Data attributes returned for resources search

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

Link a resource from a top-level portal to a sub-portals

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.

Mandatory parameters to link a resource

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

Licenses for courses

When you create a course license, you publish an existing course from your top-level portal to a sub-portal, while controlling access to the course. A licensed course is not editable in the sub-portal.

For background see the Knowledge Base articles about sub-portal management and licensing.

The /licenses resource lets you view, add, update and delete licenses from published courses already in your portal. You can't license courses in Draft status.

Licenses are assigned per sub-portal, each with a unique license_id. A course licensed to multiple sub-portals has a single course_id across the realm, and a separate license_id per portal.

Methods: course licenses

Method	Description of output
`GET /licenses`	Search for course licenses within your realm. Narrow the search by `portal_id`, `course_id`, and `page`
`GET /licenses?course_id={course_id}`	Search for all licenses for a single course across the realm
`GET /licenses/{license_id}`	Search for an individual license for a single portal
`POST /licenses`	Create licenses for 1+ courses for 1+ sub-portals
`PUT /licenses/{license_id}`	Update an existing license
`DELETE /licenses/{license_id}`	Delete a license

Search for course licenses

List licences for your realm


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

Find a license by course_id


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

Find a license by license_id


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

Sample response to finding a license by license_id

{
    "license": 
    {
        "id": 233400,
        "course_id": 4754400,
        "portal_id": 158500,
        "expiry_date": null,
        "created_at": "2026-01-06T18:31:19Z",
        "updated_at": "2026-01-06T18:31:19Z",
        "learner_limit": null,
        "allow_managers_to_enroll_learners": true,
        "resale_option": "not_allowed"
    }
}

Optional parameters for course license search

Parameter name	Type	Description
course_id	integer	Course's unique numeric identifier
portal_id	integer	Unique numeric identifier for the portal
page	integer	Page number for results. See Data pagination

Data attributes for course licenses returned

Attribute name	Type	Description
id	integer	Unique numeric identifier for the license, assigned per portal
course_id	integer	Course's unique numeric identifier. This ID stays consistent across portals
portal_id	integer	Unique identifier for the sub-portal
expiry_date	date/time	Date/time the license expires, in UTC format. Can be `null`
learner_limit	integer	Number of license seats allowed per portal. Can be `null`
created_at	string	Date the course was created, requires yyyy-mm-ddThh:m:s format
updated_at	string	Date the course was last updated, requires yyyy-mm-ddThh:m:s format
allow_managers_to_enroll_learners	boolean	Sets permission for managers on the sub-portal to enroll learners
resale_option	string	Sets permission to sell the course from the sub-portal. One of `not_allowed`, `allowed_without_price_change`, `allowed_with_price_change`

Create course licenses

You can set up licenses for multiple courses and multiple sub-portals at once.

Create course licenses


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{"course_ids": [4754430, 4381339],"portal_ids": [16196],"expiry_date": "2027-12-31","learner_limit": 50,"allow_managers_to_enroll_learners": true,"resale_option": "allowed_without_price_change"}'  https://yourdomain.learnupon.com/api/v1/licenses

Mandatory parameters to create course licenses

Parameter name	Type	Description
course_ids	array, integers	List of courses by `course_id`
portal_ids	array, integers	List of portals by `portal_id`
expiry_date	date/time	Default `null`, aka unlimited use. Date/time the license expires, in UTC format
learner_limit	integer	Default `null`, aka unlimited learners. Number of license seats allowed per portal
allow_managers_to_enroll_learners	boolean	Default `false`. Allows managers on the sub-portal to enroll learners
resale_option	string	Default `not_allowed`. Sets permission to sell the course from the sub-portal. One of `not_allowed`, `allowed_without_price_change`, `allowed_with_price_change`

Data attributes returned for creating course licenses

Attribute name	Type	Description
licenses	array	Data for each license_id and portal

licenses array definitions for license data

Attribute name	Type	Description
id	integer	Unique numeric identifier for a course license
course_id	integer	Course's unique numeric identifier. This ID stays consistent across portals
portal_id	integer	Unique identifier for the sub-portal
expiry_date	date/time	Date/time the license expires, in UTC format. Can be `null`
learner_limit	integer	Number of license seats allowed per portal. Can be `null`
allow_managers_to_enroll_learners	boolean	Sets permission for managers on the sub-portal to enroll learners
resale_option	string	Sets permission to sell the course from the sub-portal. One of `not_allowed`, `allowed_without_price_change`, `allowed_with_price_change`

Update course licenses

You can edit licenses, adding the license_id to the endpoint.

The data returned is the same as for creating licenses, confirming the changed parameters.

Update a course license


curl -X PUT -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{"expiry_date": "2028-12-31","learner_limit": 200,"allow_managers_to_enroll_learners": false,"resale_option": "allowed_with_price_change"}'  https://yourdomain.learnupon.com/api/v1/licenses/176900

Data attributes returned for updating course licenses

See Data attributes returned for creating course licenses.

Delete a course license

You can delete a license, adding the license_id to the endpoint. Deleting an individual license doesn't affect the course in the top-level portal, and doesn't affect licenses for other sub-portals.

Delete a course license


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

https://yourdomain.learnupon.com/api/v1/licenses/176900

Live Learning

See:

For Live Learning, the events provide containers to hold sessions, and metadata that applies to all sessions. Events are the equivalent of modules for other content types. You set the following parameters at the event level:

event type of individual sessions, or a series of sessions. This type determines many of the parameters available for the event, and for associated sessions
event ownership
instructors assigned to the event
event access, aka visibility: accessible to all users, or limited to course owners and session instructors
for session series: the number of sessions, and their attendance requirements
how to register - automated, manual or self-serve
whether or not overbooking is available
whether or not a waitlist is available
completion requirements for the session
attendance requirements
notification settings

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

You set the minimum attendance threshold in the event, and it applies to each associated session. Optionally, you can overwrite the attendance 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 event's parameters, or other sessions in the Live Learning event. You can't overwrite the threshold for single-day sessions, aka sessions less than 24 hours long.

Within the event, you create an unlimited number of sessions.

For Live Learning, you set the following parameters at the session level for the session format:

session type, one of webinar or classroom. The user interface refers to online and in person respectively
instructor name(s)
primary instructor, whose name goes on notifications
locations for classroom, for in-person sessions
dates and times, with associated timezones
connection details as required for webinars
attendance capacity
session waitlist, if turned on
session visibility, with the option to limit visibility by learner group
any custom session data

You must define custom session data through the application interface. See Live learning: set up custom session data fields.

Identifier options for Live Learning calls

Live Learning event owners

Each Live Learning event requires at least 1 owner. Multiple owners are allowed.

You identify event 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:

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

Event 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:

instructor_user_ids
instructor_emails
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, email or 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:

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

Event session attendees, aka learners

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

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

Permissions for Live Learning event owners and instructors

Live Learning event owners require user type permissions to create and edit events.

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 Live Learning.

Methods: Live Learning events

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

Method: GET, for individual session data	Description of output
`GET /live-learnings/sessions/search?course_id=`	Searches by parameters like `course_id`
`GET /live-learnings/sessions/search?location_id=`	In person: searches by `location_id`
`GET /live-learnings/sessions/search?instructor_user_id=`	Searches by `instructor_user_id`
`GET /live-learnings/sessions/search?course_status=`	Searches by `course_status`
`GET /live-learnings/sessions/search?start_date=`	Searches by `start_date`
`GET /live-learnings/sessions/search?end_date=`	Searches by `end_date`
`GET /live-learnings/sessions/search?event_id=`	Searches by Live Learning `event_id`
`GET /live-learnings/sessions/list`	Returns all individual sessions on the portal
`GET /live-learnings/sessions/list?course_id=`	Lists individual sessions by `course_id`
`GET /live-learnings/sessions/list?location_id=`	Lists indivdiual sessions by `location_id`
`GET /live-learnings/sessions/list?instructor_user_id=`	Lists individual sessions by `instructor_user_id`
`GET /live-learnings/sessions/list?course_status=`	Lists individual sessions by `course_status`
`GET /live-learnings/sessions/list?start_date=`	Lists individual sessions by `start_date`
`GET /live-learnings/sessions/list?end_date=`	Lists individual sessions by `end_date`
`GET /live-learnings/sessions/list?event_id=`	Lists individual sessions by `event_id`
`GET /live-learnings/events/{event_id}/sessions/{session_id}`	Search for the details for a specific session, including webinar URL
`GET /live-learnings/sessions/{session_id}/attendance`	Lists attendance for a specific session
`GET /live-learnings/custom_session_data_definitions/list`	Lists the definitions for custom session data

Method: GET, for events	Description of output
`GET /live-learnings/events/{event_id}`	Search for event details by `event_id`, including `session_series_tags`

Method: GET, for session series data	Description of output
`GET /live-learnings/session-series/search?course_id=`	Searches for a session series by parameters like `course_id`
`GET /live-learnings/session-series/search?location_id=`	In person: searches by `location_id`
`GET /live-learnings/session-series/search?instructor_user_id=`	Searches by `instructor_user_id`
`GET /live-learnings/session-series/search?course_status=`	Searches by `course_status`
`GET /live-learnings/session-series/search?start_date=`	Searches by `start_date`
`GET /live-learnings/session-series/search?end_date=`	Searches by `end_date`
`GET /live-learnings/session-series/search?event_id=`	Searches by Live Learning `event_id`
`GET /live-learnings/session-series/{id}`	Searches for a session series by `session_series_id`

Method: GET, for learners' session data	Description of output
`GET /live-learnings/learners/{user_id}/sessions`	Find a learner's scheduled sessions and their status

Method: POST, for events	Description of output
`POST /live-learnings/events/`	Creates a Live Learning event, either individual sessions or session series. Default event has individual sessions

Method: POST, for events with individual sessions	Description of output
`POST /live-learnings/events/{event_id}/sessions`	Creates individual sessions within an event
`POST /live-learnings/sessions/{session_id}/add_to_session`	Adds a learner to a specific session and, if not already enrolled, to a course
`POST /live-learnings/events/{event_id}/sessions/{session_id}/mark_attendance`	Marks attendance for a specific session
`POST /live-learnings/events/{event_id}/sessions/{session_id}/cancel_registration`	Cancels a learner's registration to a specific session
`POST /live-learnings/events/{event_id}/sessions/{session_id}/cancel`	Cancels a specific session

Method: POST, for events with a series of sessions	Description of output
`POST /live-learnings/events/{event_id}/session-series`	Creates a session series for an existing event
`POST /live-learnings/events/{event_id}/session-series/{session_series_id}/part/{session_detail_id}/mark_attendance`	Marks attendance for a session series
`POST /live-learnings/events/{event_id}/session-series/{id}/cancel`	Cancels a session series

Method: PUT, for events with individual sessions	Description of output
`PUT /live-learnings/events/{event_id}`	Updates a Live Learning event
`PUT /live-learnings/events/{event_id}/sessions/{session_id}`	Updates a specific session

Method: PUT, for events with a series of sessions	Description of output
`PUT /live-learnings/events/{event_id}/session-series/{id}`	Updates a session series
`PUT /live-learnings/events/{event_id}/session-series/{id}/part`	Updates a part of the session series

Methods for Live Learning metadata

These methods provide data for your Live Learning call parameters.

Method: GET	Description of output
`GET /timezones`	Searches for the timezones available in your portal
`GET /locations`	Classroom and in person sessions only. Searches for the course locations available in your portal

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 Live Learning events and individual sessions

Search for Live Learning sessions, using course_id


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

Search for Live Learning sessions, using instructor_user_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/live-learnings/sessions/search?instructor_user_id=29125

Search for Live Learning sessions, 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/live-learnings/sessions/search?course_status=1

Search for Live Learning sessions, using location_id

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

Search for Live Learning sessions, using start date and end date together


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

Search for Live Learning sessions, using event_id


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

Search using course_status does not find courses in draft status.

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_user_id	integer	`user_id` of an instructor
course_status	integer	One of: 1=published, 2=under revision, 3=archived
location_id	integer	In person or classroom only. A unique identifier for a physical address for sessions. See Search for locations
event_id	integer	Unique identifier for the Live Learning event. See Create a Live Learning event
page	integer	Page number for results. See Data pagination

Data attributes returned for search for Live Learning events and sessions

Attribute name	Type	Description
course_id	integer	Unique identifier for the course
course_name	string	Course name
component_title	string	Title of the Live Learning event
description	string	Description of the Live Learning event
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 Live Learning event 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. See Search for locations. 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
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL
session_id	integer	Unique numeric identifier for an individual Live Learning 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 event title

List Live Learning events and sessions

The GET /live-learnings/sessions/list endpoint returns results similar to the GET /live-learnings/events/{event_id}/sessions/{session_id} endpoint, with the results for /list formatted in an array. See Search for Live Learning event session details to compare results.

This endpoint does not return results for Live Learning session series: available for individual sessions only.

List Live Learning sessions, using course_id


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

List Live Learning sessions, using instructor_user_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/live-learnings/sessions/list?instructor_user_id=29125

List Live Learning sessions, 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/live-learnings/sessions/list?course_status=1

List Live Learning sessions, using location_id

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

List Live Learning sessions, using start date and end date together


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

List Live Learning sessions, using event_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/live-learnings/sessions/list?event_id=359415

Sample returned attributes for listing Live Learning sessions using event_id


{
    "message": "success",
    "sessions": [
        {
            "id": 1333330,
            "portal_id": 45678,
            "event_id": 871720,
            "max_capacity": 3,
            "min_capacity": null,
            "title": "Event with session options for select topics, September Mountain timezone",
            "num_enrolled": 0,
            "minimum_attendance_threshold": 75,
            "completion_requirement": "attendance required",
            "description_html": "<p>Session options let you set up multiple sessions and enroll learners in all sessions at once.</p> ",
            "description_text": "Session options let you set up multiple sessions and enroll learners in all sessions at once. ",
            "minimum_attendance_threshold_enabled": true,
            "start_time": "2025-09-10T04:00:00",
            "end_time": "2025-09-10T05:00:00",
            "timezone": "(GMT-07:00) Arizona",
            "location_id": -1,
            "instructors": [
                {
                    "user_id": 123456,
                    "first_name": "Beatrice",
                    "last_name": "Dansk",
                    "email": "beatrice.dansk@yourdomain.com",
                    "is_primary": true,
                    "username": null
                }
            ],
            "webinar_url": null,
            "address_1": null,
            "address_2": null,
            "address_3": null,
            "location": "Webinar",
            "session_type": "webinar"
        }
    ]
}

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_user_id	integer	`user_id` of an instructor
course_status	integer	One of: 1=published, 2=under revision, 3=archived
location_id	integer	In person or classroom only. A unique identifier for a physical address for sessions. See Search for locations
event_id	integer	Unique identifier for the Live Learning event. See Create a Live Learning event
page	integer	Page number for results. See Data pagination

Data attributes returned for listing Live Learning individual sessions

Attribute name	Type	Description
sessions	array	Array containing the session details

sessions array definitions for session data

Attribute name	Type	Description
id	integer	Unique numeric identifier for a session. This ID is part of the URL
portal_id	integer	Unique identifier for the portal
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the URL
title	string	Title of the session
description_html	string	Description of the session in HTML
description_text	string	Description of the 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 session. Advisory only
max_capacity	integer	Maximum number of attendees on this 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	array	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

Search for Live Learning individual 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 event_id and session_id forms part of the URL for this endpoint.

cURL to search for an event session

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

Response to search for a specific session

{
"session":{"id":390349,"portal_id":45678,"event_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":[{"user_id":654321,"first_name":"Berengar","last_name":"Hesse","email":"berengar.hesse@yourdomain.com","is_primary":true},{"user_id":123456,"first_name":"Beatrice","last_name":"Dansk","email":"beatrice.dansk@yourdomain.com","is_primary":false}]}}
}

Mandatory parameters for searching for a Live Learning session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL
session_id	integer	Unique numeric identifier for an individual Live Learning session. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning events and sessions

Data attributes returned for search for Live Learning session

Attribute name	Type	Description
id	integer	Unique numeric identifier for an individual event session. This ID is part of the URL
portal_id	integer	Unique identifier for the portal where the session exists
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the URL
title	string	Title of the event session
description_html	string	Description of the session in HTML
description_text	string	Description of the 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 session. Advisory only
max_capacity	integer	Maximum number of attendees on this 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	array	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

Instructors array attributes for Live Learning

Attribute name	Type	Description
user_id	integer	`user_id` of the 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 Live Learning session attendance

After searching for a 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/live-learnings/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 session attendance

Parameter name	Type	Description
session_id	integer	Unique numeric identifier for an individual event session

Data attributes returned for 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 event session
enrollment_data	array	List of enrollment data for a specific event session

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

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 event session
enrollment_status	integer	See the following session 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`

Session 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

Search for custom session data definitions for Live Learning sessions

Sample search for Live Learning custom session data definitions


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

Sample returned data definitions for 2 fields


{
    "message": "success",
    "custom_session_data_definitions": [
        {
            "id": 29950,
            "type_id": 1,
            "label": "Client code"
        },
        {
            "id": 29949,
            "type_id": 4,
            "label": "Cost center",
            "predefined_values": [
                "Accounts",
                "Sales",
                "Success",
                "Onboarding",
                "Engineering",
                "Quality assurance",
                "Operations",
                "Marketing"
            ]
        },

    ]
}

This method returns the definitions for custom session data, similar to definitions for custom user data.

They use the same data_type IDs as in custom user data. See type_id attribute definitions.

Custom session data fields are optional fields you define in the portal to associate additional custom data to individual sesssions. You can use these definitions to create sessions including custom session data through the API.

You must define custom session data through the application interface. See Live learning: set up custom session data fields.

This method has no additional parameters.

Data attributes returned for custom session data search

Attribute name	Type	Description
message	string	confirmation text of search result
custom_session_data_definitions	array	An array containing the list of custom user data fields as individual objects

custom_session_data_definitions object values

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

Search for Live Learning events and associated details

Search for Live Learning events, using event_id


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

This endpoint is the best way to find session_series_tags for a series of sessions. With these tags you can schedule additional series of sessions for an existing event, using POST /live-learnings/events/{event_id}/session_series

Mandatory parameters for searching for a Live Learning event

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL

Data attributes returned for event search

Attribute name	Type	Description
id	integer	Unique numeric identifier for an individual event. This ID is part of the URL
portal_id	integer	Unique identifier for the portal
title	string	Title of the event
description	string	Description of the event
created_at	string	Date the session was created, requires yyyy-mm-ddThh:m:s format
updated_at	string	Date the session was updated, requires yyyy-mm-ddThh:m:s format
waitlist_status	integer	Shows waitlist option is on or off. 0=Disabled (default), 1 =Enabled
completion_requirement	integer	Event 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 the event
session_registration_choice	integer	Available options: 0=automatic, 1=manual (default) num_not_registered
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`
num_of_uses	integer	Number of times an event with session series has been part of a course
session_type	string	Accespted values are `0` or `individual` for individual sessions, and `1` or `series`for session series
concurrent_registration	boolean	Individual sessions only. `0` = learners are registered 1 session at a time, `1`= learners are registered for multiple sessions at a time
access_option	boolean	Individual sessions only. Defines the timeframe for registrations. `0`= allow registration until requirements are met; applies only if `completion_requirement`=1 (Join the session) or =2 (Minimum attendance threshold). `1`= allow registration indefinitely; applies only if `completion_requirement`=0. `2`= allow registration for number of days set in `registration_days_after_enrollment`. `3`= allow registration for a number of attempts, set in `optional_sessions_attend_count`
individual_sessions_required_count	integer	Individual sessions only. Number of sessions required to complete the event
optional_sessions_attend_count	integer	Limit of sessions learners can attend
registration_days_after_enrollment	integer	Max number of days when a learner can register for a session
visibility	boolean	Visibility of the event and its sessions within the portal. Default is`0`= all users. `1`= course owners and session instructors only
session_series_tags	array	Session series only. Array containing details for the topics in the series
has_sessions	boolean	Indicates if the event has any sessions scheduled. Default is `false`
has_session_attendees	boolean	Indicates if any learners are registered for any sessions. Default is `false`
owners	array	Array containing details of the event owners
instructors	array	Array containing details of the event instructors
session_registration	array, string	Contains `learner_can_choose_session` or `learner_can_cancel_registration` as plain strings, when these parameters are `true`
notifications	object	Contains data related to automated notifications about the event

Owners array data attributes

Attribute name	Type	Description
full_name	string	Owner name
pm_id	integer	Portal membership ID
image_url	string	URL to the profile image for the owner avatar

Instructors array data attributes

Attribute name	Type	Description
full_name	string	Owner name
pm_id	integer	Portal membership ID
image_url	string	URL to the profile image for the owner avatar

Notifcations object data attributes

Attribute name	Type	Description
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`

Search for Live Learning session series

Search for Live Learning session series, using course_id


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

Search for Live Learning sessions, using instructor_user_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/live-learnings/session-series/search?instructor_user_id=29125

Search for Live Learning sessions, 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/live-learnings/session-series/search?course_status=1

Search for Live Learning sessions, using location_id

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

Search for Live Learning sessions, using start date and end date together


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

Search for Live Learning sessions, using event_id


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

This endpoint returns the details about events with a series of sessions, rather than individual sessions.

Optional 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_user_id	integer	`user_id` of an instructor
course_status	integer	One of: 1=published, 2=under revision, 3=archived
location_id	integer	In person or classroom only. A unique identifier for a physical address for sessions. See Search for locations
event_id	integer	Unique identifier for the Live Learning event. See Create a Live Learning event
page	integer	Page number for results. See Data pagination

Data attributes returned for search for Live Learning session series

Attribute name	Type	Description
training_id	integer	Unique identifier for the Live Learning event. `training_id` and `event_id` are the same number, used in different calls
training_session_id	integer	Unique identifier for the Live Learning sessions that are part of a series. Individual sessions have `session_id`
portal_id	integer	Unique identifier for the portal
title	string	Title of the series of sessions, within the Live Learning event
description_html	string	HTML description of the session series
description_text	string	Text description of the session series
num_enrolled	integer	number of learners enrolled in the session series
min_capacity	integer	Minimum number of attendees on this event session. Advisory only
max_capacity	integer	Maximum number of attendees on this event session
completion_requirement	string	One of attendance optional or attendance required
minimum_attendance_threshold	integer	A percentage of the event session the learner must attend, set in the associated training. Applies only if minimum attendance is turned on at the portal level
reference_name	string	Name of the Live Learning event
session_parts	array	Array of session details, including instructor details and any custom session data

Session parts attributes for session series

Attribute name	Type	Description
session_parts_id	integer	Unique numeric identifier for the session part within the series
start_time	string	Start date of the session, requires yyyy-mm-ddThh:m:s format
end_time	string	End date of the session, requires yyyy-mm-ddThh:m:s format
timezone	string	Timezone of the session
timezone_id	string	Session timezone. Required for webinar sessions. For in-person sessions the API uses `location_id` if available to provide a timezone
environment_type	integer	virtual=`0`, in_person=`1`, custom_virtual=`2`
location_id	integer	Unique numeric identifier for the location. Returns `-1` if location is not selected. Can be `null` for online sessions
session_type	string	One of: classroom, webinar
location	string	Name of the location. Returns `webinar` for all online sessions, and `N/A` if no in-person location is selected
webinar_url	string	URL for accessing a session: either a webinar URL, or custom URl
webinar_account_id	integer	Unique numeric identifier for the webinar account
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
qr_before_start_mins	integer	In-person sessions only: number of minutes before a session when learners can self-register through a QR code
qr_after_end_mins	integer	In-person sessions only: number of minutes after a session when learners can self-register through a QR code
qr_confirmation_type	integer	In-person sessions only: indicates if the session requires a confirmation code for login. Default is `0`, no confirmation required
tags	array	Details for the topics in the series
instructors	array	An array containing instructor details
custom_session_data	array	An array containing custom session data, if available

Tags attributes for session series

Attribute name	Type	Description
id	integer	Unique numeric identifier for the individual session within the series, aka the session topic
name	string	Session title
required_attendance	boolean	Indicates if attendance is required. Default `false`
sequence	integer	Assigns the order in which the sessions run for learners. Numbers from 0 onward

Custom session data attributes for session series

Custom session data fields in LearnUpon let you associate individual sessions with details like cost codes, customer names, or similar session-level data. These fields are not visible to learners.

You must define custom session data through the application interface. See Live learning: set up custom session data fields.

See Search for custom session data definitions for Live Learning sessions.

Attribute name	Type	Description
field_label	string	Name of the custom session field
custom_session_data_definition_id	integer	Unique numeric identifier for the custom session data contained in the associated field
field_value	One of string, string choice, integer, integer choice, decimal, decimal choice	Customer defined

Search for learner sessions and details

You can use 1 of user_id, email or username to search for scheduled sessions associated with an individual learner. This endpoint returns both individual sessions and sessions in series.

See Data pagination for details about handling large volumes of session data returned.

Search for learner sessions


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

https://yourdomain.learnupon.com/api/v1/live-learnings/learners/sessions?user_id=12345

Sample response for search for sessions by user_id

{
    "message": "success",
    "sessions": [
        {
            "id": 2141000,
            "title": "New hire training, Toronto, August 2026",
            "description": "<p>A series of sessions to introduce you to your new organization.</p>\n",
            "registered": true,
            "session_has_capacity": true,
            "learner_can_choose_session": false,
            "learner_can_cancel_registration": true,
            "waitlisted": false,
            "event": {
                "id": 740664,
                "session_type": "session_series",
                "courses": [
                    {
                        "id": 4287523,
                        "name": "New employee orientation through live learning",
                        "enrolled": true
                    }
                ],
                "enrollment": {
                    "status": "in_progress",
                    "sessions_attended": 0,
                    "sessions_required": 0,
                    "sessions_passed": 0
                }
            },
            "min_start_time": "2026-08-10T09:00:00",
            "details": [
                {
                    "id": 2779012,
                    "title": "Physical location, facilities and nearby amenities",
                    "description": "",
                    "environment_type": "classroom",
                    "minutes_attended": 0,
                    "webinar_url": "",
                    "location": {
                        "title": "Toronto office",
                        "address1": "33 Dundas Street East",
                        "address2": "Toronto, Ontario",
                        "address3": "L9H 5R1",
                        "notes": "Online class, Eastern Standard Time"
                    },
                    "attendance": {
                        "status": "unmarked",
                        "completion_status": null
                    },
                    "start_time": "2026-08-10T09:00:00",
                    "end_time": "2026-08-10T10:00:00",
                    "instructors": [
                        {
                            "first_name": "Beatrice",
                            "last_name": "Dansk",
                            "email": "beatrice.dansk@yourdomain.com",
                            "username": "",
                            "is_primary": true,
                            "user_id": 123456
                        }
                    ],
                    "timezone": "Eastern Time (US & Canada)"
                },
                {
                    "id": 2779013,
                    "title": "Payroll and financial details: what you need to provide",
                    "description": "",
                    "environment_type": "classroom",
                    "minutes_attended": 0,
                    "webinar_url": "",
                    "location": {
                        "title": "Toronto office",
                        "address1": "33 Dundas Street East",
                        "address2": "Toronto, Ontario",
                        "address3": "L9H 5R1",
                        "notes": "Online class, Eastern Standard Time"
                    },
                    "attendance": {
                        "status": "unmarked",
                        "completion_status": null
                    },
                    "start_time": "2026-08-11T09:00:00",
                    "end_time": "2026-08-11T10:00:00",
                    "instructors": [
                        {
                            "first_name": "Beatrice",
                            "last_name": "Dansk",
                            "email": "beatrice.dansk@yourdomain.com",
                            "username": "",
                            "is_primary": true,
                            "user_id": 123456
                        }
                    ],
                    "timezone": "Eastern Time (US & Canada)"
                },
                {
                    "id": 2779014,
                    "title": "Health benefits and pension: what you need to know",
                    "description": "",
                    "environment_type": "classroom",
                    "minutes_attended": 0,
                    "webinar_url": "",
                    "location": {
                        "title": "Toronto office",
                        "address1": "33 Dundas Street East",
                        "address2": "Toronto, Ontario",
                        "address3": "L9H 5R1",
                        "notes": "Online class, Eastern Standard Time"
                    },
                    "attendance": {
                        "status": "unmarked",
                        "completion_status": null
                    },
                    "start_time": "2026-08-12T09:00:00",
                    "end_time": "2026-08-12T10:00:00",
                    "instructors": [
                        {
                            "first_name": "Beatrice",
                            "last_name": "Dansk",
                            "email": "beatrice.dansk@yourdomain.com",
                            "username": "",
                            "is_primary": true,
                            "user_id": 123456
                        }
                    ],
                    "timezone": "Eastern Time (US & Canada)"
                },
                {
                    "id": 2779015,
                    "title": "Organization structure and departments",
                    "description": "",
                    "environment_type": "classroom",
                    "minutes_attended": 0,
                    "webinar_url": "",
                    "location": {
                        "title": "Toronto office",
                        "address1": "33 Dundas Street East",
                        "address2": "Toronto, Ontario",
                        "address3": "L9H 5R1",
                        "notes": "Online class, Eastern Standard Time"
                    },
                    "attendance": {
                        "status": "unmarked",
                        "completion_status": null
                    },
                    "start_time": "2026-08-13T10:00:00",
                    "end_time": "2026-08-13T11:00:00",
                    "instructors": [
                        {
                            "first_name": "Beatrice",
                            "last_name": "Dansk",
                            "email": "beatrice.dansk@yourdomain.com",
                            "username": "",
                            "is_primary": true,
                            "user_id": 123456
                        }
                    ],
                    "timezone": "Eastern Time (US & Canada)"
                },
                {
                    "id": 2779016,
                    "title": "Health and safety for new hires",
                    "description": "",
                    "environment_type": "classroom",
                    "minutes_attended": 0,
                    "webinar_url": "",
                    "location": {
                        "title": "Toronto office",
                        "address1": "33 Dundas Street East",
                        "address2": "Toronto, Ontario",
                        "address3": "L9H 5R1",
                        "notes": "Online class, Eastern Standard Time"
                    },
                    "attendance": {
                        "status": "unmarked",
                        "completion_status": null
                    },
                    "start_time": "2026-08-14T11:00:00",
                    "end_time": "2026-08-14T12:00:00",
                    "instructors": [
                        {
                            "first_name": "Beatrice",
                            "last_name": "Dansk",
                            "email": "beatrice.dansk@yourdomain.com",
                            "username": "",
                            "is_primary": true,
                            "user_id": 123456
                        }
                    ],
                    "timezone": "Eastern Time (US & Canada)"
                }
            ]
        }
    ]
}

This endpoint lets you:

find scheduled sessions for an individual learner, by user_id, email or username
track the learner's attendance
for self-registered sessions: find and display sessions available for registration

The endpoint returns all event sessions that a learner is registered for, both individual and series sessions. The session data includes:

session information: title, description, start/end times, capacity, enrollment count
session details: individual session parts (for multi-part sessions), location, timezone, instructors
course information: associated courses and enrollment status
attendance status: if sessions are completed, attended, or upcoming
registration status: if the learner is registered, waitlisted, or can register

Mandatory parameters for a learner's sessions

Requires 1 unique identifier. See Event session attendees, aka learners.

Parameter name	Type	Description
user_id	integer	Unique numeric identifier for the learner, aka a user
email	string	The email of the user
username	string	The username of the user

Optional parameters for a learner's sessions

These parameters filter and sort your results.

Parameter name	Type	Description
with_future_sessions	boolean	Include unregistered future sessions available for registration
with_past_sessions	boolean	Include past sessions. Default shows all registered sessions
date_from	date	Show sessions starting from this date. Required format is YYYY-MM-DD
date_to	date	Show sessions up to this date. Required format is YYYY-MM-DD
search	string	Search sessions by title or description. Example: "Safety Training"
sort	string	Sort order for results. One of `name_asc`, `name_desc`, `start_time_asc`, `start_time_desc`
session_environment	integer	Filter by 1 of `classroom` (in person) or `webinar` (covers both virtual and custom virtual environments)
event_status	integer	Filter by 1 of `in_progress`, `completed`, `failed`
attendance_status	integer	Filter by event completion requirement type, 1 of `no_requirements` or `join_the_session`
session_type	string	Filter by 1 of `single_session` or `session_series`

Data attributes returned for search for a learner's sessions

Attribute name	Type	Description
sessions	array	Contains details about each session where the learner is registered

Learner's sessions array data attributes

Attribute name	Type	Description
id	integer	Unique numeric identifier for a specific session
title	string	Session title
description	string	Session description
registered	boolean	Indicates if the learner is registered for the session
session_has_capacity	boolean	Indicates if the session has seats available
waitlisted	boolean	Indicates if the learner is on the waiting list for the session, because the session is full
learner_can_choose_session	boolean	Indicates if the learner can select a session or is enrolled on the first available session
learner_can_cancel_registration	boolean	Indicates if the learner can cancel their own registration
min_start_time	date/time	Timestamp for earliest start time across all session details
event	object	Contains details about the event that contains the session
details	array	Details about the individual session

Event object data attributes

Attribute name	Type	Description
event_id	integer	Unique identifier for the Live Learning event. `training_id` and `event_id` are the same number, used in different calls
session_type	integer	1 of `single_session` or `session_series`
enrollment	object	Contains details about the session enrollment statuses and requirements
courses	array	List of courses associated with the session, with enrollment details

Enrollment object data attributes

Attribute name	Type	Description
status	string	1 of `in_progress`, `completed`, `failed`
sessions_attended	integer	Number of session parts attended
sessions_required	integer	Number of session parts required
sessions_passed	integer	Number of session parts passed

Learner's course array data attributes

Attribute name	Type	Description
course_id	integer	Unique numeric identifer of the course
name	string	Course name or title
enrolled	boolean	Indicates if the learner is enrolled in the course

Details array data attributes

Attribute name	Type	Description
id	integer	Unique identifier for the session part
title	string	Session part title
description	string	Session part description
environment_type	string	1 of `classroom` or `webinar`
minutes_attended	integer	Number of minutes the learner attended as session
webinar_url	string	Online session URL
start_time	date/time	Timestamp for start time
end_time	date/time	Timestamp for end of session
timezone	string	Timezone supported by the session. See Timezone names
location	object	For in person sessions
attendance	object	Contains details about attendance status
instructors	array	An array containing instructor details

Location object data attributes

Attribute name	Type	Description
title	string	For in person sessions, a location name
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
notes	string	In person sessions: details about the venue

Attendance object data attributes

Attribute name	Type	Description
status	string	1 of `unmarked`, `no_requirements` or `join_the_session`
completion_status	string	1 of `completed`, `failed`, `null`

Create a Live Learning event

Every Live Learning event requires a title and at least 1 owner. Multiple owners are permitted.

All Live Learning events use the same event object. The optional event object parameters define whether the event has individual sessions or a session series.

Unless specified by session_type parameter, Live Learning events default to events for individual sessions.

To create a series of sessions:

in the POST body, include an array called session_series_tags to define each session in the series within the event. At least 1 session in the series must have required attendance
when the POST returns successfully with the event_id, search for the event to find the IDs for each session in the series. See Search for Live Learning events and associated details
with event_id and session_series_tags IDs, use POST to schedule further sessions with the same session details

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

See Identifier options for Live Learning calls for background.

cURL create a new Live Learning event, with response


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

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

Mandatory parameter for creating a Live Learning event

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

Mandatory event object parameters

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

Parameter name	Type	Description
title	string	Title of the Live Learning event
owner_user_ids	array (integer)	`user_id`s of the event owner(s)
owner_emails	array (string)	`email` of the event owner(s)
owner_usernames	array (string)	`username` of the event owner(s), available as alternative to email

Optional Live Learning events object parameters

See Live learning: overview and features in LearnUpon's Knowledge Base to learn more about individual features.

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

Parameter name	Type	Description
instructor_user_ids	array (integer)	`user_id`s of the named event instructor(s)
instructor_emails	array (string)	`email` of the event instructor(s)
instructor_usernames	array(string)	`username`s of the event 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	Event description
completion_requirement	integer	Event 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 the event
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`
session_registration	array, string	Contains `learner_can_choose_session` or `learner_can_cancel_registration` as plain strings, when these parameters are `true`
session_type	string	Accespted values are `0` or `individual` for individual sessions, and `1` or `series`for session series. Default value is `individual`. If you don't specify at all, the event is for individual sessions
concurrent_registration	boolean	Individual sessions only. `0` = learners are registered 1 session at a time, `1`= learners are registered for multiple sessions at a time
access_option	boolean	Individual sessions only. Defines the timeframe for registrations. `0`= allow registration until requirements are met; applies only if `completion_requirement`=1 (Join the session) or =2 (Minimum attendance threshold). `1`= allow registration indefinitely; applies only if `completion_requirement`=0. `2`= allow registration for number of days set in `registration_days_after_enrollment`. `3`= allow registration for a number of attempts, set in `optional_sessions_attend_count`
registration_days_after_enrollment	integer	Max number of days when a learner can register for a session
optional_sessions_attend_count	integer	Max number of sessions learners can attend
visibility	boolean	Visibility of the event and its sessions within the portal. Default is`0`= all users. `1`= course owners and session instructors only
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`
session_series_tags	array	Array of data about each session in the series. Similar results from searching for session series

Session_series_tags array for creating session series

Attribute name	Type	Description
name	string	Session title
required_attendance	boolean	Indicates if attendance is required. Default `false`
sequence	integer	Assigns the order in which the sessions run for learners. Numbers from 0 onward

Data attributes returned after creating a Live Learning event

Attribute name	Type	Description
id	integer	Numeric identifier for the event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL

Create individual Live Learning sessions

Sessions take place within an Live Learning event.

Every session requires:

an ID sourced from the event
at least 1 instructor
1 primary instructor
a start and end time
a timezone

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.

Event owners require user type permissions to create and edit events.

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 Live Learning session within an event, 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/live-learnings/events/361212/sessions

Response returned for creating a session

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

Mandatory parameters for creating a Live Learning session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s
session	object	An object containing the mandatory session parameters

Mandatory session object parameters

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

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

Parameter name	Type	Description
title	string	Title of the 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_usernames	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 session starts, in UTC format
end_time	date/time	The date/time when this 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

location_id: For in-person sessions. A unique identifier for a physical address for sessions. See Search for locations

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`, session is marked as `classroom` without applicable location
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 event. Requires minimum attendance enabled on the event. Set to 0 to turn off minimum attendance for an individual session
description	string	Session’s description
min_capacity	integer	Minimum session capacity
max_capacity	integer	Maximum session capacity
webinar_format	integer	Zoom sessions only: assigns the Zoom format for the session: 1=meeting, 2=webinar. For other integrations default is `null`
qr_before_start_mins	integer	In-person sessions only: number of minutes before a session when learners can self-register through a QR code
qr_after_end_mins	integer	In-person sessions only: number of minutes after a session when learners can self-register through a QR code
qr_confirmation_type	integer	In-person sessions only: indicates if the session requires a confirmation code for login. Default is `0`, no confirmation required

Data attributes returned for creating an event session

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

Add a user to a Live Learning session

This method adds a learner to a 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:

a unique identifier for the learner
course_id to identify the learner's enrollment
session_id for the session

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

The session_id forms part of the URL for this call.

cURL Add a learner 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/live-learnings/sessions/200039/add_to_session

cURL Add a learner 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/live-learnings/sessions/200039/add_to_session

cURL Add a learner 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/live-learnings/sessions/200039/add_to_session

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

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

Requirements to add learners to sessions

To add users to sessions:

the course must have a Published, or Under revision status. You can’t register users to sessions for courses in Draft or other statuses
the session must be associated with the course through the event
the session must be active, and have capacity, or no capacity limit. You can’t add users to cancelled or deleted sessions
the event must use manual registration

This call does not apply to events that register learners automatically to the first session available.

See Live learning: overview and features in LearnUpon's Knowledge Base for background on live learning features.

You can include an event in several courses, with as many sessions as required. As a result, you can enroll learners in an event through more than one course.

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

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

not enrolled in the course: this call enrolls them in the course and the event, registers them for the specific session, and returns an enrollment_id
not enrolled on the course, but is enrolled on the event - for example, enrolled through a different course, waiting for a session: the call adds them to the specific session, enrolls them in the course named in the call, and returns an enrollment_id
not enrolled in the course, and is already enrolled on the specific session: the call enrolls them in the course named in the call, and connects that course enrollment to the event
not enrolled in the course, and is enrolled on another session for the same training: the call does not create an enrollment and returns an error

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

enrolled on the course: the call registers the user to a specific session
enrolled on the course, and registered to the specific session: the call returns 200, and doesn’t generate an error
enrolled on the course, and registered to a different session: the call generates an error

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

Mandatory parameters for adding a user to an event session

Requires one of user_id or username to identify the learner.

Parameter name	Type	Description
user_id	integer	Unique numeric identifier for a learner. Find this value from one of the `GET /users/search?` calls. See: Search for users
email	string	Optional unique identifier for a learner
username	string	Unique identifier for a learner, 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 session. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning events and sessions

Data attributes returned by adding a user to an event session

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

Data returned for adding a learner to a 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 event: 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 event	When the user is already registered on a different session for the event
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 the event has automatic registration for the first available session	The event has Automatic registration for the first available session set: adding a user by API isn’t available

Cancel a learner's registration to a Live Learning session

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

The event_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 Live Learning calls for background.

Cancel a learner's registration for a session

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

Response to cancellation

{
    "message": "success"
}

Mandatory parameters for cancelling for a session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL
session_id	integer	Unique numeric identifier for an individual event session. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning events and sessions
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 a Live Learning session

This endpoint cancels a session, in the future or in the past. This action doesn't cancel the event, or affect course enrollments: it removes the session from the event. Any learners registered for the session move to the Unregistered learners list. See Live learning: overview and features and associated articles for background.

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

cURL to cancel a session

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

Response to cancellation

{
    "message": "success"
}

Mandatory parameters for cancelling for a session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the event. One `event_id` can be associated with many `session_id`s. This ID is part of the training URL
session_id	integer	Unique numeric identifier for an individual session. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning events and sessions

Mark attendance for a Live Learning session

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

The event_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 Live Learning calls for background.

cURL to mark attendance for a 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/live-learnings/events/123/sessions/223/mark_attendance

Response to mark attendance endpoint

{
    "message": "success"
}

Mandatory parameters for marking attendance for a session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the live learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL
session_id	integer	Unique numeric identifier for an individual session. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning events and sessions
attendance	object	Object that contains parameters related to users' attendance

Mandatory session 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

Create a Live Learning session series

Sessions take place within an Live Learning event.

Every session requires:

an ID sourced from the event
at least 1 instructor identified with instructor_pm_idor equivalent email or username
1 primary instructor identified with instructor_pm_id or equivalent email or username
a start and end time
a timezone

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.

Event owners require user type permissions to create and edit events.

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 Live Learning series of sessions within an event, with confirmation


curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"title":"Winter session series via API","register_waitlist_enabled":null,"hours_waitlist_closes_before_session":null,"description":"Creating session series with API","min_capacity":1,"max_capacity":50,"sessions":[{"title":"Winter sessions created by API","description":"API-made goodness","pm_ids":[67890],"starting_time":"2025-12-06 12:00:00.000","ending_time":"2025-12-06 14:30:00.000","timezone":"Eastern Time (US & Canada)","primary_pm_id":67890,"location_id":2255,"qr_before_start_mins":30,"qr_after_end_mins":30,"qr_confirmation_type":0},{"title":"December session 2025","description":"Session created by API","pm_ids":[67890],"starting_time":"2025-12-06 15:00:16.000","ending_time":"2025-12-06 15:30:16.000","timezone":"Eastern Time (US & Canada)","primary_pm_id":67890,"location_id":2255,"qr_before_start_mins":30,"qr_after_end_mins":30,"qr_confirmation_type":0}]}'

https://yourdomain.learnupon.com/api/v1/live-learnings/events/{event_id}/session-series

Response returned for creating a session series

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

Mandatory parameters for creating a Live Learning series of sessions

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s
sessions	array	An array containing the mandatory session series parameters

Optional parameters for creating a session series

Parameter name	Type	Description
title	string	Title for the series of sessions, if different from the event. Default is the event title
description	string	Description for the series of sessions, if different from the event. Default is the event description
register_waitlist_enabled	boolean	`0`=disabled, `1`=enabled for session-level waitlist
hours_waitlist_closes_before_session	integer	Hours before the waitlist closes. No registrations added after this time
min_capacity	integer	Minimum session capacity
max_capacity	integer	Maximum session capacity
restrict_by_group	array, integer	Array of the `group_id` for groups that can access the series of sessions. Other groups don't see the sessions available in the portal

Mandatory session series array parameters

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

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

Parameter name	Type	Description
title	string	Title of the individual session
instructor_pm_ids	array (integer)	Contains `user_id` of the session instructor(s)
instructor_pm_emails	array (string)	Contains `email` addresses of the session instructor(s)
instructor_pm_usernames	array (string)	Contains `username` of the session instructor(s), available as alternative to email
primary_pm_id	integer	`user_id` of the primary instructor
primary_pm_email	string	`email` address of the primary instructor
primary_pm_username	string	`username` of the primary instructor
start_time	date/time	The date/time when this session starts, in UTC format
end_time	date/time	The date/time when this 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 series array parameters

location_id: For in-person sessions. A unique identifier for a physical address for sessions. See Search for locations
group_id: to restrict sessions to named groups. Use GET /groups: see Methods: groups

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`, session is marked as `classroom` without applicable location
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 event. Requires minimum attendance enabled on the event. Set to 0 to turn off minimum attendance for an individual session
description	string	Session’s description
webinar_format	integer	Zoom sessions only: assigns the Zoom format for the session: 1=meeting, 2=webinar. For other integrations default is `null`
qr_before_start_mins	integer	In-person sessions only: number of minutes before a session when learners can self-register through a QR code
qr_after_end_mins	integer	In-person sessions only: number of minutes after a session when learners can self-register through a QR code
qr_confirmation_type	integer	In-person sessions only: indicates if the session requires a confirmation code for login. Default is `0`, no confirmation required

Data attributes returned for creating a session series

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

Mark attendance for a Live Learning series of sessions

This method marks attendance for users for sessions that are part of a series. It does not refer to a course, only the event and sessions that the user attended.

cURL to mark attendance for one session within a series

curl -X POST -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{"attendance":[{"email":
"agnes.poitou@yourdomain.com","completion_status":5},{"email": "amanda.parr@yourdomain.com","completion_status":10}, {"email": "bella.bell@yourdomain.com", "completion_status":10 }]}'

https://yourdomain.learnupon.com/api/v1/live-learnings/events/1265469/session-series/1846251/part/2429557/mark_attendance

Response to mark attendance for session within a series endpoint

{
    "message": "success"
}

You need to mark each session with a separate call.

The event_id and training_session_id and session_part_id form part of the URL for this endpoint.

Use GET methods to find the session series details. See Search for Live Learning session series.

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

Parameter name	Type	Description
event_id	integer	Numeric identifier for the live learning event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL
training_session_id	integer	Unique numeric identifier for a series of sessions. Find this value from one of the `GET /live-learnings/session-series/search?` calls. See: Search for Live Learning session series
attendance	object	Object that contains parameters related to users' attendance

Mandatory session 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 Live Learning series of sessions

This endpoint cancels a series of sessions, in the future or in the past.

cURL to cancel a session

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

Response to cancellation

{
    "message": "success"
}

This action doesn't cancel the event, or affect course enrollments: it removes the session from the event. Any learners registered for the session series move to the Unregistered learners list. See Live learning: overview and features and associated articles for background.

The event_id and session_series_id form part of the URL for this endpoint.

Mandatory parameters for cancelling for a session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the event. One `event_id` can be associated with many `session_id`s. This ID is part of the training URL
session_series_id	integer	Unique numeric identifier for a series of sessions. Find this value from one of the `GET /live-learnings/sessions/search?` calls. See: Search for Live Learning session series

Update a Live Learning event

Update an existing event in Live Learning. This method applies to both events with individual sessions and session series.

Make sure the event retains at least 1 owner, identified by ID, email or username. See Identifier options for Live Learning 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 event s.

cURL update a Live Learning event, with response


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

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

Mandatory parameters for updating a Live Learning event

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

Object parameters to update

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

Parameter name	Type	Description
title	string	Title of the event
owner_user_ids	array (integer)	`user_id`s of the event owner(s)
owner_emails	array (string)	`email` of the event owner(s)
owner_usernames	array (string)	`username` of the event owner(s), available as alternative to email
instructor_user_ids	array (integer)	`user_id`s of the named event instructor(s)
instructor_emails	array (string)	`email` of the event instructor(s)
instructor_usernames	array(string)	`username`s of the event 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	event description
completion_requirement	integer	event 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 event
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 a Live Learning event

Attribute name	Type	Description
id	integer	Numeric identifier for the event. One `event_id` can be associated with many `session_id`s. This ID is part of the event URL

Update a Live Learning session

Sessions take place within an Live Learning event.

Update the parameters for a session.

cURL to update a Live Learning 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/live-learnings/events/361212/sessions/389843

Response returned for updating a session

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

Mandatory parameters for updating a Live Learning session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s
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 Live Learning 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:

timezone_id: use GET /timezone. See Search for timezones
location_id: For in-person sessions. A unique identifier for a physical address for sessions. See Search for locations

Parameter name	Type	Description
title	string	Title of the event 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 session starts, in UTC format
end_time	date/time	The date/time when this session 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`. See Search for locations
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 event. Requires minimum attendance enabled on the event. Set to `0` to turn off minimum attendance for an individual session
description	string	Session’s description
min_capacity	integer	Minimum 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

Update a Live Learning session series

A series of sessions take place within an Live Learning event.

Update the parameters for a session series.

cURL to update a Live Learning session series


curl -X PUT -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d  '{"title":"Winter session series via API","register_waitlist_enabled":null,"hours_waitlist_closes_before_session":null,"description":"Creating session series with API","min_capacity":1,"max_capacity":50,"sessions":[{"title":"Winter sessions created by API","description":"API-made goodness","pm_ids":[67890],"starting_time":"2025-12-06 12:00:00.000","ending_time":"2025-12-06 14:30:00.000","timezone":"Eastern Time (US & Canada)","primary_pm_id":67890,"location_id":2255,"qr_before_start_mins":60,"qr_after_end_mins":60,"qr_confirmation_type":0},{"title":"December session 2025","description":"Session created by API","pm_ids":[67890],"starting_time":"2025-12-06 15:00:16.000","ending_time":"2025-12-06 15:30:16.000","timezone":"Eastern Time (US & Canada)","primary_pm_id":67890,"location_id":2255,"qr_before_start_mins":60,"qr_after_end_mins":60,"qr_confirmation_type":0}]}'

https://yourdomain.learnupon.com/api/v1/live-learnings/events/{event_id}/sessions/{session_series_id}

Response returned for updating a session

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

Mandatory parameters for updating a Live Learning session series

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s
session_series_id	integer	Unique identifier for the session series
sessions	array	An array containing all the session series parameters. For updating existing calls, all array parameters are optional

Session series array parameters for updates

Parameter name	Type	Description
title	string	Title of the individual session
instructor_pm_ids	array (integer)	Contains `user_id` of the session instructor(s)
instructor_pm_emails	array (string)	Contains `email` addresses of the session instructor(s)
instructor_pm_usernames	array (string)	Contains `username` of the session instructor(s), available as alternative to email
primary_pm_id	integer	`user_id` of the primary instructor
primary_pm_email	string	`email` address of the primary instructor
primary_pm_username	string	`username` of the primary instructor
start_time	date/time	The date/time when this session starts, in UTC format
end_time	date/time	The date/time when this 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	Classroom or in person sessions only. A unique identifier of the session location. If you don't include it, and there is no `custom_webinar_url`, session is marked as `classroom` without applicable location
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 event. Requires minimum attendance enabled on the event. Set to 0 to turn off minimum attendance for an individual session
description	string	Session’s description
min_capacity	integer	Minimum session capacity
max_capacity	integer	Maximum session capacity
webinar_format	integer	Zoom sessions only: assigns the Zoom format for the session: 1=meeting, 2=webinar. For other integrations default is `null`
qr_before_start_mins	integer	In-person sessions only: number of minutes before a session when learners can self-register through a QR code
qr_after_end_mins	integer	In-person sessions only: number of minutes after a session when learners can self-register through a QR code
qr_confirmation_type	integer	In-person sessions only: indicates if the session requires a confirmation code for login. Default is `0`, no confirmation required

Data attributes returned for updating a session series

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

Update part of a session series

cURL to update part of a Live Learning session series


curl -X PUT -H "Content-Type: application/json" 
--user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d '{ "session_series": [ { "id": 789,"title": "API-created session 1" }, { "id": 790, "title": "API-created session 2" } ] }'

https://yourdomain.learnupon.com/api/v1/live-learnings/events/{event_id}/sessions/{session_series_id}/part

Mandatory parameters for updating part of a Live Learning session

Parameter name	Type	Description
event_id	integer	Numeric identifier for the Live Learning event. One `event_id` can be associated with many `session_id`s
session_series_id	integer	Unique identifier for the session series
session_part_id	integer	Unique identifier for the session series part
sessions	array	An array containing all the session series parameters

Search for Live Learning metadata

These methods provide data for your Live Learning call parameters.

Sample search for timezones for Live Learning event sessions


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

Search for timezones

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

This method has no additional parameters.

See the list of supported timezones in Appendix: Timezone names.

Data attributes returned for session timezone search

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

Search for locations

This method returns the list of locations available in your portal. You set up locations in the LearnUpon interface.

See the Knowledge Base: Live Learning: set locations for in-person sessions

Sample search and response for locations for Live Learning sessions


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."}]}

Location is an optional course setting, for classroom and in person training. To add a location to your event in the API call, you need the location_id provided by this call.

This method has no additional parameters.

Data attributes returned for locations search

Attribute name	Type	Description
id	integer	Unique numeric identifier for the location
title	string	Name of the location
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

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

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

Optional parameters for portal search

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

Note: Setting a value for number_licenses_purchased automatically enables the license model for the 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

Note: Setting a value for number_licenses_purchased automatically enables the license model for the 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"
        }
    ]
}

Data attributes returned for membership type search

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:

get a list of users who are assigned to a specific group
assign users to groups
remove users from groups

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:

Specify groupmembership_id on your URL, e.g. 1234 as above. This is the unique identifier of the membership, returned when you create a membership via the API
Specify a value of 0 for the id but ensure you have a GroupMembership payload consisting of a group_id and user_id. The call searches for and deletes the membership based on group/user in the payload.

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	Default is `false`. If set to `true`, deleting a user from a group automatically unenrolls the user from any learning paths or courses associated with the group.

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:

GroupInvites API endpoint doesn’t let you add additional user attributes (such as user first and last name), and does let you invite multiple users in a single API request
PortalInvites API endpoint lets you add additional user attributes, and requires a separate API request for each invited user

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

from the Users tab in LearnUpon
using a batch upload
via the API

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:

you enroll all users in that group on the course
in future, LearnUpon will auto enroll new users who join the group onto the courses linked to the group

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:

the manager now manages the existing users in this group in LearnUpon
the manager now manages this group and can run reports and, optionally, create or invite users into this group

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:

The instructor user can run course-related reports in LearnUpon, and correct assignments for learners. You can assign them as dedicated instructors on particular ILT sessions.
All current and future learners in that course can submit assignments to the instructor user.

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

Optional parameters for search

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

Data attributes returned for CourseInstructors search

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
course_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
`POST /learning_paths/{id}/assign_certificate`	Add a certificate to a learning path. Requires certificate ID and learning path ID

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
course_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

Add a certificate to a learning path

Assign existing certificates, previously created through the interface, to your learning paths.

This option requires Certificate Editor Redesign turned on in the portal. Contact the support team as required.

Add a certificate to a learning path

curl  -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{"certification_guid": "6377075f-4abd-11ef-97d5-06c3fede0100", "certification_expires_days": 180, 
"recertify_when_expires": true, "recertify_days_before_expires": 30, "do_course_certs": false}'
https://yourdomain.learnupon.com/api/v1/learning_paths/131470/assign_certificate

Confirmation of adding certificate to a learning path

{
    "message": "Success"
}

Mandatory parameters to add certificates to learning paths

Parameter name	Type	Description
id	integer	Unique numeric identifier for the learning path. Find this value from `GET /learning_paths` endpoint
certification_guid	string	Unique alphanumeric identifier for the certificate. Find this value from `GET /certifications` endpoint. See: Certifications

Optional parameters to add certificates to courses

Parameter name	Type	Description
certification_expires_days	integer	Number of days before the certificate expires
recertify_when_expires	boolean	Indicates if the application will automatically re-enroll the learner for this certification. Default is `false`
recertify_days_before_expires	integer	Number of days to re-enroll the learner before the certificate expries. Default `0`
certification_guid	string	Globally unique alphanumeric identifier for the certificate
do_course_certs	boolean	Awards any course-level certificates, as learners complete courses on their 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:

search for existing learning path enrollments
create new learning path enrollments

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:

the user, with one of their user_id, username or email
the learning path, with one of the lp_id or lp_name

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

Audit trails

The audit-trails endpoint searches for and lists recent high-priority actions on the portal and returns them as JSON files.

You can search by comma-separated action IDs, or by date.

Maximum date range is within the last 30 days: date ranges outside this range generate an error.

Maximum response size is 10K items.

See the LearnUpon Knowledge Base article Portal: access audit trails and export results to CSV for background.

Methods: audit trails

Method	Description of output
`GET /audit-trails`	Searches for actions, filtered by action or by date range

Audit trails call and sample returned data


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


{
    "trails": [
        {
            "action": 2,
            "initiated_by_user": "Beatrice Dansk",
            "initiated_by_user_email": "beatrice.dansk@yourdomain.com",
            "impacted_user": "Agnes Poitou",
            "impacted_user_email": "agnes.poitou@yourdomain.com",
            "impacted_data": "Intro to accessibility, with eSignature",
            "date_and_time_utc": "2024-04-17T20:14:24.272Z"
        },
    ]
}

Audit trails sample call for a specific action, and returned data


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

{
    "trails": [
        {
            "action": 8,
            "initiated_by_user": "Beatrice Dansk",
            "initiated_by_user_email": "beatrice.dansk@yourdomain.com",
            "impacted_user": null,
            "impacted_user_email": null,
            "impacted_data": "Licensed learning paths at LearnUpon",
            "date_and_time_utc": "2024-04-17T19:52:20.878Z"
        }
    ],
    "next": false
}

Audit trails sample call for a date range, with sample returned data


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/audit-trails?date_range=2024-04-10T23:00:00.000Z,2024-05-07T23:00:00.000Z

{
    "trails": [
        {
            "action": 7,
            "initiated_by_user": "Beatrice Dansk",
            "initiated_by_user_email": "beatrice.dansk@yourdomain.com",
            "impacted_user": null,
            "impacted_user_email": null,
            "impacted_data": "Emotional intelligence workshop",
            "date_and_time_utc": "2024-05-03T19:02:18.794Z"
        },
        {
            "action": 6,
            "initiated_by_user": "Beatrice Dansk",
            "initiated_by_user_email": "beatrice.dansk@yourdomain.com",
            "impacted_user": null,
            "impacted_user_email": null,
            "impacted_data": "Get the most from SCORM modules in LearnUpon",
            "date_and_time_utc": "2024-04-18T19:44:54.359Z"
        }
    ],
}

Optional parameters for audit trails endpoints

Parameter name	Type	Description
action_id	integer	Unique numeric identifier associated with individual action type, separated by commas
date_range	string	comma-separated dates in RFC3339 format, within the last 30 days
next	string	Token for viewing a next page, returned in response. For less than 10k results `next=false`

action_id numbers and associated actions

Action number	Action
1	Set complete
2	User unenrolled
3	User deleted
4	User login disabled
5	User login enabled
6	Course deleted
7	Course archived
8	Learning path deleted
9	Learning path archived
10	Exam attempts reset
11	Group deleted
12	User removed from a group

Audit trails object returned

Attribute name	Type	Description
trails	object	An object containing action details

Trails object attributes

Attribute name	Type	Description
action	integer	Unique numeric identifier associated with individual action type
initiated_by_user	string	Name of person who started the action. For automated actions, field is left blank
initiated_by_user_email	string	Email of person who started the action. For automated actions, field is left blank
impacted_user	string	Name of the person affected by the action
impacted_user_email	string	Email of the person affected by the action
impacted_data	string	Name of the content or group or person affected by the action
date_and_time_utc	date/time	Date and time limits in UTC format

Certifications

Certification, aka giving certificates for completed courses and learning paths, shows that your learners have completed courses, and lets them share their accomplishments.

The certifications resource lets you list the certificates available on a portal. With the certificate's unique identifier, you can assign certificates to a specific course or learning path, using POST /courses and POST /learning_paths.

See Courses and Learning paths as required.

Method: certifications

Method	Description of output
`GET /certifications`	Searches for (list) all certificates available on the portal

Search for certificates on a portal

List certificates available on a portal


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

Search results for certifications

{
    "certifications": [
        {
            "guid": "2eb0ddf7-2d63-11ef-97d5-06c3fede0100",
            "title": "Driving level 1"
        },
        {
            "guid": "2eb0dff3-2d63-11ef-97d5-06c3fede0100",
            "title": "Driving level 2"
        },
        {
            "guid": "2ea3f61d-2d63-11ef-97d5-06c3fede0100",
            "title": "SNC certificate"
        }
    ]
}

Data attributes returned for searching for certifications

Attribute name	Type	Description
certifications	array	List of certificate names and unique identifiers

certifications data attributes

Attribute name	Type	Description
guid	string	Unique alphanumeric identifier for each certificate
title	string	Name for the certificate that appears in the interface

Batch user upload via SFTP

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.

See LearnUpon's Knowledge Base articles about batch user upload for background:

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.

See JSON and UTF-8 syntax for tips about working with user data containing special characters.

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 (Secure File Transfer Protocol) server. Make sure:

the server is accessible on port 22
the server has a username and password, which you provide to the API in your call

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:

a batch user upload is already in progress
an attribute is missing or invalid
the upload was to process enrollments, a required group_sync setting was missing
the uploaded file contained no changes from the previous version

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:

For your first batch upload, the import job creates or invites new users, and updates all users in the portal.
For future CSV file uploads, such as daily or weekly updated files, the upload process compares the new file to the previous one, notes the differences, and updates only the learners who have changed from the previous file.

Prerequisites

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.
The CSV file format must be the same as is currently used in LearnUpon’s batch user upload feature.
LearnUpon supports SFTP versions 3 and above.
The CSV file cannot be larger than 50MB.
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`

Note: To use the process_unenrollments parameter, you must set group_sync to true, otherwise you get an error. This parameter applies to Not Started and In Progress status enrollments only. Completed status enrollments remain in the users' training history.

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

HTTP code	Message	Description
200	---	API call was successful
400	Invalid request: feature disabled	Batch user import feature needs to be enabled
400	Invalid request: error converting parameters to bool	Some values that are expected to be boolean were given in a different type
400	invalid request: upload already in progress	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	Invalid request: group sync not enabled, 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: required params are missing	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

Bulk operations

The bulk-operations resource lets you:

submit large batches of enrollments or unenrollments for asynchronous processing
check the status and progress of a submitted bulk-operation job
list bulk-operation jobs for your portal

Currently LearnUpon supports only bulk-enrollment and bulk-unenrollment.

LearnUpon's bulk engine processes bulk operations using the same back-end service as the portal action tracker, so results are reported in a familiar format.

See LearnUpon's Knowledge Base Portal: follow bulk actions through the portal action tracker for background.

Reports on bulk-operations via API are only available via the report_url returned for a job. The application does not display the reports in the portal action tracker itself.

Methods: bulk operations

Method	Description of output
`POST /bulk-operations/submit/{operation}`	Submits a new `bulk-enrollment` or `bulk-unenrollment` job for asynchronous processing
`GET /bulk-operations/jobs/{job_id}`	Retrieves the status, progress, and `report_url` for a bulk-operation job
`GET /bulk-operations/jobs`	Lists bulk-operation jobs for your portal, newest first

Limits for bulk operations

Notes:

up to 100,000 items are allowed per request
an empty items array is acceptable. The job completes immediately with an empty report
rate limits apply: the number of concurrent active jobs per operation is limited

See API throttling and suggested usage patterns for background about rate limits and best practice.

Submit a bulk operation

This endpoint submits a new bulk-enrollment or bulk-unenrollment job for asynchronous processing, and returns a job_id you can use to track its progress.

Every bulk-operation request needs an operation to perform, and a list of items to process.

operation must be either bulk-enrollment or bulk-unenrollment, passed as part of the request path
items is an array of objects. The required fields depend on the operation — see Data parameters for bulk-enrollment items and Data parameters for bulk-unenrollment items

Submit a bulk enrollment


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"items": [{"course_id": 1321, "user_id": 555}, {"course_id": 1321, "user_id": 556}]}'
https://yourdomain.learnupon.com/api/v1/bulk-operations/submit/bulk-enrollment

Submit a bulk unenrollment


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"items": [{"enrollment_id": 9901}, {"enrollment_id": 9902}]}'
https://yourdomain.learnupon.com/api/v1/bulk-operations/submit/bulk-unenrollment

Mandatory parameters for submitting a bulk operation

Parameter name	Type	Description
operation	string	The bulk action to perform, 1 of `bulk-enrollment` or `bulk-unenrollment`
items	array	Customer-provided list of objects to process

Data parameters for bulk-enrollment items

Submitting a bulk enrollment requires a course_id and user_id for every item.

Parameter name	Type	Description
course_id	integer	The unique numeric identifier for the course
user_id	integer	The unique numeric identifier for the user to enroll

Data parameters for bulk-unenrollment items

Parameter name	Type	Description
enrollment_id	integer	The unique numeric identifier for the enrollment to remove

Data attributes returned for a submitted bulk operation

Attribute name	Type	Description
job_id	string (UUID)	Unique numeric identifier for the submitted job. Use this ID to check status or retrieve the results report

Get job status

This endpoint retrieves the current status, progress, and report_url for a bulk-operation job.

The report_url returns an error report in the same format as the report available in the portal action tracker. You can download it programmatically, or open it directly in a browser.

Sample job status request and response

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
https://yourdomain.learnupon.com/api/v1/bulk-operations/jobs/550e8400-e29b-41d4-a716-446655440000

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "operation": "bulk-enrollment",
  "num_operations": 1000,
  "num_completed_operations": 985,
  "num_failed_operations": 15,
  "created_at": "2026-04-15T10:00:00Z",
  "completed_at": "2026-04-15T10:05:32Z",
  "report_url": "https://example.com/reports/550e8400-..."
}

Mandatory parameters for getting job status

Parameter name	Type	Description
job_id	string (UUID)	Path parameter: the `job_id` is the unique identifier returned when the bulk operation was submitted

Data attributes returned for job status

Attribute name	Type	Description
job_id	string (UUID)	Unique identifier for the job
status	string	Current job status. See Status values
operation	string	The operation type, 1 of `bulk-enrollment` or `bulk-unenrollment`
num_operations	integer	Total number of items submitted
num_completed_operations	integer	Items processed successfully
num_failed_operations	integer	Items that failed
created_at	date/time	When the job was submitted, in UTC format
completed_at	date/time	When the job finished, in UTC format. `null` if still running
report_url	string	Download URL for the results report. `null` until the job completes

Status values

Status	Description
in_progress	The job is currently being processed
completed	Processing finished — check `num_failed_operations` for partial failures
failed	A system error occurred. It is safe to retry the full job
aborted	The job was cancelled
timeout	The job exceeded its time limit

List jobs

Returns a paginated list of bulk-operation jobs for your portal, newest first.

Sample list jobs request and response

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c
"https://yourdomain.learnupon.com/api/v1/bulk-operations/jobs?status=completed&page=1&per_page=10"

{
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "operation": "bulk-enrollment",
      "num_operations": 1000,
      "num_completed_operations": 985,
      "num_failed_operations": 15,
      "created_at": "2026-04-15T10:00:00Z",
      "completed_at": "2026-04-15T10:05:32Z",
      "report_url": "https://example.com/reports/550e8400-..."
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

Optional parameters for listing jobs

Parameter name	Type	Default	Description
status	string	(all)	Filter by job status
page	integer	1	Page number
per_page	integer	20	Results per page (max 100)

Data attributes returned for list jobs

Attribute name	Type	Description
jobs	array	List of job objects similar to Data attributes returned for job status
page	integer	Current page number
per_page	integer	Results per page
has_more	boolean	Whether additional pages of results are available

Error responses

All bulk operations API errors return a consistent JSON error envelope.

Sample error response

{
  "error": "payload_too_large",
  "message": "items array exceeds 100,000 entries"
}

HTTP status	Error code	Description
400	validation_failed	Missing or invalid fields in the request body
403	feature_not_enabled	Bulk Operations API is not enabled for your portal
404	not_found	Job not found
422	payload_too_large	`items` array exceeds 100,000 entries
429	rate_limit_exceeded	Too many concurrent jobs — wait for existing jobs to complete
500	internal_error	An unexpected error occurred

eCommerce

LearnUpon is offering eCommerce services using Spree Vendo, an open-source eCommerce framework trusted by thousands of businesses worldwide.

LearnUpon based its eCommerce API endpoints on Spree's platform API. See Spree's platform API documentation.

Notes:

LearnUpon supports a limited number of endpoints for eCommerce, to enable customers to manage transactions for their portal sales
authentication is managed through LearnUpon's methods only
LearnUpon has modified the request and responses of supported endpoints. As a result, some responses are near-identical to Spree, some are not
includes parameters are not supported. The API endpoint embeds the relationships when they are relevant
the eCommerce endpoints use prefixed IDs, of type string (vs integer) for resources. Look for prod_abcde, li_abcde, or_abcde and similar

The ecommerce resource lets you view and manage products, prices, orders, line items and payments. You can also view customers, store credits and gift cards.

Methods: eCommerce

Products	Description of output
`GET /ecommerce/products`	Searches for products, with optional parameters to filter or set pages
`GET /ecommerce/products/{product_id}`	Searches for products by `product_id`
`PATCH /ecommerce/products/{product_id}`	Update a product's details

Prices	Description
`GET /ecommerce/products/{product_id}/prices/{price_type}`	List prices for a product
`GET /ecommerce/products/{product_id}/prices/{price_type}/{price_id}`	List a price for a product by `price_id`
`POST /ecommerce/products/{product_id}/prices/{price_type}`	Create a base price for a product by `product_id`
`PATCH /ecommerce/products/{product_id}/prices/{price_type}/{price_id}`	Update a price for a product identified by `price_id`
`DELETE /ecommerce/products/{product_id}/prices/{price_type}/{price_id}`	Delete a base price for a product identified by `price_id`

Orders	Description
`GET ecommerce/orders`	List all orders
`POST ecommerce/orders`	Create an order
`PATCH ecommerce/orders/{number}`	Update an order by `order_id` or `number`
`PATCH ecommerce/orders/{number}/advance`	Advance or progress an order through states

Payments	Description
`GET ecommerce/payments/{payment_id}`	Search for a payment by `payment_id`
`POST ecommerce/payments`	Create a payment
`PATCH ecommerce/payments/{payment_id}`	Update a payment
`PATCH ecommerce/payments/{payment_id}/capture`	Capture a payment, to state the payment is complete
`PATCH ecommerce/payments/{payment_id}/void`	Cancel a payment, without deleting it

Adjustments	Description
`GET ecommerce/orders/{order_id}/adjustments`	List adjustments to an order
`GET ecommerce/orders/{order_id}/adjustments/{adjustments_id}`	Search for specific adjustments
`POST ecommerce/orders/{order_id}/adjustments`	Create adjustments
`PATCH ecommerce/orders/{order_id}/adjustments/{adjustments_id}`	Update individual adjustments
`DELETE ecommerce/orders/{order_id}/adjustments/{adjustments_id}`	Delete adjustments

Line items	Description
`GET ecommerce/orders/{order_id}/line_items`	List the individual items in an order
`GET ecommerce/orders/{order_id}/line_items/{line_item_id}`	Search for a specific line item
`POST ecommerce/orders/{order_id}/line_items`	Create line items
`PATCH ecommerce/orders/{order_id}/line_items/{line_item_id}`	Update an individual line item
`DELETE ecommerce/orders/{order_id}/line_items/{line_item_id}`	Delete a line item

Customers	Description
`GET ecommerce/customers/{user_id}`	Search for a customer by `user_id` or `customer_id` (interchangeable)

Store credits	Description
`GET ecommerce/store_credits/{store_credit_id}`	Search for store credit by `store_credits_id`

Subscriptions	Description
`GET ecommerce/customers/{customer_id}/subscriptions`	Search for customer subscriptions
`POST ecommerce/customers/{customer_id}/subscriptions/{subscription_plan_id}`	Create a manual subscription
`PUT ecommerce/customers/{customer_id}/subscriptions/{user_subscription_id}`	Update a subscription manually
`GET ecommerce/subscription-plans`	List all subscription plans for your storefront
`GET ecommerce/subscription-plans/{subscription_plan_id}`	Find one subscription plan

Gift cards	Description
`GET ecommerce/gift_cards/{gift_card_id}`	List gift cards

Search for products

List products


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{ "filter":{"name": "Avoiding slips, trips and falls: observation"}}'
https://yourdomain.learnupon.com/api/v1/ecommerce/products

Search for a product by product_id


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

Optional parameters for searching for products

See Data pagination about setting how many pages to view.

Parameter name	Type	Description
filter	object	Contains parameters for filtering results

Filter object optional parameters

Parameter name	Type	Description
name_eq	string	"name equals": enter an exact match to the title of the course

Data returned by search for products

Attribute name	Type	Description
id	string	Product ID is the unique identifier for the product on the eCommerce platform. It is not the same as identifiers from the portal
name	string	The title of the product
description	string	Product description: can include HTML markup
available_on	date/time	Calendar date when the product is available. Can be `null`
discontinue_on	date/time	Calendar date when the product is no longer available. Can be `null`
slug	string	Text that appears in the URL for the product
status	string	Defines if the product is available for sale or not. One of `draft` or `active`. Default is `draft`
content_type	string	Defines the type of content. One of `course` or `bundle`
content_id	integer	Refers to the unique identifier for content used in the LearnUpon portal, such as `course_id`
tags	array, strings	Customer-created tags for identifying products and filtering
meta_description	string	SEO description
meta_keywords	string	SEO keywords
metafields	array	Customer-created custom field names and values
base_prices	array	Prices with supported currencies, used when `price_type=base`
membership_prices	array	Prices with supported currencies, when `price_type=membership`
tax_category	object	Contains data about tax categories
taxons	[array]	Contains data about taxon identifiers and types. Taxons are the categories Spree uses to group products
group_restrictions	array, string	Contains data about which portal groups can access products

metafields array attributes

Attribute name	Type	Description
key	string	Customer-defined custom field name
value	string	Value for the custom field
type	customer-defined	One of `string`, `integer`, `boolean`, `json`

base_prices array data attributes

Attribute name	Type	Description
id	string	Unique identifier for the price in a given currency
amount	string	The current selling price of the variant in the specified currency
compare_at_amount	string	The recommended retail price of the variant in the specified currency. Used to display crossed out prices in the storefront. Can be `null`
currency	string	ISO code for the currency for `amount` and `compare_at_amount` for this product
created_at	time/date	Timestamp of when the price was created
updated_at	time/date	Timestamp of when the price was updated

membership_prices array data attributes

Attribute name	Type	Description
id	string	Unique identifier for the price in a given currency
amount	string	The current selling price of the variant in the specified currency
compare_at_amount	string	The recommended retail price of the variant in the specified currency. Used to display crossed out prices in the storefront. Can be `null`
currency	string	ISO code for the currency for `amount` and `compare_at_amount` for this product
membership_type_id	integer	Identifier for the membership type
membership_type_label	string	Membership type name
created_at	time/date	Timestamp of when the price was created
updated_at	time/date	Timestamp of when the price was updated

tax_category object data attributes

Attribute name	Type	Description
id	string	Unique identifier for the tax category
type	string	Defines the category type

taxons array data attributes

Attribute name	Type	Description
id	integer	Unique numeric identifier for the taxon
name	string	Customer-generated label. Typically this label matches your categories within LearnUpon
permalink	string	Link that points to the taxon. Example: "categories/canada"

Patch product by product_id

Update a product by product_id


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

'{"name": "Slips trips and falls: Canada health and safety","description": "Course for Canadian employers","available_on": "2026-08-24T14:15:22Z","discontinue_on": "2027-08-24T14:15:22Z","tags": ["Canada", "compliance training"]}'

https://yourdomain.learnupon.com/api/v1/ecommerce/products/{product_id}

Update a product listing using a PATCH endpoint: updates only the fields you provide and leaves other fields unchanged. The endpoint returns a full product listing showing your latest updates.

Product parameters available to update

Parameter name	Type	Description
name	string	The title of the product
description	string	Product description: can include HTML markup
available_on	date/time	Calendar date when the product is available. Can be `null`
discontinue_on	date/time	Calendar date when the product is no longer available. Can be `null`
slug	string	Text that appears in the URL for the product
meta_description	string	SEO description
meta_keywords	string	SEO keywords
amount	string	Price stated in the associated currency
compare_at_amount	string	The recommended retail price of the variant in the specified currency. Can be `null`
currency	string	ISO code for the currency for this product
tax_category_id	string	Unique identifier for the tax category
taxon_ids	array, integer	Unique numeric identifiers for any taxons associated with the product
product_group_restrictions	array, integer	Unique numeric identifiers for groups that have access to the product

List prices for products

In the eCommerce platform, you set a base price in as many currencies you support.

For organizations that offer membership pricing, you then set membership prices, in your supported currencies.

The base price applies as default when the buyer isn't eligible for a membership-specific price.

All the price-related endpoints require price_type of either base or membership.

See LearnUpon's Knowledge Base: Associations and membership types: overview and setup

Get or list prices for a specfic product


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/products/{product_id}/prices/{price_type}

Mandatory parameters for listing prices

Parameter name	Type	Description
product_id	string	Unique identifier for the product
price_type	string	One of `base` or `membership`, to return the correct price for the product

Prices returned attributes

Attribute name	Type	Description
id	string	Unique identifier for the price
amount	string	The current selling price in the specified currency
compare_at_amount	string	The recommended retail price in the specified currency. Used to display crossed out prices in the storefront. Can be `null`
currency	string	ISO code for the currency for `amount` and `compare_at_amount` for this product
membership_type_id	integer	`membership` only: identifier for the membership type
membership_type_label	string	`membership` only: membership type name

Create a new base price for a product

Set a new base price for a product


curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"amount": 25.99,"currency": "CAD"}' 
https://yourdomain.learnupon.com/api/v1/ecommerce/products/{product_id}/prices/{base}

This endpoint requires the product_id and lets you set a new base price, in a currency that doesn't yet have a price set.

You can't set a membership price with this endpoint, only the base price.

You can update existing products that already have membership prices using the PATCH endpoint.

The endpoint returns the price attributes with a new price_id for the product in this currency.

Mandatory parameters for setting base prices

Parameter name	Type	Description
product_id	string	Unique identifier for the product
price_type	string	`base` only

Price setting returned attributes

Attribute name	Type	Description
id	string	Unique identifier for the price
amount	string	The current selling price in the specified currency
compare_at_amount	string	The recommended retail price in the specified currency. Used to display crossed out prices in the storefront. Can be `null`
currency	string	ISO code for the currency for `amount` and `compare_at_amount` for this product
created_at	time/date	Timestamp of when the price was created
updated_at	time/date	Timestamp of when the price was updated

Update or delete a price for a product

Update a price for a product


curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"amount": 200, "currency": "USD"}' 
https://yourdomain.learnupon.com/api/v1/ecommerce/products/{product_id}/prices/{price_type}/{price_id}

Delete a base price in a currency for a product


curl -X DELETE -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"amount": 200, "currency": "USD"}' 
https://yourdomain.learnupon.com/api/v1/ecommerce/products/{product_id}/prices/base/{price_id}

The PATCH endpoint lets you change existing base and membership prices in the named currencies. It returns the same data as for Price setting returned attributes.

The DELETE endpoint lets you delete a base price for a product, in a given currency.

You can't delete membership prices with this endpoint.

Mandatory parameters for updating or deleting prices

Parameter name	Type	Description
product_id	string	Unique identifier for the product
price_type	string	One of `base` or `membership`. For `DELETE`, use `base` only
price_id	string	Unique identifier for the price in a given currency

Search for orders

List orders


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

Search for a orders by order_id or number


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

Sample return for listing an order

{
    "id": "or_E86hxLZ9ck",
    "number": "R067763667",
    "item_total": "10.0",
    "total": "10.0",
    "state": "complete",
    "adjustment_total": "0.0",
    "payment_state": "paid",
    "currency": "EUR",
    "item_count": 1,
    "canceled_at": null,
    "created_at": "2026-03-04T20:39:16.551Z",
    "updated_at": "2026-03-05T15:17:43.680Z",
    "completed_at": "2026-03-05T15:17:43.000Z",
    "special_instructions": null,
    "bulk_purchase": false,
    "display_item_total": "€10.00",
    "display_total": "€10.00",
    "display_adjustment_total": "€0.00",
    "metafields": [],
    "state_link": "https://yourportal.learnupon.com/ecommerce/checkout/longstringidentifier/complete?currency=EUR",
    "user_id": 291200,
    "bill_address": 
    {
        "id": "addr_x9soCpeNMW",
        "firstname": "Charlotte",
        "lastname": "Schleswig",
        "address1": "One Park Place",
        "address2": "4th floor",
        "city": "Dublin",
        "zipcode": null,
        "phone": "00000000000000",
        "state_name": null,
        "country_iso": "IE"
    },
    "line_items": [
            {
            "id": "li_nU8qfPa3Cp",
            "quantity": 1,
            "price": "10.0",
            "currency": "EUR",
            "total": "10.0",
            "adjustment_total": "0.0",
            "additional_tax_total": "0.0",
            "promo_total": "0.0",
            "included_tax_total": "0.0",
            "pre_tax_amount": "10.0",
            "taxable_adjustment_total": "0.0",
            "non_taxable_adjustment_total": "0.0",
            "bulk_purchase": false,
            "display_price": "€10.00",
            "display_total": "€10.00",
            "order_id": "or_E86hxLZ9ck",
            "product_id": "prod_CP5SrJgpzQ",
            "tax_category_id": 69,
            "tax_category": {
                "id": 69,
                "name": "Default"},
            "digital_links": [] 
            }
        ],
        "payments": [],
        "adjustments": []
}

The orders endpoint returns details about orders placed. You can filter for named items, or search for an order by order_id or order number.

Not all attributes appear in every returned call.

Mandatory parameters for searching for individual orders

Requires 1 of the 2 parameters.

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
number	string	A unique identifier for this order. This number is shown to the buyers

Optional parameters for searching for orders

See Data pagination about setting how many pages to view.

Parameter name	Type	Description
filter	object	Contains parameters for filtering results

Filter object optional parameters

Parameter name	Type	Description
name_eq	string	"name equals": enter an exact match to the title of the product

Order data attributes

Attribute name	Type	Description
id	string	Order ID is the unique identifier for the order on the eCommerce platform
number	string	A unique identifier for this order. This number is shown to the buyers
state	string	The current state of the order. One of `cart`, `address`,`delivery`, `payment`, `confirm`, `complete`, `canceled`
payment_state	string	Current state of payments associated with the order. An order can have multiple payments
item_total	string	The sum of all the line items for this order
adjustment_total	string	Sum of all adjustments (tax + shipping + promos). Can be `null`
total	string	Sum of the `item_total` and the `adjustment_total`
display_total	string	The sum of the order shown to the customer in the relevant currency
display_item_total	string	The sum of all the line items shown to the customer in the relevant currency
display_adjustment_total	string	Sum of all adjustments (tax + shipping + promos) shown to the customer in the relevant currency
currency	string	The ISO currency code for this order, such as USD
email	string	Contact email. Can be `null`
user_id	string	Person who created the order
item_count	string	Number of items in the order
special_instructions	string	Notes about the order from the customer
canceled_at	time/date	Can be `null`. Date of cancellation
created_at	time/date	Timestamp of when the order was created
updated_at	time/date	Timestamp of when the order was updated
completed_at	time/date	The timestamp of when the order was completed
bulk_purchase	boolean	Indicates if this order is a bulk purchase
bill_address	object	Contains billing address information. Can be `null`
line_items	array	Details about each line item
payments	array	Details about the payment
adjustments	array	Details about adjustments like promotions or discounts
metafields	array	Customer-created custom field names and values
meta	object	For lists of multiple orders, contains details about the display of products onscreen

Bill address object attributes

Attribute name	Type	Description
firstname	string	Customer first name
lastname	string	Customer last name
address1	string	Customer address
city	string	Customer city
zipcode	string	Customer zip code or post code
phone	string	Customer phone
company	string	Customer company name
country_iso	string	Customer ISO alpha-2 code
state_name	string	Customer state or province name - optional
label	string	Example: "My home address"

Line items array data attributes

Attribute name	Type	Description
id	string	Unique identifier for the line item
quantity	integer	Number of items in this line item
price	string	Cost of this line item
currency	string	The ISO currency code for this order, such as USD
total	string	Total cost for the line item
adjustment_total	string	Total of adjustments
additional_tax_total	string	Total of additional tax
promo_total	string	Total of promotions
included_tax_total	string	Total of tax included
pre_tax_amount	string	Cost before tax
taxable_adjustment_total	string	Tax on the adjustment
non_taxable_adjustment_total	string	Total of adjustment that is not taxable
bulk_purchase	boolean	Indicates if this line item is a bulk purchase
display_price	string	Price shown to customers in the relevant currency
display_total	string	Total to pay shown to customers in the relevant currency
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
product_id	string	Unique identifier for the product
tax_category_id	integer	Unique numeric identifier for the tax category
tax_category	object	Details about the tax category
digital_links	array	Can be `null`. Contains data about any links applicable to this line item

Tax category object attributes

Attribute name	Type	Description
id	string	Unique identifier for the tax category
name	string	Name of the tax category

Payments array data attributes

Attribute name	Type	Description
id	string	Unique identifier for the payment
amount	string	Sum the buyer is paying
state	string	The current payment status of the order. It takes into account all payments. One of `checkout`, `pending`, `processing`, `balance_due`, `paid`, `completed`, `credit_owed`, `failed`, `void`
payment_method_id	integer	Unique numeric identifier for the payment method
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
captured_at	date/time or `null`	Time the payment was recorded
created_at	date/time	Time the payment request was created

Adjustments array data attributes

Attribute name	Type	Description
id	string	Unique identifier for the adjustment
label	string	The name of the adjustment
amount	string	The sum that the adjustment represents
eligible	boolean	Indicates if the adjustment applies to the order
state	string	State of the adjustment
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform

metafields array attributes

Attribute name	Type	Description
key	string	Customer-defined custom field name
value	string	Value for the custom field
type	customer-defined	One of `string`, `integer`, `boolean`, `json`

Meta object attributes

Attribute name	Type	Description
page	string	Current page of orders shown
limit	string	Limit of viewable orders on a page
count	string	Total of orders
pages	string	Number of pages required to show all orders
from	string	First order shown on the page
to	string	Last order shown on the page
in	string	Relates to total number of orders
previous	string	Can be `null`. Refers to previous page to display
next	string	Can be `null`. Refers to next page to display

Create an order

Create an order


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

'{"user_id": 29100, "special_instructions": "A special instruction to handler", "currency": "EUR",
"channel": "online","considered_risky": false, "line_items_attributes": [{"product_id": "prod_gXYEHJdmfr","quantity": 3,"bulk_purchase": true},{"product_id": "prod_CP5SrJgpzQ","quantity": 1,"bulk_purchase": false}]}'

https://yourdomain.learnupon.com/api/v1/ecommerce/orders

Create an order for products from the store.

Mandatory order object parameters

Parameter name	Type	Description
user_id	integer	The unique numeric identifier for a person in this portal
email	string	Email contact for the person placing the order
special_instructions	string	Instructions from the customer entered at purchase
currency	string	The ISO currency code for this order, such as USD
channel	string	Refers to the sales channel. One of `online`, `api`, `offline`
considered_risky	boolean	Indicates if the order is flagged for fraud review. Default `false`
line_items_attributes	object	Contains line items information

Optional order object parameters

Parameter name	Type	Description
bill_address	object	Contains billing address information

Bill address object parameters

Parameter name	Type	Description
firstname	string	Customer first name
lastname	string	Customer last name
address1	string	Customer address
city	string	Customer city
zipcode	string	Customer zip code or post code
phone	string	Customer phone
alternative_phone	string	Additional phone number
company	string	Customer company name
country_iso	string	Customer ISO alpha-2 code
state	string	Customer state or province name - optional
state_abbr	string	For `country_iso`=`US` - state identifier
label	string	Example: "My home address"

Line items object parameters

Parameter name	Type	Description
product_id	integer	Unique identifier for the product
quantity	number	Number of products purchased in this line item
bulk_purchase	boolean	Indicates if this order is a bulk purchase. Default `false`

Order returned attributes

The application returns an order with an order_id, an order number, and data the same as shown for searching for an order. See Data attributes returned for search for orders.

Update an order

Update or change an order using the order_id or number


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

'{"email": "agnes.poitou@yourdomain.com"}'
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{number}

You can update an order, entering only the fields you need to change, using the PATCH endpoint. The fields you don't list are not changed, unless they are affected by your changes, like totals.

This endpoint can progress orders: for example, update the billing address, or the number of line items.

Providing line_items_attributes replaces all current line items of the order with the given array.

When changing currency, make sure that line item products have prices in the given new currency, otherwise the application removes the line item from the order.

To change a line_item quantity to greater than 1, make sure you set bulk_purchase to true.

The application returns the order details including the changed attributes.

Progress an order

Advance or progress an order using the order_id or number


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

https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{number}/advance

Mandatory parameters for progressing individual orders

Requires 1 of the 2 parameters.

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
number	string	A unique identifier for this order. This number is shown to the buyers

This endpoint changes the pending order's state. See Order data attributes. The endpoint uses the same parameters as for Update an order.

Completing the order requires a payment available: the order can't progress to paid without payment.

If you try to advance an order that is complete, the application returns a 200 with no change.

The returned payload shows the order with a new state. You can confirm the result by searching for the order. See search for orders.

Payments

This endpoint extends ecommerce/orders and returns the details about payments, including:

searching or listing payments
capturing a payment that is pending
voiding a payment in progress
creating a payment

Search for payments

List payments for an order

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/payments/

Find an individual payment by order_id and payment_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/payments/{payment_id}

Sample returned data for search for a payment


{
    "id": "py_rABCDEFG",
    "amount": "30.0",
    "state": "completed",
    "response_code": null,
    "avs_response": null,
    "number": "ABCDEFGHIJ",
    "cvv_response_code": null,
    "cvv_response_message": null,
    "source_type": null,
    "display_amount": "€30.00",
    "order_id": "or_6EPgargleF",
    "payment_method_id": 277,
    "payment_method": 
    {
      "id": "pm_k8FBapIsR",
      "name": "LearnUpon Purchase Order",
      "type": "Spree::PaymentMethod::PO"
    },
    "refunds": [],
    "metafields": []
}

Find an individual payment by order_id together with payment_id.

Mandatory parameters for finding a payment

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
payment_id	string	Unique identifier for the payment on the eCommerce platform

Attributes returned for search for a payment

Attribute name	Type	Description
id	string	Unique identifier for the payment on the eCommerce platform
number	string	Unique identifier for the payment
amount	string	Raw number for the payment
state	string	The current payment status of the order. It takes into account all payments. One of `checkout`, `pending`, `processing`, `balance_due`, `paid`, `completed`, `credit_owed`, `failed`, `void`
payment_method_id	integer	Unique numeric identifier for the payment method
payment_method	object	Object describing the payment method
source_type	string	Payment source type
response_code	string	Credit card only: relates to credit card purchases
avs_response	string	Credit card only: Response from Address Verification Service (AVS)
cvv_response_code	string	Credit card only: response to CVV
cvv_response_message	string	Credit card only: Message about CVV response
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
refunds	array	Data related to refunds
metafields	array	Customer-created custom field names and values

Payment method object attributes

Attribute name	Type	Description
id	string	Unique identifier for the payment method
name	string	Label to identify payment method. Typically one of "Credit card", "Stripe", "Purchase order" or similar
type	string	Defines the payment method within Spree

Capture a payment

Find a pending payment

curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/payments/{payment_id}/capture

Mandatory parameters for capturing a payment

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
payment_id	string	Unique identifier for the payment on the eCommerce platform

This endpoint returns the details about an in-process payment with order_id and payment_id.

The data returned is similar to the results of searching for a payment, and can use this data to progress the state of the payment.

See Attributes returned for search for a payment.

Void a payment

Void a payment

curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/payments/{payment_id}/void

This endpoint lets you void a payment that is in process, and not yet complete.

Mandatory parameters for voiding a payment

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
payment_id	string	Unique identifier for the payment on the eCommerce platform

Create a payment

Create a payment

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d 
'{ "amount": 310, "payment_method_id": 177}'
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/payments/

Sample returned data for a payment

{
    "id": "py_z2oIcw",
    "amount": "310.0",
    "state": "checkout",
    "response_code": null,
    "avs_response": null,
    "number": "NK0TB2",
    "cvv_response_code": null,
    "cvv_response_message": null,
    "source_type": null,
    "display_amount": "€310.00",
    "order_id": "or_pQZNk",
    "payment_method_id": 177,
    "payment_method": 
    {
        "id": "pm_k8yKT9MVfb",
        "name": "LearnUpon Purchase Order",
        "type": "Spree::PaymentMethod::Check"
    },
    "refunds": [],
    "metafields": []
}

This endpoint extends ecommerce/orders and lets you create a payment.

The endpoint returns a payment_id, and data about the payment.

The data returned is similar to the results of searching for a payment.

See Attributes returned for search for a payment.

Mandatory parameters for creating a payment

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
amount	string	Raw number for the payment
payment_method_id	integer	Unique numeric identifier for the payment method

Adjustments

List adjustents to an order

List adjustments for an order with order_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/adjustments/

List individual adjustments for an order with adjustment_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/adjustments/{adjustment_id}

Sample returned attributes for adjustments on an order


[
  {
    "id": "adj_ghi123",
    "label": "Summer discount",
    "amount": "string",
    "eligible": true,
    "state": "string",
    "order_id": "or_BUNCHtext"
  }
]

Adjustments are modifications to a a customer's order such as promotions or discounts.

Mandatory parameters for listing adjustments for an order

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform

Attributes returned for listing adjustments

This data also appears as an array within orders. See Search for orders.

Attribute name	Type	Description
id	string	Unique identifier for the adjustment
label	string	The name of the adjustment
amount	string	The sum that the adjustment represents
eligible	boolean	Indicates if the adjustment applies to the order
state	string	State of the adjustment
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform

Update adjustments for an order

Change individual adjustments for an order

curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"label": "Summer discount","amount": 0}'
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/adjustments/{adjustment_id}

This endpoint lets you change an adjustment. You provide the changed adjustment details in the body of the payload.

The endpoint returns the adjustment with the changed data.

Mandatory parameters for listing adjustments for an order

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
adjustment_id	string	Unique identifier for individual adjustments on an order

Create an adjustments for an order

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"label": "Summer discount","amount": 10}'
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/adjustments/

This endpoint lets you add an adjustment to an existing order. You provide the added adjustment details in the body of the payload. The endpoint returns the adjustment_id with the changed data.

Mandatory parameters for listing adjustments for an order

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform

Delete an adjustment

Delete an adjustment, with order_id and adjustment_id

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

https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/adjustments/{adjustments_id}

This DELETE endpoint lets you remove an adjustment from an existing order.

There's no returned data for this endpoint. If you search for the adjustment again you'll get an "order not found" message.

Search for line items

List line items by order_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/line_items

Search for individual line items by order_id and line_item_id

curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/line_items/{line_item_id}

The line_items endpoint returns the details about either all line items in an order, or a specific line item.

For a result for multiple line items, the returned data includes the meta array.

Data attributes returned for line items search

Attribute name	Type	Description
id	string	Unique identifier for the line item
quantity	integer	Number of items in this line item
price	string	Cost of this line item
currency	string	The ISO currency code for this order, such as USD
total	string	Total cost for the line item
adjustment_total	string	Total of adjustments
additional_tax_total	string	Total of additional tax
promo_total	string	Total of promotions
included_tax_total	string	Total of tax included
pre_tax_amount	string	Cost before tax
taxable_adjustment_total	string	Tax on the adjustment
non_taxable_adjustment_total	string	Total of adjustment that is not taxable
bulk_purchase	boolean	Indicates if this line item is a bulk purchase
display_price	string	Price shown to customers in the relevant currency
display_total	string	Total to pay shown to customers in the relevant currency
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
product_id	string	Unique identifier for the product
tax_category_id	string	Unique identifier for the tax category
tax_category	object	Details about the tax category
digital_links	array	Can be `null`. Contains data about any links applicable to this line item
meta	object	Contains a list of the line items and total page count

Create a line item

Create a line item for an existing order, with order_id

curl -X POST -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"product_id": "prod_PjHNMcnNFW", "quantity": 2, "bulk_purchase": true }'

https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/line_items

Mandatory data parameters for adding a line item

Parameter name	Type	Description
order_id	string	Order ID is the unique identifier for the order on the eCommerce platform
product_id	string	Unique identifier for the product
quantity	integer	Number of items in this line item. Must be greater than 0. For adding 1+ in a single line item, set `bulk_purchase=true`
bulk_purchase	boolean	Default `false`. Indicates if this line item is a bulk purchase. Change to `true` for any quantity greater than 1

This POST endpoint lets you add a line item to an existing order. The call returns a new line_item_id, and the details of the line item, as shown in Data attributes returned for line items search.

Update a line item

Update or change an existing line item, with order_id and line_item_id

curl -X PATCH -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
'{"quantity": 5, "bulk_purchase": true}'

https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/line_items/{line_item_id}

This PATCH endpoint lets you change a line item in an existing order. The endpoint only changes the values you enter.

The call returns the data for the order with the changes shown.

Delete a line item

Delete a line item, with order_id and line_item_id

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

https://yourdomain.learnupon.com/api/v1/ecommerce/orders/{order_id}/line_items/{line_item_id}

This DELETE endpoint lets you remove a line item in an existing order.

There's no returned data for this endpoint. If you search for the line item again you'll get a "line item not found" message.

Find customers by user ID or customer ID

Find customers by user_id


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

Returned contents of search for a customer profile


{
    "id": 291200,
    "email": "charlotte.schleswig@yourdomain.com",
    "first_name": "Charlotte",
    "last_name": "Schleswig",
    "average_order_value": [
        {
            "currency": "EUR",
            "amount": "10.00"
        }
    ],
    "lifetime_value": [
        {
            "currency": "EUR",
            "amount": "10.00"
        }
    ],
    "store_credits": [],
    "bill_address": 
    {
        "id": "addr_x9soC",
        "firstname": "Charlotte",
        "lastname": "Schleswig",
        "address1": "One Park Place",
        "address2": "4th floor",
        "city": "Dublin",
        "zipcode": null,
        "phone": "00000000000000",
        "state_name": null,
        "country_iso": "IE"
    }
}

Search for a customer profile and view a summary of their order and payment data. This endpoint requires the user_idor customer_id, available from searching for orders. See Search for orders.

Returned data attributes for search for customer profile

Attribute name	Type	Description
id	string	Unique identifier for the customer profile - not the same as their portal `user_id`
email	string	Customer-provided email
first_name	string	Customer first name
last_name	string	Customer last name
average_order_value	array	Contains data about the average order
lifetime_value	array	Contains data about the total spent by the customer
store_credits	array	Contains data about store credits earned by the customer
bill_address	object	Details about the billing address

Average order value data attributes

Attribute name	Type	Description
currency	string	The ISO currency code for this order, such as USD
amount	string	Raw number for the payment

Lifetime value data attributes

Attribute name	Type	Description
currency	string	The ISO currency code for this order, such as USD
amount	string	Raw number for the payment

Store credits data attributes

Attribute name	Type	Description
currency	string	The ISO currency code for this order, such as USD
amount	string	Raw number for the payment

Bill address object attributes

Attribute name	Type	Description
id	string	Unique identifier for the customer address
firstname	string	Customer first name
lastname	string	Customer last name
address1	string	Customer address
address2	string	Customer address 2
city	string	Customer city
zipcode	string	Customer zip code or post code
phone	string	Customer phone
company	string	Customer company name
country_iso	string	Customer ISO alpha-2 code
state_name	string	Customer state or province name - optional

Search for store credit

Find store credit by store_credit_id


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

Data returned for search by store_credit_id

{
  "id": "credit_mno345",
  "amount": "20",
  "amount_used": "0",
  "amount_authorized": "50",
  "currency": "USD",
  "memo": "string",
  "user_id": "291100",
  "created_by_id": "string",
  "category": 
  {
    "id": 0,
    "name": "string"
  },
  "credit_type": 
  {
    "id": 0,
    "name": "string"
  },
  "display_amount": "$20",
  "display_amount_used": "0"
}

You can find details about a buyer's store credits by store_credit_id.

This endpoint returns details about store credit category and type. The credit type defines which credits are applied first or last.

Returned data attributes for search for store credits

Attribute name	Type	Description
id	string	Unique identifier for the store credit
amount	string	Amount of credit
amount_used	string	Total of credit used to date
amount authorized	string	Amount of store credit a customer can use
currency	string	ISO code for the currency
memo	string	Notes
display_amount	string	Value of credits shown to the buyer in their preferred currency
display_amount_used	string	Value of used credits shown to the buyer in their preferred currency
user_id	integer	Unique identifier for the customer on the portal
created_by_id	string	Unique identifier of the person who assigned the credit
category	object	Details about the store credit by purpose. Gift cards, refunds, loyalty rewards are categories of store credit
credit_type	object	Defines the priority of store credits for applying them to a purchase

Store credit category object attributes

Attribute name	Type	Description
id	integer	Unique identifier for store credit categories
name	string	Label for store credit, such as gift cards, refunds and loyalty rewards

Store credit type object attributes

Attribute name	Type	Description
id	integer	Unique identifier for store credit type
name	string	One of `expiring` (applied first) and `non-expiring` (applied last)

Customer subscription management

These endpoints let you set up subscriptions for products through eCommerce. Buyers can order content, and pay recurring fees. Optionally, you can offer content free with subscription.

You need to set up the subscription plans for your storefront within the eCommerce UI.

Using the ecommerce/customers endpoint, you can: * list all subscriptions for a customer with their customer_id * create a new subscription with a customer_id and subscription_plan_id * update an existing subscription

Using the ecommerce/subscription-plans endpoint you can: * list the active subscription plans offered through your storefront * return an individual subscription plan by its subscription_plan_id

Search for subscriptions

Find subscriptions by customer_id


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/customers/{customer_id}/subscriptions

Returned contents of search for a customer profile

[
  {
    "id": 456,
    "subscription_plan_id": 5,
    "status": "active",
    "metadata": {
      "created_by": "admin@yourdomain.com",
      "reason": "promotional"
    },
    "total_seats": null,
    "bulk_purchase": false,
    "gateway_subscription": {
      "gateway_provider": "stripe",
      "billing_period": "monthly",
      "billing_amount_cents": 2999,
      "billing_currency": "USD",
      "next_billing_period": "2027-07-01T00:00:01Z"
    }
  }
]

The customer_id is the same as the user_id from the portal.

Mandatory parameters for finding a subscription

Parameter name	Type	Description
customer_id	string	aka `user_id`, that identifies the customer

Subscription attributes returned

Attribute name	Type	Description
id	integer	Unique identifier for this customer's subscription
subscription_plan_id	integer	Unique identifier for the subscription plan
status	string	One of `active` or `inactive`
metadata	object	Customer-defined key-value data for manual subscriptions
bulk_purchase	boolean	Defines if this is a bulk (team) purchase
total_seats	integer	Total seats purchased. Applies only when `bulk_purchase=true`
gateway_subscription	object or `null`	Billing details from payment gateway; `null` for manual subscriptions

Gateway subscription object attributes

Attribute name	Type	Description
gateway_provider	string	Payment provider such as Stripe
billing_period	string	One of `monthly` `yearly`
billing_amount_cents	integer	Sum in the smallest denomination
billing_currency	string	ISO code for the currency used for billing
next_billing_period	string or null	Date and time for next billing period; `null` for manual subscriptions

Create a subscription manually

Creating a subscription manually assigns a subscription_id without a payment gateway. The gateway_subscription object is null for a manual subscription.

It returns the rest of the subscription data, similar to data returned for searching for a subscription. See Subscription attributes returned.

Create a manual subscription with customer_id and subscription_plan_id


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

'{"metadata": {"created_by": "admin@yourdomain.com","reference_id": "LMS-12345"}}'
https://yourdomain.learnupon.com/api/v1/ecommerce/customers/{customer_id}/subscriptions/{subscription_plan_id}

Mandatory parameters for creating a manual subscription

Parameter name	Type	Description
customer_id	string	aka `user_id`, that identifies the customer
subscription_plan_id	integer	Unique identifier for the subscription plan

Update a subscription

You can change a subscription status, or update metadata. The endpoint returns the changed data and metadata, and any payment details.

Update a subscription with customer_id and user_subscription_id


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

'{"status": "active","metadata": {}}'
https://yourdomain.learnupon.com/api/v1/ecommerce/customers/{customer_id}/subscriptions/{user_subscription_id}

Mandatory parameters for updating a subscription

Parameter name	Type	Description
customer_id	string	aka `user_id`, that identifies the customer
user_subscription_id	integer	Unique identifier for the customer's subscription, returned when you create a subscription
status	string	One of `active` or `inactive`
metadata	object	Customer-defined key-value data for manual subscriptions

Get all subscription plans for your storefront

View your eCommerce subscription catalog. This endpoint returns an array of all the active subscriptions available.

List subscriptions


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

Sample active subscriptions returned

[
    {
        "id": 90,
        "name": "All access",
        "description": "<ul><li>all courses</li><li>all learning journeys</li><li>all bundled content</li></ul>",
        "tag_line": "Access to the whole catalog",
        "status": "active",
        "gateway_provider": "stripe",
        "trial_period_days": 14,
        "periods": [
            "monthly",
            "yearly"
        ],
        "prices": [
            {
                "currency": "EUR",
                "period": "monthly",
                "amount": 10.0
            },
            {
                "currency": "EUR",
                "period": "yearly",
                "amount": 100.0
            },
            {
                "currency": "USD",
                "period": "monthly",
                "amount": 8.0
            },
            {
                "currency": "USD",
                "period": "yearly",
                "amount": 80.0
            }
        ]
    }
]

Subscription plans array data attributes

Attribute name	Type	Description
id	integer	Unique identifier for this subscription plan
name	string	Subscription plan name visible to customers
description	string	Long description of the subscription plan. Can contain HTML formatting
tag_line	string	Short 1-line description of the plan
status	string	Default `active`
gateway_provider	string	Default `stripe`
trial_period_days	integer	Number of days allowed for a free trial. `0`= no free trial, subscription starts immediately
periods	[array, string]	Lists 1 or both of `monthly` or `yearly`
prices	array	List of prices, period and amounts for each currency

Subscription prices array data attributes

Attribute name	Type	Description
currency	string	Short code for each currency supported
period	string	One of `monthly` or `yearly`
amount	numeric float	Sum of the subscription for each period. Can be `null` if the subscription is not offered in a given currency

Get individual subscription plans for your storefront

Find an individual subscription plan using subscription_plan_id. This endpoint returns individual active subscriptions, with the same data attributes described for Subscription plans data attributes.

Get individual subscription plans


curl -X GET -H "Content-Type: application/json" --user 988d4f1313f881e5ac6bfdfc7f54244aab:905a12r3a0c -d
https://yourdomain.learnupon.com/api/v1/ecommerce/subscription-plans/{subscription_plan_id}

Mandatory parameters for finding an individual subscription

Parameter name	Type	Description
subscription_plan_id	integer	Unique identifier for the subscription plan

View gift cards

Search for gift card details


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

Sample returned attributes for a gift card

{
    "id": "gc_s18jaGonyx",
    "code": "SUMMER GIFTS",
    "status": "active",
    "currency": "EUR",
    "amount": "20.0",
    "amount_used": "0.0",
    "amount_authorized": "0.0",
    "amount_remaining": "20.0",
    "display_amount": "€20.00",
    "display_amount_used": "€0.00",
    "display_amount_remaining": "€20.00",
    "expires_at": "2026-09-01",
    "redeemed_at": null,
    "expired": false,
    "active": true
}

This endpoint lets you view gift card details.

You need to create gift cards through the eCommerce UI.

Mandatory parameters for listing gift cards

Parameter name	Type	Description
gift_card_id	string	Unique identifier for the gift card

Gift cards returned attributes

Attribute name	Type	Description
id	string	Unique identifier for the gift card
code	string	Name of the gift card
status	string	One of `active` or `expired`
currency	string	ISO code for the currency for this product
amount	string	Gift card value
amount_used	string	For cards in use
amount_authorized	string	For cards in use
amount_remaining	string	Sum still available
display_amount	string	Value of gift card shown to the buyer in their preferred currency
display_amount_used	string	Value of used gift card shown to the buyer in their preferred currency
display_amount_remaining	string	Value still available shown to the buyer in their preferred currency
expires_at	time/date	Expiry date in YYYY-MM-DD format
redeemed at	time/date	Date the card is used in YYYY-MM-DD format. Can be `null`
expired	boolean	Indicates if the card has expired. Default `false`
active	boolean	Indicates if the card is available for use. Default `true`

Appendix

Language codes

Possible values for language attribute of users when creating or updating

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

Timezone names

LearnUpon supports the following timezones, in API calls and in the application. The list is displayed as an array.


[{:id=>"International Date Line West", :name=>"(GMT-12:00) International Date Line West"},
 {:id=>"American Samoa", :name=>"(GMT-11:00) American Samoa"},
 {:id=>"Midway Island", :name=>"(GMT-11:00) Midway Island"},
 {:id=>"Hawaii", :name=>"(GMT-10:00) Hawaii"},
 {:id=>"Alaska", :name=>"(GMT-08:00) Alaska"},
 {:id=>"Arizona", :name=>"(GMT-07:00) Arizona"},
 {:id=>"Mazatlan", :name=>"(GMT-07:00) Mazatlan"},
 {:id=>"Pacific Time (US & Canada)", :name=>"(GMT-07:00) Pacific Time (US & Canada)"},
 {:id=>"Tijuana", :name=>"(GMT-07:00) Tijuana"},
 {:id=>"Central America", :name=>"(GMT-06:00) Central America"},
 {:id=>"Chihuahua", :name=>"(GMT-06:00) Chihuahua"},
 {:id=>"Guadalajara", :name=>"(GMT-06:00) Guadalajara"},
 {:id=>"Mexico City", :name=>"(GMT-06:00) Mexico City"},
 {:id=>"Monterrey", :name=>"(GMT-06:00) Monterrey"},
 {:id=>"Mountain Time (US & Canada)", :name=>"(GMT-06:00) Mountain Time (US & Canada)"},
 {:id=>"Saskatchewan", :name=>"(GMT-06:00) Saskatchewan"},
 {:id=>"Bogota", :name=>"(GMT-05:00) Bogota"},
 {:id=>"Central Time (US & Canada)", :name=>"(GMT-05:00) Central Time (US & Canada)"},
 {:id=>"Lima", :name=>"(GMT-05:00) Lima"},
 {:id=>"Quito", :name=>"(GMT-05:00) Quito"},
 {:id=>"Caracas", :name=>"(GMT-04:00) Caracas"},
 {:id=>"Eastern Time (US & Canada)", :name=>"(GMT-04:00) Eastern Time (US & Canada)"},
 {:id=>"Georgetown", :name=>"(GMT-04:00) Georgetown"},
 {:id=>"Indiana (East)", :name=>"(GMT-04:00) Indiana (East)"},
 {:id=>"La Paz", :name=>"(GMT-04:00) La Paz"},
 {:id=>"Puerto Rico", :name=>"(GMT-04:00) Puerto Rico"},
 {:id=>"Santiago", :name=>"(GMT-04:00) Santiago"},
 {:id=>"Atlantic Time (Canada)", :name=>"(GMT-03:00) Atlantic Time (Canada)"},
 {:id=>"Brasilia", :name=>"(GMT-03:00) Brasilia"},
 {:id=>"Buenos Aires", :name=>"(GMT-03:00) Buenos Aires"},
 {:id=>"Montevideo", :name=>"(GMT-03:00) Montevideo"},
 {:id=>"Newfoundland", :name=>"(GMT-02:30) Newfoundland"},
 {:id=>"Mid-Atlantic", :name=>"(GMT-02:00) Mid-Atlantic"},
 {:id=>"Cape Verde Is.", :name=>"(GMT-01:00) Cape Verde Is."},
 {:id=>"Azores", :name=>"(GMT+00:00) Azores"},
 {:id=>"Monrovia", :name=>"(GMT+00:00) Monrovia"},
 {:id=>"UTC", :name=>"(GMT+00:00) UTC"},
 {:id=>"Casablanca", :name=>"(GMT+01:00) Casablanca"},
 {:id=>"Dublin", :name=>"(GMT+01:00) Dublin"},
 {:id=>"Edinburgh", :name=>"(GMT+01:00) Edinburgh"},
 {:id=>"Lisbon", :name=>"(GMT+01:00) Lisbon"},
 {:id=>"London", :name=>"(GMT+01:00) London"},
 {:id=>"West Central Africa", :name=>"(GMT+01:00) West Central Africa"},
 {:id=>"Amsterdam", :name=>"(GMT+02:00) Amsterdam"},
 {:id=>"Belgrade", :name=>"(GMT+02:00) Belgrade"},
 {:id=>"Berlin", :name=>"(GMT+02:00) Berlin"},
 {:id=>"Bern", :name=>"(GMT+02:00) Bern"},
 {:id=>"Bratislava", :name=>"(GMT+02:00) Bratislava"},
 {:id=>"Brussels", :name=>"(GMT+02:00) Brussels"},
 {:id=>"Budapest", :name=>"(GMT+02:00) Budapest"},
 {:id=>"Copenhagen", :name=>"(GMT+02:00) Copenhagen"},
 {:id=>"Harare", :name=>"(GMT+02:00) Harare"},
 {:id=>"Kaliningrad", :name=>"(GMT+02:00) Kaliningrad"},
 {:id=>"Ljubljana", :name=>"(GMT+02:00) Ljubljana"},
 {:id=>"Madrid", :name=>"(GMT+02:00) Madrid"},
 {:id=>"Paris", :name=>"(GMT+02:00) Paris"},
 {:id=>"Prague", :name=>"(GMT+02:00) Prague"},
 {:id=>"Pretoria", :name=>"(GMT+02:00) Pretoria"},
 {:id=>"Rome", :name=>"(GMT+02:00) Rome"},
 {:id=>"Sarajevo", :name=>"(GMT+02:00) Sarajevo"},
 {:id=>"Skopje", :name=>"(GMT+02:00) Skopje"},
 {:id=>"Stockholm", :name=>"(GMT+02:00) Stockholm"},
 {:id=>"Vienna", :name=>"(GMT+02:00) Vienna"},
 {:id=>"Warsaw", :name=>"(GMT+02:00) Warsaw"},
 {:id=>"Zagreb", :name=>"(GMT+02:00) Zagreb"},
 {:id=>"Zurich", :name=>"(GMT+02:00) Zurich"},
 {:id=>"Athens", :name=>"(GMT+03:00) Athens"},
 {:id=>"Baghdad", :name=>"(GMT+03:00) Baghdad"},
 {:id=>"Bucharest", :name=>"(GMT+03:00) Bucharest"},
 {:id=>"Cairo", :name=>"(GMT+03:00) Cairo"},
 {:id=>"Helsinki", :name=>"(GMT+03:00) Helsinki"},
 {:id=>"Istanbul", :name=>"(GMT+03:00) Istanbul"},
 {:id=>"Jerusalem", :name=>"(GMT+03:00) Jerusalem"},
 {:id=>"Kuwait", :name=>"(GMT+03:00) Kuwait"},
 {:id=>"Minsk", :name=>"(GMT+03:00) Minsk"},
 {:id=>"Moscow", :name=>"(GMT+03:00) Moscow"},
 {:id=>"Nairobi", :name=>"(GMT+03:00) Nairobi"},
 {:id=>"Riga", :name=>"(GMT+03:00) Riga"},
 {:id=>"Riyadh", :name=>"(GMT+03:00) Riyadh"},
 {:id=>"Sofia", :name=>"(GMT+03:00) Sofia"},
 {:id=>"St. Petersburg", :name=>"(GMT+03:00) St. Petersburg"},
 {:id=>"Tallinn", :name=>"(GMT+03:00) Tallinn"},
 {:id=>"Vilnius", :name=>"(GMT+03:00) Vilnius"},
 {:id=>"Volgograd", :name=>"(GMT+03:00) Volgograd"},
 {:id=>"Tehran", :name=>"(GMT+03:30) Tehran"},
 {:id=>"Abu Dhabi", :name=>"(GMT+04:00) Abu Dhabi"},
 {:id=>"Baku", :name=>"(GMT+04:00) Baku"},
 {:id=>"Muscat", :name=>"(GMT+04:00) Muscat"},
 {:id=>"Samara", :name=>"(GMT+04:00) Samara"},
 {:id=>"Tbilisi", :name=>"(GMT+04:00) Tbilisi"},
 {:id=>"Yerevan", :name=>"(GMT+04:00) Yerevan"},
 {:id=>"Kabul", :name=>"(GMT+04:30) Kabul"},
 {:id=>"Almaty", :name=>"(GMT+05:00) Almaty"},
 {:id=>"Astana", :name=>"(GMT+05:00) Astana"},
 {:id=>"Ekaterinburg", :name=>"(GMT+05:00) Ekaterinburg"},
 {:id=>"Islamabad", :name=>"(GMT+05:00) Islamabad"},
 {:id=>"Karachi", :name=>"(GMT+05:00) Karachi"},
 {:id=>"Tashkent", :name=>"(GMT+05:00) Tashkent"},
 {:id=>"Chennai", :name=>"(GMT+05:30) Chennai"},
 {:id=>"Kolkata", :name=>"(GMT+05:30) Kolkata"},
 {:id=>"Mumbai", :name=>"(GMT+05:30) Mumbai"},
 {:id=>"New Delhi", :name=>"(GMT+05:30) New Delhi"},
 {:id=>"Sri Jayawardenepura", :name=>"(GMT+05:30) Sri Jayawardenepura"},
 {:id=>"Kathmandu", :name=>"(GMT+05:45) Kathmandu"},
 {:id=>"Dhaka", :name=>"(GMT+06:00) Dhaka"},
 {:id=>"Urumqi", :name=>"(GMT+06:00) Urumqi"},
 {:id=>"Bangkok", :name=>"(GMT+07:00) Bangkok"},
 {:id=>"Hanoi", :name=>"(GMT+07:00) Hanoi"},
 {:id=>"Jakarta", :name=>"(GMT+07:00) Jakarta"},
 {:id=>"Krasnoyarsk", :name=>"(GMT+07:00) Krasnoyarsk"},
 {:id=>"Novosibirsk", :name=>"(GMT+07:00) Novosibirsk"},
 {:id=>"Beijing", :name=>"(GMT+08:00) Beijing"},
 {:id=>"Chongqing", :name=>"(GMT+08:00) Chongqing"},
 {:id=>"Hong Kong", :name=>"(GMT+08:00) Hong Kong"},
 {:id=>"Irkutsk", :name=>"(GMT+08:00) Irkutsk"},
 {:id=>"Kuala Lumpur", :name=>"(GMT+08:00) Kuala Lumpur"},
 {:id=>"Perth", :name=>"(GMT+08:00) Perth"},
 {:id=>"Singapore", :name=>"(GMT+08:00) Singapore"},
 {:id=>"Taipei", :name=>"(GMT+08:00) Taipei"},
 {:id=>"Ulaanbaatar", :name=>"(GMT+08:00) Ulaanbaatar"},
 {:id=>"Osaka", :name=>"(GMT+09:00) Osaka"},
 {:id=>"Sapporo", :name=>"(GMT+09:00) Sapporo"},
 {:id=>"Seoul", :name=>"(GMT+09:00) Seoul"},
 {:id=>"Tokyo", :name=>"(GMT+09:00) Tokyo"},
 {:id=>"Yakutsk", :name=>"(GMT+09:00) Yakutsk"},
 {:id=>"Adelaide", :name=>"(GMT+09:30) Adelaide"},
 {:id=>"Darwin", :name=>"(GMT+09:30) Darwin"},
 {:id=>"Brisbane", :name=>"(GMT+10:00) Brisbane"},
 {:id=>"Canberra", :name=>"(GMT+10:00) Canberra"},
 {:id=>"Guam", :name=>"(GMT+10:00) Guam"},
 {:id=>"Hobart", :name=>"(GMT+10:00) Hobart"},
 {:id=>"Melbourne", :name=>"(GMT+10:00) Melbourne"},
 {:id=>"Port Moresby", :name=>"(GMT+10:00) Port Moresby"},
 {:id=>"Sydney", :name=>"(GMT+10:00) Sydney"},
 {:id=>"Vladivostok", :name=>"(GMT+10:00) Vladivostok"},
 {:id=>"Magadan", :name=>"(GMT+11:00) Magadan"},
 {:id=>"New Caledonia", :name=>"(GMT+11:00) New Caledonia"},
 {:id=>"Solomon Is.", :name=>"(GMT+11:00) Solomon Is."},
 {:id=>"Srednekolymsk", :name=>"(GMT+11:00) Srednekolymsk"},
 {:id=>"Auckland", :name=>"(GMT+12:00) Auckland"},
 {:id=>"Fiji", :name=>"(GMT+12:00) Fiji"},
 {:id=>"Kamchatka", :name=>"(GMT+12:00) Kamchatka"},
 {:id=>"Marshall Is.", :name=>"(GMT+12:00) Marshall Is."},
 {:id=>"Wellington", :name=>"(GMT+12:00) Wellington"},
 {:id=>"Chatham Is.", :name=>"(GMT+12:45) Chatham Is."},
 {:id=>"Nuku'alofa", :name=>"(GMT+13:00) Nuku'alofa"},
 {:id=>"Samoa", :name=>"(GMT+13:00) Samoa"},
 {:id=>"Tokelau Is.", :name=>"(GMT+13:00) Tokelau Is."}]