○ API calls - Subscriptions
The API calls make it possible to
- check if a learner is subscribed to a course
- check which courses a learner is subscribed to
- retrieve the results of courses, including the scores on activities (but not the answers on questions)
- (un)subscribe a learner to a course
Context
Users that have the role learner can have a subscription to a course.
A subscription can be linked to a subenvironment. By default this is the subenvironment that belongs to the domain in the URL that you use to call the API.
A subscription also has a start date and expire date. The learner can't see the course before the start date. After the expire date, the learner can only view statistics, but not complete any more activities.
A learner that is subscribed to a course can be linked to instructors. Instructors can only see the learners that they are linked to.
Courses consist of activities and one such activity is the external activity. Other kinds of activities get scores that are calculated automatically or they are manually entered by instructors. For the external activity you can use the API to register a score.
Support articles:
- Subscribe learners
- The platform structure
- Subenvironments
- How to extend a course for a learner
- Course settings - Tab: Managing instructor learner
- Which activities can I use in a template?
For historical reasons and to continue to support old API integrations, the terminology of the API and the front-end for administrators does not always match completely. In the API:
- A subenvironment is a Reseller.
- An instructor is a Teacher.
- An activity is a Part or CoursePart.
API calls
You can view more information and an example of each API call in the API Documentation by clicking the titles below. However, all links go to the /apidocs page of a demo environment that you cannot use for your own testing purposes.
To test the API calls, you will need to change the first part of the URL to match the right learning environment.
GET requests
GET /isSubscribed/{userID}/{courseID}
or GET /isSubscribed?userUID={userUID}&courseUID={courseUID}
Use this to check if a specific user (learner) has a subscription to a specific course. You will need to use the external IDs (userID/courseID) or the UIDs (userUID/courseUID) of the user (learner) and course.
GET /getSubscriptions/{userID}
or GET /getSubscriptions?userUID={userUID}
Use this to get all subscriptions of a specific user (learner). It also includes basic information about the subscription.
Example of JSON output:
{ "courses": [ { "active": true, "efficiency": 0.5, "expired": false, "finished": false, "id": "EXAMPLE-00001", "knowledgeIntake": 0.7, "name": "Example course", "objectivesProgress": 0.625, "progress": "1/1", "reseller": "SUBENV-001", "startDate": "2019-03-27", "startDateTime": "2019-03-27T14:23:11Z", "subscribeDate": "2019-03-27", "subscribeDateTime": "2019-03-27T11:08:44Z", "uid": "a62b0793-7682-11eb-b67e-06575dd7e8c5" } ] }
This is what these properties mean:
- active: This is false at first when a learner has been subscribed. It will be true when a learner has started the course.
- efficiency: This is a number between 0 and 1, 1 means 100%. This is related to the number of attempts on MemoTrainable questions.
- expired: This is true if the subscription has expired.
- finished: This is true if the subscription has expired or the learner was unsubscribed manually.
- id: This is the external ID of the course.
- knowledgeIntake: This is a number between 0 and 1, 1 means 100%. Knowledge intake is the learner's progress on having all MemoTrainable questions in the long term memory of the learner.
- name: This is the name of the course.
- objectivesProgress: This is a number between 0 and 1, 1 means 100%. This is the learner's progress on objectives in the course (not all courses have objectives).
- progress: E.g. 11/16. This means that 11 out of 16 available activities have been completed. Activities that are not available due to conditions, don't count in the progress.
- reseller: This is the external ID of the subenvironment that the course is linked to. It will be empty if the subenvironment doesn't have an external ID.
- startDate: This is the start date of the subscription, the learner can't see the course before this date. This will show the actual start date of the learner, and not the start date of the course set in its preservability properties.
- startDateTime: The same as startDate, including the time in UTC.
- subscribeDate: This is the date on which the learner was subscribed to the course.
- subscribeDateTime: The same as subscribeDate, including the time in UTC.
- uid: The uid is a unique ID that is automatically generated. This course is only unique per template and will be the same for multiple courses of the same template.
You will need to use the external ID (userID) or UID (userUID) of the user (learner).
To get more statistics and results of a subscription, it is often better to use our webhooks, because this will send the results to your server in realtime and you will not continuously have to call the API for all users and courses. If you do have a reason to use the API for this, you can use /getResults as described below.
GET /getResults/{userID}
or GET /getResults?userUID={userUID}
Use this to get the results of all subscriptions of a specific user. You will need to use the external ID (userID) or UID (userUID) of the user (learner).
GET /getResults/{userID}/{courseID}
or GET /getResults?userUID={userUID}&courseUID={courseUID}
Use this to get the results of a specific subscription of a specific user. You will need to use the external IDs (userID/courseID) or the UIDs (userUID/courseUID) of the user and the subscribed course.
Example of JSON output:
{ "active": true, "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "efficiency": 0.5, "expired": false, "finished": false, "grade": "67%", "gradeDate": "2020-02-13", "gradeDateTime": "2020-02-13T16:23:55Z", "id": "EXAMPLECOURSE-0001", "knowledgeIntake": 0.4, "lastTrainingCompletedDate": "2020-02-12", "lastTrainingCompletedDateTime": "2020-02-12T08:05:23Z", "name": "Example course", "objectives": [ { "knowledgeIntake": 0.5, "name": "Example objective", "target": 0.8, "value": 0.3 } ], "objectivesProgress": 0.375, "parts": [ { "attempts": [ { "attemptNr": -1, "completeDate": "2020-02-12", "completeDateTime": "2020-02-12T14:20:21Z", "completed": true, "criteria": [ { "id": "EXAMPLECRI-001", "maxScore": 100, "name": "Criterion 1", "score": 100 }, { "id": "EXAMPLECRI-002", "maxScore": 100, "name": "Criterion 2", "score": 100 } ], "passed": true, "progress": null, "score": "100%", "startDate": "2020-02-12", "startDateTime": "2020-02-12T14:14:38Z", "terms": [] } ], "blockName": "Block 1", "completeDate": "2020-02-12", "completeDateTime": "2020-02-12T14:20:21Z", "completed": true, "id": null, "name": "Example hand-in assignment", "partId": 118, "passed": true, "score": "100%", "subType": "SkillAssignment", "type": "SkillAssignment", "uid": "8e28909d-ff9d-4813-9007-dc7c785c62b0" }, { "attempts": [ { "attemptNr": 1, ... }, { "attemptNr": 2, "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "criteria": [], "passed": true, "progress": "3/3", "score": "67%", "startDate": "2020-02-13", "startDateTime": "2020-02-13T16:20:31Z", "terms": [ { "maxScore": 1, "name": "Exam term 1", "score": 1, "threshold": 0 }, { "maxScore": 1, "name": "Exam term 2", "score": 1, "threshold": 0 }, { "maxScore": 1, "name": "Exam term 3", "score": 1, "threshold": 0 } ] } ], "blockName": "Block 1", "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "id": null, "name": "Example assessment", "partId": 223, "passed": true, "score": "67%", "subType": "Assessment", "type": "Assessment", "uid": "c94d938b-0084-4a97-a51c-61e23478c462" } ], "progress": "2/2", "reseller": "EXAMPLEID", "startDate": "2020-02-05", "startDateTime": "2020-02-05T15:38:35Z", "subscribeDate": "2020-02-05", "subscribeDateTime": "2020-02-05T09:00:12Z", "uid": "a62b0793-7682-11eb-b67e-06575dd7e8c5" }
This is what these properties mean:
- active: This is false at first when a learner has been subscribed. It will be true when a learner has started the course.
- completeDate: This is the date on which the course was completed.
- completeDateTime: The same as completeDate, including the time in UTC.
- completed: This is true when the course is completed.
- efficiency: This is a number between 0 and 1, 1 means 100%. This is related to the number of attempts on MemoTrainable questions.
- expired: This is true if the subscription has expired.
- finished: This is true if the subscription has expired or the learner was unsubscribed manually in the course settings.
- grade: This is the score of the activity that was selected at the "Base course grade on" setting in the template.
- gradeDate: This is the date on which the activity that was selected at the "Base course grade on" setting in the template is completed.
- gradeDateTime: The same as gradeDate, including the time in UTC.
- id: This is the external ID of the course.
- knowledgeIntake: This is a number between 0 and 1, 1 means 100%. Knowledge intake is the learner's progress on having all MemoTrainable questions in the long term memory of the learner.
- lastTrainingCompletedDate: This is the date of the last MemoTraining that was completed.
- lastTrainingCompletedDateTime: The same as lastTrainingCompletedDate, including the time in UTC.
- name: This is the name of the course.
- objectives: These are the learning objectives. If a course doesn't have objectives, this will be an empty array.
- knowledgeIntake: This is a number between 0 and 1, 1 means 100%. This is the knowledge intake on the MemoTrainable questions of a specific objective.
- name: This is the name of the objective.
- target: This is the target value of the objective.
- value: This is the learner's current score on the objective.
- objectivesProgress: This is a number between 0 and 1, 1 means 100%. This is the learner's progress on objectives in the course (not all courses have objectives).
- parts:These are the activities in the course.
- attempts:These are the attempts on this activity. Only Assessment type activities can have multiple attempts.
- attemptNr: If multiple attempts are not allowed, this value will be -1. For assessments that allow multiple attempts it will show the attempt number.
- completeDate: This is the date on which the attempt was completed.
- completeDateTime: The same as completeDate, including the time in UTC.
- completed: This is true if the attempt was completed.
- criteria:Criteria can apply to activities that need to be assessed if the activity is set up like that. In other cases, this will be an empty array.
- id: This is the ID of the criterion.
- maxScore: This is the max score of the criterion.
- name: This is the name of the criterion.
- score: This is the score of the criterion.
- passed: This is set to true if an attempt was passed.
- progress: Some activities don't support a progress, in that case the value will be null. For activities that do support a progress, it will show for example "3/3". This means that 3 out of 3 questions and/or content parts are completed in this attempt.
- score: This is the score on the attempt.
- startDate: This is the start date of the attempt.
- startDateTime: The same as startDate, including the time in UTC.
- terms:These are the statistics on exam terms. Exam terms are only possible for Assessment activities. If there are no exam terms, this will be an empty array.
- maxScore: This is the max score of the exam term.
- name: This is the name of the exam term.
- score: This is the score on the exam term.
- threshold: This is the threshold of the exam term.
- blockName: This is the name of the block in which you find the activity.
- completeDate: This is the date on which the activity is completed.
- completeDateTime: The same as completeDate, including the time in UTC.
- completed: This is true if the activity is completed.
- id: This is the external ID of the activity.
- name: This is the name of the activity.
- partId: This is the internal ID of the activity, which is sometimes visible in the URL that learners see.
- passed: This will be true if the learner passed the activity. For activities that don't support a threshold (like a Lesson), this will always be false. Evaluation activities will always show null.
- score: This is the score of the activity. For evaluation activities, this will always be null.
- subtype: This shows the activity type on a more specific level than type. See type for more information.
- type: This shows the activity type. The names of these types don't always correspond to the names that are used in the user interface of aNewSpring:
- Assessment: type "Assessment", sub type "Assessment"
- Random Assessment: type "Assessment", sub type "RandomAssessment". Nowadays, this activity type has been merged with Assessment.
- Fingerprint Assessment: type "Assessment", sub type "FingerPrintAssessment". Nowadays, this activity type has been merged with Assessment.
- Assignment: type "Assignment", sub type "Assignment"
- Certificate: type "Certificate", sub type "Certificate"
- Questionnaire: type "Evaluation", sub type "Inquiry"
- Scan: type "Evaluation", sub type "Scan"
- 360° feedback: type "Evaluation", sub type "360-degrees"
- External activity: type "External", sub type "External"
- Webinar: type "External", sub type "Webinar"
- External activity with LTI: type "External", sub type "LTI-1p0" of "LTI-2p0"
- Lesson: type "Lesson", sub type "Lesson"
- Documentation: type "Lesson", sub type "Documentation"
- SCORM: type "Scorm", sub type "Scorm"
- Hand-in assignment: type "SkillAssignment", sub type "SkillAssignment"
- Video hand-in assignment: type "SkillAssignment", sub type "VideoSkillAssignment" - uid: The uid is a unique ID that is automatically generated. The uid of an activity is only unique on a template level. The same activity in multiple courses of one template will have the same uid.
- attempts:These are the attempts on this activity. Only Assessment type activities can have multiple attempts.
- progress: E.g. 11/16. This means that 11 out of 16 available activities have been completed. Activities that are not available due to conditions, don't count in the progress.
- reseller: This is the external ID of the subenvironment that the course is linked to. It will be empty if the subenvironment doesn't have an external ID.
- startDate: This is the start date of the subscription, the learner can't see the course before this date. This will show the actual start date of the learner, and not the start date of the course set in its preservability properties.
- startDateTime: The same as startDate, including the time in UTC.
- subscribeDate: This is the date on which the learner was subscribed to the course.
- subscribeDateTime: The same as subscribeDate, including the time in UTC.
- uid: The uid is a unique ID that is automatically generated.
GET /getResults/{userID}/{courseID}/{activityID}
or GET /getResults?userUID={userUID}&courseUID={courseUID}&activityID={activityID}
Use this to get the results of a specific activity in a specific subscription for a specific user. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user and the subscribed course and the external ID (activityID) of the activity.
POST requests
POST /subscribe/{userID}/{courseID}
or POST /subscribe?userUID={userUID}&courseUID={courseUID}
Use this to subscribe a specific learner to a specific course. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user (learner) and course.
POST /subscribeGroups/{courseID}
or POST /subscribe?courseUID={courseUID}
Use this to subscribe existing learner groups to a specific course. You will need to use the external ID or UID of the course and external IDs of the groups, which can be sent as an array in the parameter groupID, by repeating the same parameter with different values.
POST /updateSubscription/{userID}/{courseID}
or POST /updateSubscription?userUID={userUID}&courseUID={courseUID}
Use this to change the start date or expiry date for a specific learner and a specific subscription. You can also set the subscription to expired. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user (learner) and the subscribed course.
POST /unsubscribe/{userID}/{courseID}
or POST /unsubscribe?userUID={userUID}&courseUID={courseUID}
Use this to unsubscribe a specific learner from a specific course. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user (learner) and the subscribed course.
POST /scoreExternalActivity/{userID}/{courseID}/{activityID}
or POST /scoreExternalActivity?userUID={userUID}&courseUID={courseUID}&activityID={activityID}
Use this to register a score in a specific external activity for a specific user in a specific course. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user and the subscribed course and the external ID (activityID) of the activity.