Our API enables customers to register users and/or enroll them in existing Qstreams.

 PLEASE NOTE Any integrations with our API are entirely on the customer to implement and are limited to the current API capabilities as documented below.

Getting Started

Pre-requisites

• Qstream site URL

• Application ID & Secret Key

These prerequisites will provided to you by Qstream upon request.

 

Interacting with the API

All communication with the API must be via HTTPS. HTTP connections will be refused. The endpoint for the API is: https://api.qstream.com/api/

All requests must include the Application ID and Secret Key in the URL params as follows: https://api.qstream.com/api/method?application_id=appID&secret_key=secret​Key

Method Parameters are provided using HTTP POST data. This data should be provided as well formed XML.

Responses will have valid HTTP response codes and return well formed XML bodies.

 

API Methods

Enrollments/Create

This method is used to enroll a user in a course on Qstream. User details are POSTed as XML in the request parameters. In order to identify the course an external ID may be associated with courses on Qstream. This ID is then used in the request parameters.

By default, new users are not sent an introductory email (“Welcome to Qstream”). Rather, the course author or company introduces the new users to Qstream, and users receive daily emails starting the following day. This can be overridden so that users receive a welcome email.

Assign External ID to Course

External IDs are assigned to courses in the course editor. This ID must be unique in our system.

 

Method Name

Method	Action	Example
enrollments	POST	https://api.qstream.com/api/enrollments?application_id=appID&sec ret_key=secretKey

 

Parameters

Top level elements are ​<user> ​and ​<courses>​ (Note, only one user per API call).

 

User Parameters 

Element	Purpose	Required when:
<external_id>	Client ID or other identifier on the created user (used to look up if user exists)	No email or delivery_email provided
<email>	Main email address for user (used to look up if user with external_id not found)	No external_id or delivery_email provided
<delivery_email>	Alternate email address (used in look up if user with external_id or email not found)	No external_id or email provided
<first_name>	User's first name	Optional
<last_name>	User's last name	Optional
<send_email />	set to true to force sending of non-customizable Qstream email (recommended only under specific circumstances)	Optional
<dashboard_url />	Authenticated link to user's Qstream dashboard. User will be prompted to create a new password if that option is set, otherwise they will be required to enter their existing password to make changes to their account.	Optional

 

Courses

The <courses> tag takes a number of <course> elements, each course element has one required sub-element: ​<external_id>.​ This will be used to look up the course.

User:

• First name, last name, email.

• Optionally delivery email and external ID can be specified for the user

• Optionally, an introductory email can be forced. If send_email is true, an introductory email will be sent. Any other value will be ignored.

• The external ID must be unique and can be used for single sign on solutions

(User External ID is not available through GUI)

Courses - A list of courses identified by external ID

 

XML example:

Here is an ​example​ cUrl command on the command line which will enroll Joe Smith (email: joe.smith@example.com​, external user id: acme-user-123) in the course with the external id of acme-course-777​. The user will be sent an introductory email from Qstream and the authenticated link will be provided.

$curl -d “<?xml version="1.0" encoding="UTF-8"?> 
<xml>
<user>
  <external_id> acme-user-123 </external_id> 
  <first_name>Joe</first_name> 
  <last_name>Smith</last_name> 
  <email>joe.smith@example.com</email> 
  <delivery_email>​joe.smith@example.com​</delivery_email> 
  <send_email />
  <dashboard_url /> 
</user>
<courses> 
     <course>
          <external_id>acme-course-777</external_id> 
     </course>
</courses>
</xml>” -H “Content-Type: text/xml” 
“​https://api.qstream.com/api/enrollments?application_id=1234&secret_key=4321​”

Replace the above with the external_id for a live course and your enterprise’s application_id and secret_key, and this command can be used.

 

Response

Response is an XML element in the following form:

<?xml version="1.0" encoding="UTF-8"?> 
<response>
     <code> ... </code>
     <message> ... </message>
     <detail> ... </detail>
     <login> ... </login>
     <dashboard_url> ... </dashboard_url>
</response>

 

<code> will be one of the following:

0	Failure
1	User created and enrolled in course
2	User found and enrolled in course
3	User already enrolled in course

 

<message> and <detail> contain information on the calls success. <login> is the user’s Qstream username. <dashboard_url>, if set to true in the request, will be an authenticated link, specific to this user, for logging into their dashboard for the first time.

 

Testing

For testing your application against the API, we provide a couple of extra URL parameters.

Parameter	Description
echo=true	Will respond with the XML sent in the request POST body. This is useful to see if you are sending the request correctly and your XML is well formed.
debug=true	The request will be processed as normal but no objects are created on Qstream. This is useful so that you don't have to create lots of dummy users and enrollments during your development cycle.