CandidateLaunch
https://us1.proctorapi.comBody
The Candidate request to create a Candidate URL.
Must be a regular expression to match the in-exam page URLs (the URL of the exam), and any redirects. In cases where there are questions on multiple pages, this is important. Anything else visited that does not match this or the exam_end parameter will be considered leaving the exam and the session will be considered complete.
In case URLs don't reflect the exam state (Single-page applications), the postMessage method can be used, to communicate the exam_take state to the Proctorio extension via:
window.top.postMessage( ["exam_state_change", "exam_take"], "https://getproctorio.com" );
When using the postMessage method the "exam_take" should have a "post_message_nofication" value.
Must be a regular expression to match the exam end page (the URL the Candidate is taken to once the exam has been completed) and any possible redirect. This triggers the end of the proctoring session and considers that the exam has been submitted. Anything else visited that does not match this or the exam_take parameter will be considered leaving the exam and the proctoring session will end but the attempt won't be considered as gracefully submitted.
In case URLs don't reflect the exam state (Single-page applications), the postMessage method can be used, to communicate the exam_end state to the Proctorio extension via:
window.top.postMessage( ["exam_state_change", "exam_end"], "https://getproctorio.com" );
When using the postMessage method the "exam_end" should have a "post_message_nofication" value.
1, Maximum value is 18000.^[a-zA-Z0-9-]*$.The "domain" parameter is optional. By utilizing "domain", the exam pages as well as the Reviewer Center will load with your desired domain.
The URL will no longer point to the https://getproctorio.com page. Instead, the Candidates/Reviewers will be directed to the new route you provided in the parameter, example: https://yourdomain.com.
This allows the utilization of additional cross-origin security mechanisms, which use the SameSite cookies or X-Frame-Options: SAMEORIGIN header. It will also provide the ability to prevent data loss in session or local storage related to storage partitioning browser functionality.
The https://getproctorio.com page has the following functionalities: Check if a Candidate/Reviewer has the supported browser installed. Check if a Candidate/Reviewer has the Proctorio extension installed. To keep these functionalities, a link to https://getproctorio.com with content describing the purpose of getproctorio.com is necessary on the institution's page.
Extension Allowlist endpoint URL. Http Method: GET. The response should be a JSON stringified array. For example: '[extensionID1,extensionID2]'.
The extension_allowlist_url can be used for Candidates that have force enabled extensions in the browser by institution. These extensions can't be disabled manually by Candidate.
The 'extensionID' value should correspond to ID of the extension that will be allowed to remain active during Proctored attempt.
^[a-zA-Z0-9-]*$.^(?!goodbye$|support$|update$|setup$|invalid$).*.Represents a course ID or a section ID value. This parameter is optional. It provides a more granular sorting of the exams.
That means that exams that have the same "exam_tag" but different "section_id", will be treated like different exams.
The "section_id" parameter is dependent upon the "roster_url" parameter, and it can't be used without it.
Roster endpoint URL. Http Method: GET. The response should be a JSON stringified array. For example: '[["id1","name1"],["id2","name2"]]'
The "id" value should correspond to the "userId" parameter, be unique to the Candidate, and non-repeatable within the roster.
The roster endpoint is validated by Proctorio, so that means that if an invalid endpoint is provided or if "userId" doesn't match any "id" value inside the array, the attempts will be marked as "Unmatched" in the Review Center.
The roster_url is only fetched by the end user accessing the Review Center or the Exam Agreement page, client-side, not by Proctorio directly. That means that it can be secured with the session for that particular user. This is intentional, and as such there is no need for the PII to be passed to Proctorio at any point, whether that be a Candidate Launch request or a Reviewer Launch request.
Responses200application/jsonIndicates success and returns a Candidate URL.
400application/jsonIndicates bad request.
401application/jsonIndicates unauthorized response.
2154 - Account not active.
2155 - Incorrect region.
2655 - Invalid api_key.
Indicates success and returns a Candidate URL.
Indicates bad request.
Indicates unauthorized response.
2154 - Account not active.
2155 - Incorrect region.
2655 - Invalid api_key.
curl --request POST \
--url https://us1.proctorapi.com/v2/candidate/launch \
--header 'Content-Type: application/json' \
--header 'api_key: $API_KEY' \
--data '{"launch_url":"https://example.com/exam","exam_start":"https://example.com/exam","exam_take":"https://example.com/exam","exam_end":"https://example.com/exam","exam_settings":{"record_video":true,"record_audio":false,"record_screen":false,"verify_video":false},"user_id":"example-id-123"}'import requests
url = "https://us1.proctorapi.com/v2/candidate/launch"
payload = {
"launch_url": "https://example.com/exam",
"exam_start": "https://example.com/exam",
"exam_take": "https://example.com/exam",
"exam_end": "https://example.com/exam",
"exam_settings": {
"record_video": True,
"record_audio": False,
"record_screen": False,
"verify_video": False
},
"user_id": "example-id-123"
}
headers = {
"api_key": "$API_KEY",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const fetch = require('node-fetch');
const url = 'https://us1.proctorapi.com/v2/candidate/launch';
const options = {
method: 'POST',
headers: {api_key: '$API_KEY', 'Content-Type': 'application/json'},
body: '{"launch_url":"https://example.com/exam","exam_start":"https://example.com/exam","exam_take":"https://example.com/exam","exam_end":"https://example.com/exam","exam_settings":{"record_video":true,"record_audio":false,"record_screen":false,"verify_video":false},"user_id":"example-id-123"}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://us1.proctorapi.com/v2/candidate/launch"),
Headers =
{
{ "api_key", "$API_KEY" },
},
Content = new StringContent("{\"launch_url\":\"https://example.com/exam\",\"exam_start\":\"https://example.com/exam\",\"exam_take\":\"https://example.com/exam\",\"exam_end\":\"https://example.com/exam\",\"exam_settings\":{\"record_video\":true,\"record_audio\":false,\"record_screen\":false,\"verify_video\":false},\"user_id\":\"example-id-123\"}")
{
Headers =
{
ContentType = new MediaTypeHeaderValue("application/json")
}
}
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}{
"launch_url": "https://example.com/exam",
"exam_start": "https://example.com/exam",
"exam_take": "https://example.com/exam",
"exam_end": "https://example.com/exam",
"exam_settings": {
"record_video": true,
"record_audio": false,
"record_screen": false,
"verify_video": false
},
"user_id": "example-id-123"
}