Use the API to manage courses and assignments

Step 1 – Provision a course

To provision a course a POST request must be made to: 

POST ​/api​/v2​/schools/{school_id}/courses

The attributes for creating courses are listed in the schema section of the course documentation

External_id
The external_id can be used to add a reference to a unique id of a course in your own organisation. You can use the external_id alongside the Search API to find a course in Ans based on the provided external_id.

Step 2 – Add users to a course

To add users to a course a PATCH request must be made to:

PATCH ​/api​/v2​/courses/{course_id}

Users can be added to a course with one of the following four roles: 

• Instructors
• Invigilators
• Learners
• Reviewers

Set a custom role when adding a user to a course
You can provide a role_id in the API request for course users, that will set the custom role with that id for that user within that course. You can update the role id to the course user here or create it when you create the course user. The role id can be found here.

Additional information about roles in courses can be found here. 

Additional Information about updating courses
Learners have an extra attribute “extra_time”, which allows the learner to receive extra time within an exam.

It is possible to give users (excluding learners) a custom role in the course, by setting the role_id. As of this moment, custom roles can only be created through the interface and are only available through a beta feature.

To retrieve the roles a GET request must be made to:

GET ​/api​/v2​/schools/{school_id}/roles

Step 3 – Provision an assignment

To provision an assignment a POST request must be made to:

POST ​/api​/v2​/courses/{course_id}/assignments

The attributes for creating assignments are listed in the schema section of the assignment documentation.

External_id
The external_id can be used to add a reference to a unique id of an assignment in your own organisation. You can use the external_id alongside the Search API to find an assignment in Ans based on the provided external_id.

Reviewers
Before the reviewers can be assigned to an assignment, they must already be a part of the course. Reviewers can be set for the assignment in two ways, namely exercise reviewers and group reviewers.

Exercise reviewers are only allowed to review the specific exercises they are assigned to, unless they have the instructor role. Then they can review any of the exercises. 

The obtain the list of exercises of an assignment, a GET request must be made to:

GET ​/api​/v2​/assignments/{assignment_id}/exercises

Group reviewers are only allowed to review the exercises for the groups they are assigned to, unless they have the instructor role. Then they can review any of the groups. 

The obtain the list of groups of a course, a GET request must be made to:

GET ​/api​/v2​/courses/{course_id}/groups

Integrations
Ans allows you to enable and disable integrations with third party tools via the API. At this moment, the following tools can be enabled via the API:

• Canon Exam Services
• Ouriginal
• ProctorExam
• Proctorio
• Safe Exam Browser
• Safe Exam Browser Server
• Schoolyear
• STEP

To enable the integration, you have the option to enable an integration and directly set the default configuration. The configuration options differ per integration. For some integrations, the default configuration can be set on school level. In all other cases, the default configurations are documented in the scheme part of the API documentation.

To enable the integration with the default configuration which is set on school level, you can send "{}" as value for the attribute of the tool:

{
..,
"integrations": {
"ouriginal": {}
},
...
}

If you want to enable the integration with other settings than the default settings, you can set these by using the different attributes. Below you can find an example for Ouriginal. Ouriginal has only one setting which can be set via the API, which is whether results are automatically submitted to Ouriginal. There are no settings available in the school settings of Ouriginal. The default settings are available in the scheme documentation. Here, you can also see see which options are available per tool. For Ouriginal an example value can be:

{
..,
"integrations": {
"ouriginal": {
"auto_submit": false
}
},
...
}

To disable an integration, you can send the value "null", as you can see below:

{
..,
"integrations": {
"ouriginal": null
},
...
}

Step 4 – Add timeslots to an assignment

To provision a timeslot a POST request must be made to:

POST ​/api​/v2​/assignments/{assignment_id}/timeslots

The attributes for creating timeslots are listed in the schema section of the timeslot documentation.

Users are granted access to an assignment based on the range of dates and times set in the timeslot.

External_id
The external_id can be used to add a reference to a timeslot for an assignment. You can use the external_id alongside the Search API to find a timeslot in Ans based on the provided external_id.

A time limit for the assignment can be set with the “duration” attribute, where the value represents the amount of minutes.

The timeslot can either have a group set or a klass set but not both. If neither the attribute “group_id” or “klass_id” are set, then the timeslot for the assignment is available for all students.