Developer APIs to Manage Enrollments Programmatically

Introduction

Enrollment APIs are a set of JSON APIs that allow a client to programmatically register learners in NovoEd as well as get information on the status of a registration. These APIs are suitable for clients who have their own portal for listing their online offerings and are looking for a programmatic way to connect their online portal with NovoEd. 

Step 1: Get Started with an API Key and Secret

Customers need an API key and secret to make any API calls to NovoEd. The API key and secret belong to a developer, an app, or a development organization. A key can be whitelisted and able to access data from one course or the whole institution on NovoEd. The API key and secret can also be used to get private user information from NovoEd and write data to a customer’s instance. It is as powerful as a Super Admin role in the scope it is given access to. Customers can choose to make the API key and secret more secure by only enabling a dedicated set of IP addresses to use them. Or, customers may choose to allow any machine who has the key and secret to make API calls.

Customers should write to the NovoEd customer support at hello@novoed.com with the list of IP addresses of the machines that would be making API calls. The support team can whitelist those specific IP addresses. Customers may also choose to let any machine in the world who has the key and secret make calls. A customer’s technical team may refer to this as one-factor (only using key and secret) or two-factor (enabling only specific machines with a specific IP address) authentication for API calls.

Once a key and secret are obtained, customers should work with their NovoEd Org Admin to whitelist this key for one course or across the institution. Unfortunately, the NovoEd support team cannot help with this step. Instructions on how to whitelist an API key in one course or across the institution are listed below.

Whitelisting an API key

An Org Admin can log into a specific course in the institution, click on the wrench menu in the top right, choose Admin Dashboard, and choose configurations after to see the API key section.

Under API keys, the Org Admin can whitelist the key to manage this course and decide whether the key can manage any course across the institution.

The API key can be whitelisted for individual courses without linking it to the institution. 

Troubleshooting Whitelisting

• Make sure the key and secret are valid. Customers will receive a 401 error if they are not.
• Make sure calls are being made from an IP address that is authorized to use the key and secret. A 401 error will also be received here if they are not. 
• Make sure a JSON call is being made. This can be done by adding .json to the end of the endpoint before starting to pass the parameters. If the wrong request type is made or HTTP is being requested instead of JSON, an error page will show.

Step Two: Set Up Enrollment APIs

Note that before you are able to use the Enrollment APIs, you will need to request an API Key and Secret in Step One. You may choose to allow any IP address to make API calls with your key and secret. API whitelisting is a two-factor authentication technique and it is your choice whether you want to use it.

After obtaining a key and secret, the API key and secret must be whitelisted in a course or across the institution from the NovoEd product to allow for the following set of APIs to be called. 

Endpoints

There are four endpoints:

1. POST To register a new learner
2. POST Unregister a learner
3. POST Resend welcome email
4. GET Registration information (enrollment status)

For Developers:  See our call documentation here

Rate Limiting

We ensure the integrity of our API endpoints, NovoEd limits usage of our API on a per key basis. Here are the rate limits:

“Time span” is determined by when a request first comes in. Within the next time span, the requestor cannot exhaust the number of requests allowed within that time period.

Notes

For NovoEd, one cannot create a user without registering them in a course. A user is relevant only within the context of a course, so the Register New Learner API will create a new user in a course.

You may call the same endpoint to update first name and last name of the user with the same email address; the email address identifies the user

“Unenroll” removes user access, which is the closest NovoEd has to disabling a user.

Troubleshooting

If you receive a 503 from any of the following endpoints, you are probably being throttled due to back-end capacity issues or because you have reached quota.

We recommend implementing an exponential backoff and retrying the call until 200 success is reached. Of course, retries should be limited and errors communicated back to the caller.

External Id can be present when SSO based on external id is enabled. Register New Learner requires the existence of email, however in all other calls providing email address or external id is sufficient and you do not need to provide both. If both are provided, NovoEd will user external_id as the primary id.