API parameters
The parameters transmitted on starting a proctored exam are described in the table below.
Mandatory parameters are marked with *.
| Parameter group | Field | Type | Max. length | Description |
|---|---|---|---|---|
| User parameters | userId* | string | 255 | User ID in the client’s system (it can be an employee number or GUID). It must be unique for every user. |
| User email address in the client system. | ||||
| lastName | string | 255 | User last name. | |
| firstName | string | 255 | User first name. | |
| thirdName | string | 255 | User middle name or patronymic. | |
| language | string (enum) | 2 | 2-character language code from ISO 639-1. Ask your integration manager at Constructor to specify the available languages and to activate the ones you are planning to use. | |
| Organization / company parameters | accountId* | string | 255 | Company ID in the client’s system. Different accountIds are necessary if the LMS is used by several organizations or departments that you need to distinguish between themselves and restrict access to each of them. |
| accountName* | string | 255 | Company name in the client’s system. | |
| Exam parameters | courseName | string | 450 | Course name, if the exam belongs to this course. |
| examId* | string | 255 | Exam ID (test ID in the system, preferably GUID). | |
| examName* | string | 500 | Exam name. | |
| userAgreementUrl | string (URL) | 200 | A link to a document containing the exam regulations that will be displayed right before the exam starts | |
| duration* | int | — | Exam duration in minutes | |
| schedule* | boolean | — | Parameter specifying whether the user needs to sign up for the exam in the calendar. | |
| proctoring* | string (enum) | — | Proctoring mode. The possible values are * online with a real-time proctor, * offline in case of the post-review mode, * auto in case of automatic conclusion by the system’s algorithms | |
| startDate* | string (datetime) | — | Date and time that marks the start of the test in the ISO 8601 format. The user can start the test only after startDate. It is required to set the time offset explicitly or to use a special format for UTC. In case when the exam does not require scheduling, this parameter is set individually for eash proctoring session (so it will be not an exam parameter, but a session parameter). | |
| endDate* | string (datetime) | — | Date and time that marks the end of the test (UTC, ISO 8601). The user can start the test only before endDate. In case when the exam does not require scheduling, this parameter is set individually for eash proctoring session (so it will be not an exam parameter, but a session parameter). | |
| allowMultipleDisplays | boolean | — | Parameter indicating whether the use of an additional monitor during the exam is allowed. The default value is false. | |
| allowVirtualEnvironment | boolean | — | Parameter indicating whether the use of a virtual environment for launching the proctoring is allowed. The default value is false. | |
| auxiliaryCamera | boolean | — | Enable an additional camera from the smartphone in the exam. | |
| auxiliaryCameraMode | string (enum) | — | Operation mode of the additional (second) camera: * photo — the second camera takes a photo every 30 seconds. * video — the second camera records video. | |
| allowMakingRoomScanSecondCamera | boolean | — | Parameter indicating whether the use of an auxiliary camera for room scan is allowed. The default value is false. | |
| calculator | string (enum) | — | Mode of using the calculator within the proctoring application: * off — the calculator is prohibited. * simple — only the use of simple arithmetic operations is permitted. * scientific — advanced operations are permitted. | |
| checkIdPhotoQuality | boolean | — | Parameter indicating whether the automatic document quality check is required (true). The default value is false. | |
| desktopAppForbiddenProcesses | JSON | — | A list of lines, where each line is the name of a forbidden process. An empty list means no blocked processes. Default is the preset list. | |
| desktopAppAllowedProcesses | JSON | — | A list of lines, where each line is the name of an allowed process. An empty list means no allowed processes. The default value is empty. | |
| identification | string (enum) | — | The mode of taking a picture for the exam, one of the following values: * passport * face * face_and_passport * skip | |
| proctorEmails | JSON | — | Parameter that enables assigning specific proctors to a specific exam. This option is available only for the Live review mode. | |
| rules | JSON parameters | — | JSON structure with the exam rules. | |
| scoreConfig | JSON | — | Score calculation parameters. | |
| trial | boolean | — | Parameter indicating whether the exam is trial. Trial exams are not listed in the archive. The default value is false. | |
| userAgreementUrl | string (URL) | 200 | A link to a document containing the exam regulations that will be displayed right before the exam starts. | |
| visibleWarnings | JSON | — | Warning display options. | |
| webCameraMainView | string (enum) | — | Location of the web camera that is considered main during the exam: * front — the front camera is main. * side — the side camera is main. | |
| streamsPreset | string (enum) | — | The mode of recording video for the exam. The values are as follows: * default — recording is performed from the webcam and desktop, as well as a second camera (depending on the settings). * no_video — recommended for use only when using the Secure Browser in the high security mode. * no_ai_detection — full video recording is performed, but there is no AI processing of the recordings. | |
| sendManualWarningsToLearner | boolean | — | This parameter indicates whether warnings added by a live proctor should be shown to the learner. The default value is true. | |
| shortName | string | 255 | Course code or short name of the course to which the exam belongs. | |
| Session parameters | sessionId* | string | 230 | Session ID in the system, preferably GUID. Must be unique within the system. |
| sessionUrl* | string (URL) | 2550 | Link to the exam test in the LMS. | |
| reviewUrl | string (URL) | 600 | The URL where the proctoring result will be sent. It overrides review_url for the session | |
| sessionFinishUrl | string (URL) | 2550 | The URL of the page where the test taker should be redirected to when the exam is over. It can also be passed at the end of the session. | |
| special_accommodations_info | string | 500 | Parameter indicating whether a learner requires special accommodations during testing. | |
| Environment parameters | secureBrowser | boolean | — | Parameter indicating whether to open the exam in a lockdown browser. The exact browser should be chosen in advance. |
| secureBrowserLevel | string (enum) | — | Secure Browser mode to use during exams: * basic * medium * high | |
| preliminaryCheck | JSON | — | Preliminary check parameters used for the examinee's identification before the exam. |
It is possible to change the parameters of a user or an exam in Constructor Proctor after they have been created. To do this, you need to pass the same user, exam, and session ID as was used before and the updated parameter values. For example, you can change the duration and rules of an exam, or the language of a user.
Constructor Proctor creates a user according to the passed data (or uses an existing user), authorizes them and creates a proctoring session. After that, the test taker starts a proctoring session, gets through the identification and connection check, and in case of success Constructor Proctor redirects the user to the test URL which was provided in the sessionUrl.
If during the proctoring session the user got disconnected or other technical problems occurred, so that the exam page was closed, the test taker can go back to the test using the same link as for the start. That is possible for 5–15 minutes, depending on the timeout set on the Constructor Proctor server. If the user has been disconnected for too long, the proctoring session will finish automatically, after that the test taker will have to get a new link with a new sessionId.