Introduction
This document is to be used as a reference guide to implementing each of the APIs of ExamBuilder. Each request (see vocabulary below) has its own heading within this document. All requests have been categorized into sections based on commonality.
Formatting
Within this document, to avoid confusion between concept and abstract, as well as between concept and specific data necessary for successful operation of this API, various styles will be applied to text.
Bold: Bold font without italics is reserved for headings and controlled vocabulary definitions.
Bold,+,Italics: Bold font with italics is reserved for definitions of specific vocabulary.
Consolas:
The consolas font is used to represent code or code parameters.
CONSOLAS ALL CAPS:
The consolas font with all caps to represent error codes.
Highlighted Consolas with White Space:
This set of formatting is used to represent code within text that is controlled, but is being displayed with white space and potentially capital letters for visibility reasons within the text. Refer to code formatting for actual code examples. This format is also used when particular members are represented in slightly different ways in code.
all lower case:
Systems using this API do not use case-sensitivity within URLs, therefore all URLs and their possible parameters will use all lower case.
multipleWordsAllButFirstCapitalized:
JSON
Vocabulary
The following terms are used throughout the document and are necessary to understanding how the API works.
Controlled Vocabulary Parameters: A parameter which must take on a specific value corresponding to one of the values the request can understand.
cURL: A command-line tool for transferring data which is easily mappable to other common REST APIs.
Error Code: A specific string used to represent a specific behavior. An error code is returned from a request.
Identifier: A parameter which must take on a specific value corresponding to a specific value in a database which uniquely identifies an object.
Member: A name/value pair in JSON. Members may be called out by name in this document, but it is implicit that the value is also included.
Parameter: The equivalent of an argument in other programming languages, a parameter is additional data supplied to a request. This parameter may be part of the URL or JSON. Parameters in this document are typically search parameters, identifiers, or controlled vocabulary parameters.
Permission: The ability to be able to access or change specific requests, data, or users within a system. These are specifically named for the areas of data to which they allow access.
Request: The equivalent of a function in other programming languages, this API uses a REST style. Communications in any RESTful implementation are done through requests.
Search Parameters: A parameter which can take on any value and is used to complete the request with the supplied value. When passing in search parameters, ExamBuilder will do a case insensitive search and match any occurrence at the beginning, middle or end of the corresponding string.
Super User: A permission level granted by the system which allows all actions necessary to do anything outlined in this document.
URL Encoded: Special formatting done to represent dates, times, and other types of data reliant on symbols. Examples can be found at: http://www.w3schools.com/tags/ref_urlencode.asp.
Request Information
Each request has a variety of implementation details, all summarized below.
Summary Text: This text describes how the request is used in practice and any expectations one can have using it.
Returns: This text describes any relevant data that is returned as a result of the request in addition to the minimal set of members shown in the Example Response details.
Required Permissions: Lists specific permissions necessary on the system to be able to use the request. A Super User has all of these permissions by default and has read permissions on all students and exams. An instructor or developer may or may not be a Super User.
Usage: Provides, in code, the way to perform the request. All parameters are listed in this code, although parameter usage will vary by request. Parameters are explained within a table in this area, detailing how the parameter influences the request, any restricted vocabulary (shown in bold) and if using the parameter is required or optional. This table will also denote if a parameter is to be used in JSON form. Every API request requires an API Key
and API Secret
(passed in the header over SSL using basic authentication). This is represented in the examples below following the -u in cURL.
A note on URL and JSON construction: Each request has a URL portion. URLs are constructed literally unless there are curly brackets ({ }), which denote a value must be placed instead, or an ID unique to the system. The IDs are easy to identify as they are strings of hexadecimal characters. Curly brackets that are not arguments (i.e. are before the .json operator) are expected to take on the value of the corresponding ID within them. Parameters, also within curly brackets, occur after question marks and are denoted as follows: search parameters are represented with {searchparam}, identifiers are represented with {identifier} and controlled vocabulary parameters are represented with {vocab}. See the definitions of these types for further explanation. Dates and times have a special representation which are URL Encoded and are represented by {encodeddate}. JSON objects are created as parameters for some requests, and will use the same representation for parameters within the objects. JSON objects can create values with their parameters, and this document uses {value} to identify those opportunities.
cURL Example Request(s): Provides, in code, an actual command line example (or examples) calling the API request. Each example will be enumerated and the title will describe what the example is doing. Some requests in this documentation take a JSON object as a parameter. These requests require that "Content-Type: application/json" be added to the header (all requests with this requirement have it built into the example). Only add "Content-Type: application/json" for requests that use a JSON object as a parameter.
Example Response(s): Provides, in code, an actual example of a response from a successful API request. Each example will be enumerated and the title will describe what the example is doing. The response is always in the form of JSON and will always contain the following members:
Member Name | Description |
---|---|
message | A human-readable message corresponding to the request |
returnCode | If successful this value will be S, otherwise it will be the error code |
status | true or false based on the success of the call |
Most responses contain result sets from the database or members. Result sets are returned as an array of JSON objects, as shown by square brackets [ ]. If the request COULD have multiple JSON objects in a result set, it will STILL have the square brackets. If the request CAN ONLY have one JSON object or is just additional members, square brackets are NOT used.
GUI Accessibility: Tells whether the GUI can be used for this request and if so, instructions are provided.
Errors: Provides a table of all error codes and descriptions which could be encountered in using the request.
Enabler Requests
This document is to be used as a reference guide to implementing each of the APIs of ExamBuilder. Each request (see vocabulary below) has its own heading within this document. All requests have been categorized into sections based on commonality.
Get Instructor ID
When making an API request, an identity of an instructor is asserted. Each organization can have one or more instructor accounts. Permissions will vary across instructors.
Note: For API developers new to ExamBuilder, this request,can be used to confirm that an API Key
and API Secret
combination is valid. If the request comes back without an error, the combination is valid.
Returns
The instructor ID
based on successful authentication.
Required Permissions
No special permissions required.
Usage
GET | https://instructor.exambuilder.com/v2/validate.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/validate.json\ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED |
The API Key The API Secret combination was invalid
|
Get SSO Link
This request creates a single sign-on link that allows a specific student to bypass the Student Testing Site login page and go directly to his/her Current Exams Page. On that page he/she can select an exam that was scheduled prior to log in.
Returns
A URL that can be used by a specific student for single sign-on.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/sso.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/25fdf796c0a6bcd/student/855cea216bd/sso.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes.
Errors
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_STUDENT | The user ID was invalid or this account does not have permission to this resource |
Get SSO Exam Link
This request creates a single sign-on link so that a specific student can launch a specific exam. The link allows a student to bypass the Testing Site login page and bypass the Current Exams page.
Returns
A URL that can be used by a specific student to launch a specific exam.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructor_id}/userexam/{user_exam_id}/sso.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/25fdf796c0a6bcd/userexam/519335a0e61cf/sso.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_STUDENT_EXAM | The user exam ID entered was invalid |
Exam Requests
The following requests enable functionality on exams. This includes listing exams and their properties.
List Exams
The List Exams request allows the search and retrieval of one or more exams. The exam IDs
returned may be used for scheduling exams and running reports. To search for an exam by name, pass in an exam name
as a URL parameter.
Returns
A list of one or more exam records, each identified by an exam ID
.
Required Permissions
Exam Authoring | Create and edit exams |
---|---|
Exam Authoring | Activate, archive and delete exams |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/exam/list.json?examname={searchparam}&examstate={vocab} |
Input Parameters | Description | Required |
---|---|---|
examname | Name (or partial name) of exam to search for. If omitted returns all exams. | No |
examstate | Filters results based on the status of the exam as follows: active = active exams only notactive = exams that are not active archived = exams that have been archived all = all exams (default) |
No |
cURL Example Request
Example 1: List All Exams
curl |
https://instructor.exambuilder.com/v2/instructor/3b7e9c038a24c4ba8c4/exam/list.json?examstate=all \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example 2: Search for an Exam by Name
curl |
https://instructor.exambuilder.com/v2/instructor/37e9c038a24c4a8c4/exam/list.json?examname=sales \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example 3: Search for an Exam by Active State
curl |
https://instructor.exambuilder.com/v2/instructor/37e9c038a24c4a8c4/exam/list.json?examstate=active \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. As a logged in instructor with applicable permissions click on Exam Editor and add .json to the end of the URL.
For example: https://instructor.exambuilder.com/v2/instructor/3b7e9x038a47d4dc4by8c4c149c3/exam/list.json
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
Get Exam
This request lists the properties of a previously created exam.
Returns
An exam record identified by its exam ID
.
Required Permissions
Exam Authoring | Create and edit exams |
---|---|
Exam Authoring | Activate, archive and delete exams |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/sso.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/3b4ba8c4c14/exam/861cf983afcf9.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Although there is no corresponding GUI screen at this time, JSON can be retrieved via Web browser. As a logged in instructor with applicable permissions plug in Instructor ID
and exam ID
and go to https://instructor.exambuilder.com/v2/instructor/{instructorid}/exam/{examid}.json
Errors
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
Student Requests
The following requests enable functionality on students and student records. This includes listing, creating, deleting, and updating students, their properties, and groups to which they belong.
Note: There are fields called student ID
and User ID
. The training department sets the student ID
field when the student account is created and it is optionally used to look up a student record. The User ID
field is generated by ExamBuilder as a database primary key and is required for scheduling and reporting.
Note: Some requests return an API Key
and API Secret
as part of the student record. This is only used by organizations that have incorporated ExamBuilder’s Embedded Exam feature. An Embedded Exam is displayed inline within a third party application. In this scenario, a student can be logged in programmatically using his/her API Key
and API secret.
List Students
The List Exams request allows for the search and retrieval of one or more students. To search for a student, pass in first name or last name or student ID
as URL parameters as described below. A combination of these parameters can be used to further filter results, but only first name and last name. If student id is provided, first name and last name parameters will be omitted. Providing no parameters returns all students. The returned is used for scheduling exams and running reports.
You can also sort the results by last name, first name or date created, in either ascending or descending order
Returns
A list of one or more student records, each identified by a User ID
.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Managing Students | Delete students |
Scheduling Students | Schedule students and add more time to student exam attempt |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/list.json?firstname={searchparam}?lastname={searchparam}?studentid={searchparam} |
Input Parameters | Description | Required |
---|---|---|
firstname | The student's first name | No |
lastname | The student's last name | No |
studentid | The User ID assigned to the student by the training department | No |
sort | An optional parameter to order the results. There are 3 possible values: firstname = to sort by first names lastname = to sort by last names datetimecreated = to sort by creation date | No |
sortdirection | An optional parameter to further sort the results in either ascending or descending order. If this parameter is not passed, the default value is ascending There are 2 possible values: asc = to sort in ascending order desc = to sort in descending order | No |
cURL Example Request
Example 1: List All Students (newest students first)
curl |
https://instructor.exambuilder.com/v2/instructor/ff5c883afcf927ab42/student/list.json?sort=datetimecreated&sortdirection=desc \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example 2: Search for a Student
curl |
https://instructor.exambuilder.com/v2/instructor/ff5c883afcf927ab42/student/list.json?lastname=richards \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. As a logged in instructor with applicable permissions click on Student Manager > Students and add .json to the end of the URL.
For example: https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/list.json
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
Get Student
This request gets the details of a previously created student.
Returns
A student record identified by its User ID
. The set of groups that the student belongs to is also returned.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Managing Students | Delete students |
Scheduling Students | Schedule students and add more time to student exam attempt |
Scheduling Students | Reset or delete student exam attempt |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{studentid}.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/d1e2f3.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Although there is no corresponding GUI screen at this time, JSON can be retrieved via Web browser. As a logged in instructor with applicable permissions substitute personal Instructor ID
and exam ID
and go to https://instructor.exambuilder.com/v2/instructor/{instructorid}/exam/{examid}.json
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_STUDENT | The User ID was invalid or did not belong to this company account |
Create Student
This request adds a student account and generates a unique system-wide User ID
for the new student. It has both required and optional parameters that must be passed in as a JSON object as shown below.
Returns
The User ID
of the student.
Required Permissions
Managing Students | Create and group students |
---|
Usage
POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student.json |
Input Parameters | Description | Required |
---|---|---|
firstName | The student's first name. This is passed in via JSON. | Yes |
lastName | The student's last name. This is passed in via JSON. | Yes |
studentId | A system-wide unique identifier for the student. The student uses student ID to log in to the Web portal. student ID can be used to look up a student record and retrieve the User ID generated by ExamBuilder. The User ID is required for scheduling and reporting. This is passed in via JSON. | Yes |
password | The password the student will use to log in to the Web portal. This is passed in via JSON. | Yes |
employee_number | An optional field (String) that can be used for internal purposes. This is passed in via JSON. | No |
group_ids | An optional list of group ID s that can be used to assign the new student to demographic groups. This is passed in via JSON. | No |
cURL Example Request
Example 1: Create a Student without Groups
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X POST \ -d '{"firstName":"$firstname1","lastName":"$lastname1","studentId":"$studentid1","password":"xxx-xxxx"}' |
Example 2: Create a Student with Groups
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -d '{"firstName":"$firstname4","lastName":"$lastname4", "studentId":$studentid4", \ "password":"xxxxxxx", "group_ids" : ["6cf00cb5aed89361001", "61b4f925933d9ad1028"] }' |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
OUT_OF_STUDENT_LICENSES | All available licenses used. Additional licenses must be purchased by a Super User to add more students. |
FIRST_NAME_REQUIRED | The first name parameter was missing or null |
LAST_NAME_REQUIRED | The last name parameter was missing or null |
STUDENTID_REQUIRED | The student ID parameter was missing or null |
PASSWORD_REQUIRED | The password parameter was missing or null |
STUDENTID_EXISTS | The student ID entered already exists in ExamBuilder. |
Update Student
This request updates an existing student record. This request has all optional parameters that are passed in as a JSON object as shown in the Example Requests area below.
Returns
The student record after the update has occurred.
Required Permissions
Managing Students | Edit and group students |
---|
Usage
PUT or POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{studentid}.json |
Input Parameters | Description | Required |
---|---|---|
firstName | The student's first name. This is passed in via JSON. | No |
lastName | The student's last name. This is passed in via JSON. | No |
studentId | A system-wide unique identifier for the student created by the training department. The student uses student ID to log in to the Web portal. student ID can be used to look up a student record and retrieve the User ID generated by ExamBuilder. The User ID is used for scheduling and reporting. This is passed in via JSON. | No |
password | The password the student will use to log in to the Web portal. This is passed in via JSON. | No |
employee_number | An optional field (string) that can be used for internal purposes. This is passed in via JSON. | No |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/DC4BA8C4C1/student/6d631cd74.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X POST \ -d '{"firstName":"Henrietta","lastName":"Marx ","studentId":"stha@eb.com","password":"xxxxxxx"}' |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
OUT_OF_STUDENT_LICENSES | All available licenses used. Additional licenses must be purchased by a Super User to add more students. |
FIRST_NAME_REQUIRED | The first name parameter was missing or null |
LAST_NAME_REQUIRED | The last name parameter was missing or null |
STUDENTID_REQUIRED | The student ID parameter was missing or null |
PASSWORD_REQUIRED | The password parameter was missing or null |
STUDENTID_EXISTS | The student ID entered already exists in ExamBuilder. |
Delete Student
This request permanently deletes a student record and the student's entire exam history. There is no “undo” for this action.
Returns
The name of the deleted student.
Required Permissions
Managing Students | Delete students |
---|
Usage
DELETE | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{studentid}/initials/{initials}.json |
The URI is appended with /initials/ {initials}. ExamBuilder stores the initials of the person who deleted a student record. If an automated procedure calls this, the initials api should be passed so that it can be easily determined that an API call deleted the account during the procedure. Otherwise, the instructor’s initials of the account performing the deletion should be used. The value entered for {initials} must be 2 or 3 characters (case insensitive). |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/xyx34/initials/api.json \ -X DELETE \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INITIALS_REQUIRED | The initials portion of the URI was missing or invalid. |
STUDENT_NOT_FOUND | The student account was not found. Confirm that the User ID is valid and the student exists |
INVALID_STUDENT | Insufficient permission to delete this student. |
Get Student's Groups
This request provides a list of all groups to which a specific student belongs.
Returns
A list of groups this student belongs to, each one identified by its group ID
.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/group.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/7ff7b1cfa/student/8e87470/group.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Pasting the example request URL in a browser for a logged in instructor will return the same JSON as an API call.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
STUDENT_NOT_FOUND | The student account was not found. Confirm that the User ID is valid and the student exists |
INVALID_STUDENT | Insufficient permission to delete this student. |
Get Student's Exams
This request provides a list of completed exams, and a list of exams in progress, for a specific student.
Both lists identify a record by the user exam id
which maps a user id
and an
exam id
and an exam attempt
.
The user exam id
can be used for Scheduling Requests such as
Unschedule Exam (Delete Exam Attempt),
Reset Exam in Progress, and
Add Time to an Exam Attempt.
The showallattempts
parameter by default returns only the last completed exam attempt
. To return all exam attempts pass in a value of 1.
Returns
A list of completed exams, and a list of exams in progress for a specific student, with each record identified by a user exam id
Required Permissions
Managing Students | View student scores and basic reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/exams.json |
Input Parameters | Description | Required |
---|---|---|
showallattempts | 0 = show last attempt 1 = Show all attempts | No |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/7ff7b1cfa/student/8e87470/exams.json?showallattempts=1 \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Pasting the example request URL in a browser for a logged in instructor will return the same JSON as an API call.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
STUDENT_NOT_FOUND | The student account was not found. Confirm that the User ID is valid and the student exists |
INVALID_STUDENT | Insufficient permission to delete this student. |
Get Student's Exam Statistics
This function returns a full report on a specific student's exam attempt. The report includes the student's response for each question, their performance in each question pool if the exam uses them, and aggregate exam stats. While this data is perhaps better suited for the web interface, the question pool section can be useful for providing exam feedback.
Returns
A full report for a student's exam attempt including a list of exam questions with correct/incorrect values, and a list of question pool performance, and aggregate exam statistics
Required Permissions
Managing Students | View student scores and basic reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/userexam/{userexamid}/stats.json |
Input Parameters | Description | Required |
---|---|---|
None |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/7ff7b1cfa/student/8e87470/userexam/1e634260d2/stats.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Pasting the example request URL in a browser for a logged in instructor will return the same JSON as an API call.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
STUDENT_NOT_FOUND | The student account was not found. Confirm that the User ID is valid and the student exists |
INVALID_STUDENT | Insufficient permission to delete this student. |
INVALID_USEREXAMID | The user exam ID was invalid |
Group Requests
ExamBuilder allows the grouping of students. Each Group Category is defined by a group category ID which is used to list all the groups within a Category. For example, A Group Category named "Country" might have the following groups: England, Australia, Canada, and Germany as shown in the table below.
Note: Students can only be in one group per group category. There is an exception for the built-in category named “Classes”.
List Group Categories
This request lists all the Group Categories in an instructor’s account - up to the system maximum of 10.
Group Category Name = Country Group Category ID = 1d0ee33bfb768cb2 |
Group Category Name = Department Group Category ID = 1d0ee33bfb768cb2 |
||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Note: Group Category Name is a synonym for Group Type Name and group category ID is a synonym for Group Type ID. Those other terms may appear in legacy error messages and other result sets.
Returns
Group Categories and their corresponding group category IDs.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/category/list.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/cfdb65b35c916dcb9569fc4/category/list.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Click on Student Manager > Groups. Append .json to the URL.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
Get Group Category
This request lists details about a Group Category.
Returns
A Group Category record identified by its group category ID.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/category/{categoryid}.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/category/5e343e.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Click on Student Manager > Groups. Under a Group Category select Manage Groups. Replace "/manage" from the end of the URL with ".json"
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
List Groups
This request lists all groups within a specific Group Category.
Returns
A list of group records, each one identified by its group ID
.
Required Permissions
Managing Students | Create and group students |
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/category/{categoryid}/manage.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/{instructorid}/category/{categoryid}/manage.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Go to Student Manager > Groups. Click on Manage Groups. Append .json to the URL
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_CATEGORY_ID | The category ID was invalid |
Get Groups
Gets the group name, group category ID and date time created for a group by passing in the group ID
. This request can be used to confirm a group ID
is valid and to map a group to it’s parent group category.
Returns
A group record identified by its group ID
.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/group/6572e66975fde0ca.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Go to Student Manager > Groups. Click on Manage Groups. Click on Select a Group. Append .json to the URL
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
List Group Members
This request lists all the students in a specific group.
Returns
A list of students in a specific Group, each identified by a User ID
.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}/members.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/4216bde17e6fc4d4/group/730fca3c398ea872/members.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. Go to Student Manager > Groups. Click on Manage Groups. Append .json to the URL
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
List Unassigned (Ungrouped) Students
This request lists all students who have not been assigned to a Group within a specific Group Category.
Returns
A list of students, each identified by a User ID
.
Required Permissions
Managing Students | Edit and group students |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/category/{categoryid}/uncategorized.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/category/008156/uncategorized.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_CATEGORY_ID | The category ID was invalid |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
Create Group Member
This request adds a student, identified by User ID
, to a Group within a Group Category.
Note: If the student is already in a Group this function will update the record with the new Group.
Returns
Only minimal members are returned.
Required Permissions
Managing Students | Create and group students |
---|---|
Managing Students | Edit and group students |
Usage
POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}/members/add.json |
Input Parameters | Description | Required |
---|---|---|
userId | The User ID of the student to be added to the Group. | Yes |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/3b12e4a710cdf88/group/8c1e6342441e86/members/add.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X POST \ -d {"userId":"29f71c9a76f0a9eec1aed8c"} |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_STUDENT | The User ID was invalid or insufficient permissions to access |
Delete Group Member
This request removes a student from a Group. It does not delete any of the student information or history.
Returns
Only minimal members are returned.
Required Permissions
Managing Students | Edit and group students |
---|
Usage
DELETE | https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}/members/delete.json |
Input Parameters | Description | Required |
---|---|---|
userId | The User ID of the student to be removed from the Group. | Yes |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}/members/delete.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ X DELETE \ -d {"userId":"29f71c9a76f0a9eec1aed8c"} |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
GROUP_MEMBER_DOES_NOT_EXIST | The student does not exist in this Group |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_STUDENT | The Student does not exist or this account does not have permission to access this resource |
Scheduling Requests
Requests in this section are for various scheduling and unscheduling processes. When a student is scheduled to take an exam, the system creates a database record that is identified by a user exam ID
- a combination of User ID
and exam ID
and exam attempt. To make future changes to a scheduled exam such as adding time, deleting an attempt or resetting an exam in progress, the "user exam ID
" must be used in the request.
Note: "Schedule" does not refer to a date and time; it only makes the exam available to a student.
List Scheduled Exams
This request has many functions, including:
- Listing student records for a specific exam (all the students who took an exam or are scheduled to take it)
- Listing exam records for a specific student (all the exams one student took or is scheduled to take)
- Finding a specific exam that a specific student took or is scheduled to take
Returns
A list of exam records that include scheduled exams, exams in progress and completed exams whereby each record is identified by its user exam ID
, an identifier created as a specific student paired with a specific exam.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|---|
Scheduling Students | Reset or delete student exam attempt |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?examId={identifier} |
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?userId={identifier} |
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?examid={identifier}&userId={identifier} |
Input Parameters | Description | Required |
---|---|---|
userid | The identifier of a unique student. | No* |
examid | The identifier of a unique exam. | No* |
cURL Example Request
Example 1: Get Student Records for a Specific Exam
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/scheduled.json?examid= 8880e61c \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example 2: Get Exam Records for a Specific Student
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/scheduled.json?userid=cf927ab42 \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example 3: Get a Specific Exam Record for a Specific Student
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/scheduled.json?userId=cf927ab42&examid=8880e61c \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
USERID_OR_EXAMID_REQUIRED | This request requires at least 1 parameter; either User ID or exam ID . Passing both parameters is allowed |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_STUDENT | This Student does not exist or this account does not have permission to access this resource |
Schedule Exam
This request schedules a student to take a specific exam.
Returns
An exam record, including the scheduling information. The details are in a member named last_exam_attempt and includes the user exam ID
(required to add time, delete an attempt or reset an exam in progress), the User ID
, exam ID
and student ID
.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|
Usage
POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/exam/{examid}/schedule.json |
Input Parameters | Description | Required |
---|---|---|
userId | The identifier of a unique student. This is passed in via JSON. | Yes |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/8c1e6342441e86/student/exam/3b12e4a710cd88/schedule.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -d '{"userId":"4216bde17e6f"} \ -X POST \ -H "content-type:application/json" |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
STUDENT_ALREADY_SCHEDULED | This student is already scheduled to take this exam. Cannot schedule an exam in progress. Delete the exam attempt and reschedule or reset an exam in progress |
Unschedule Exam (Delete Exam Attempt)
This request deletes an exam attempt for a specific student. The exam attempt can be:
- An exam that has not been started yet
- An exam that has been started but not completed
- A completed exam
For exams in progress, this request removes the exam from a student’s list of current exams.
This request requires the "user exam ID
" which is a combination of User ID
and exam ID
and exam attempt
. The "user exam ID
" can be obtained by using the List Scheduled Exams request.
Returns
A member called all_exam_attempts that contains a list of all remaining exam attempts for this student (or an empty list if the request deleted the only attempt for this student) and a member called last_exam_attempt
that contains detailed info on the most recent exam attempt for this student (or an empty list if the request deleted the only attempt for this student).Required Permissions
Scheduling Students | Reset or delete student exam attempt |
---|
Usage
DELETE | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/userexam/{userexamid}/unschedule.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/3b12e4adf8c/student/userexam/1e634260d2/unschedule.json \ -X DELETE \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_USEREXAMID | The user exam ID was invalid |
DELETE_EXAM_ATTEMPT_FAILED | The exam attempt could not be deleted because of a database error |
Get Exam Attempt
This request returns the details of a specific exam attempt. It requires the user exam ID
which is a combination of User ID
and exam ID
and exam attempt
. The user exam ID
can be obtained by using the List Scheduled Exams request.
Returns
A record for a specific student’s specific exam that includes the student’s name and ID, exam attempt, start date, completion date and score.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|---|
Scheduling Students | Reset or delete student exam attempt |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/userexam/{userexamid}/attempt.json |
cURL Example Request
Example 1: List All Exams
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/student/userexam/cd474dc/attempt.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_USER_EXAM | The "user exam ID " is invalid |
Reset Exam Progress
This request deletes an exam in progress and reschedules the exam; in effect, all data for the exam in progress is deleted and the student is rescheduled. Since the old database record is deleted and a new one is added, the user exam ID
will change as a result of this call. Making this request requires the user exam ID
which is a combination of User ID
and exam ID
and exam attempt
. The user exam ID
can be obtained by using the List Scheduled Exams request.
Returns
The members of the scheduled exam including the student’s name, student’s name, and exam attempt.
Required Permissions
Scheduling Students | Reset or delete student exam attempt |
---|
Usage
PUT | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/userexam/{userexamid}/reset.json |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/3b12e4a7cdf88c/student/userexam/1e63424460d2/reset.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes. If logged in to the GUI this request can receive a JSON response but realize that the user exam ID
changes after the call so reloading the page it will return an error.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_USER_EXAM | The user exam ID was invalid |
STUDENT_NOT_SCHEDULED | The exam could not be reset because this student is not scheduled for this exam |
RESET_FAILED_EXAM_COMPLETED | The exam could not be reset because this student completed the exam. Only exams in progress can be reset |
Add Time to an Exam Attempt
If an exam is timed, this request adds time to a student’s exam attempt so that he/she has more time to complete the exam, or can continue an exam that has timed out. The amount of time must be passed in as a JSON object using the format in the example below in the areas denoted {value}.
Making this request requires the "user exam ID
" which is a combination of User ID
and exam ID
and exam attempt
. The "user exam ID
" can be obtained by using the List Scheduled Exams request.
Returns
Only minimal members are returned.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|
Usage
POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/userexam/{userexamid}/time/add.json |
Input Parameters | Description | Required |
---|---|---|
days | An integer representing the number of days to add. This must be an integer greater than or equal to zero. This value is passed in via JSON. | Yes |
hours | An integer representing the number of hours to add. This must be an integer greater than or equal to zero. This value is passed in via JSON. | Yes |
minutes | An integer representing the number of minutes to add. This must be an integer greater than or equal to zero. This value is passed in via JSON. | Yes |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/7ff7b57e1/student/userexam/3919ae25fdf7/time/add.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -X POST \ -d '{"days":"2","hours":"0","minutes":"0"}' \ -H "content-type:application/json" |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
STUDENT_NOT_SCHEDULED | This student is not scheduled to take this exam |
EXAM_IS_NOT_TIMED | This exam is not timed. Time can only be added to a timed exam. |
NOT_THE_LATEST_EXAM_ATTEMPT | The user exam ID is not for the latest exam attempt. Time can only be added to the most recent exam attempt. Note: This error is most often related to the condition where a user exam ID references a completed exam. |
Bulk Schedule
This request batch schedules students to take a specific exam. Scheduling can be limited to only those in an ExamBuilder defined Group or open or to all students. This scope can be further restricted to who haven’t ever taken or haven’t passed the exam if desired. To schedule by group, the students must be assigned to groups before issuing this request. Grouping a student after issuing this request will not schedule the student to take the exam.
Returns
The number of students scheduled.
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|
Usage
POST | https://instructor.exambuilder.com/v2/instructor/{instructorid}/exam/{examid}/bulkschedule.json |
Input Parameters | Description | Required |
---|---|---|
groupId | To schedule a specific group of students, use the group ID of the Group. To schedule all students, use the value of zero, but do not use quotes. | Yes |
target | An optional parameter to further target the students who are bulk scheduled. There are 2 possible values: not_scheduled = to target students who are not scheduled for and never took this exam (default value) failed = to only target students who failed their last attempt | No |
cURL Example Request
Example 1: Bulk Schedule Single Group, Unscheduled Students
curl |
https://instructor.exambuilder.com/v2/instructor/cde2e519335a0/exam/fe4f3ddf796/bulkschedule.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X POST \ -d '{"groupid" : "61B4F925933D9AD1", "target" : "not_scheduled"}' |
Example 2: Bulk Schedule All Unscheduled Students
curl |
https://instructor.exambuilder.com/v2/instructor/cde2e519335a0/exam/fe4f3ddf796/bulkschedule.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X POST \ -d '{ "groupid" : 0, "target" : "not_scheduled"}' |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
Bulk Unschedule
This request batch unschedules (removes) students from a specific exam. This only affects exams that were not started, or were started but not completed. The request can be limited to only those in an ExamBuilder defined Group or can unschedule all students the instructor has access to. To unschedule by group, the students must be assigned to groups before issuing this request. Grouping a student after issuing this request will not unschedule the student.
Returns
The number of students unscheduled.
Required Permissions
Scheduling Students | Reset or delete student exam attempt |
---|
Usage
DELETE | https://instructor.exambuilder.com/v2/instructor/{instructorid}/exam/{examid}/bulkunschedule.json |
Input Parameters | Description | Required |
---|---|---|
groupId | To unschedule a specific group of students, use the group ID of the Group. To unschedule all students, use the value of 0, but do not use quotes (i.e. it is not a String). |
Yes |
cURL Example Request
Example 1: Bulk Unschedule Single Group of Students
curl |
https://instructor.exambuilder.com/v2/instructor/2e519335a0/exam/f6829335a585/bulkunschedule.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X DELETE \ -d '{"groupId" : "61B4F925933D9AD1"}' |
Example 2: Bulk Unschedule All Students
curl |
https://instructor.exambuilder.com/v2/instructor/2e519335a0/exam/f6829335a585/bulkunschedule.json \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "content-type:application/json" \ -X DELETE \ -d '{ "groupid" : 0 }' |
Example Response
GUI Accessibility
No.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
Report Requests
Requests in this section are for specialized ExamBuilder reports.
Get an Exam Enrollment Report
This request returns a list of students that can be scheduled for an exam (with exam ID
).
Returns
A list of students who can be scheduled for an exam
Required Permissions
Scheduling Students | Schedule students and add more time to student exam attempt |
---|---|
Scheduling Students | Reset or delete student exam attempt |
Report Generation | Generate Quick Reports |
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/scheduler/exam/{examid}/schedule/search?filter={identifier}&groupid={identifier} |
Input Parameters | Description | Required |
---|---|---|
status | This parameter takes one of 3 possible values: never = not scheduled for and never took this exam (default) failed = failed their last attempt scheduled = scheduled for and did not yet complete this exam | No |
groupid | The group ID of the Group | No |
cURL Example Request
Example 1: Default values. Show all students who, are not scheduled for and never took this exam, and do not filter by group
curl | GET https://instructor.exambuilder.com/v2/instructor/98e863a8a261dc5e343edaa3c20d5cb3/scheduler/exam/67bc766c61bb7bec19b933e720dee513/search.json -u 3004037C6019A687:669B9CC922BEA7855EBECC82 -X |
Example 2: Show all students who, are scheduled for but did not yet complete this exam, and do not filter by group
curl |
-X GET https://instructor.exambuilder.com/v2/instructor/98e863a8a261dc5e343edaa3c20d5cb3/scheduler/exam/67bc766c61bb7bec19b933e720dee513/search.json?status=scheduled \ -u 3004037C6019A687:669B9CC922BEA7855EBECC82 –X |
Example 3: Show all students in a specific group who are not scheduled for and never took this exam
curl |
-X GET https://instructor.exambuilder.com/v2/instructor/98e863a8a261dc5e343edaa3c20d5cb3/scheduler/exam/67bc766c61bb7bec19b933e720dee513/search.json?groupid=494D954400 \ -u 3004037C6019A687:669B9CC922BEA7855EBECC82 -X |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
INVALID_ID | An ID other then the Instructor ID was invalid |
Get a Snapshot Report
This request provides results on which students completed a specific exam, also known as a Snapshot Report. A Snapshot Report can be filtered by group, pass/fail status, and date.
Returns
A list of exam results with filtering parameters applied.
Required Permissions
Report Generation | Generate Quick Reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/report/exam/{examid}/snapshot.json?passorfail={vocab}&groupid={identifier}&timeperiod={vocab}&date1={encodeddate}&date2={encodeddate} |
Input Parameters | Description | Required |
---|---|---|
passorfail | This parameter takes one of 3 possible values: PASS = passing scores only FAIL = failing scores only COMPLETED = both passing and failing scores | No |
groupid | The group ID of the Group | No |
timeperiod | Limit results to a specific time period. Possible parameter values are: today = current date weektodate = So far, this week monthtodate = 1st of the current month until current date yeartodate = 1st of the current year until current date 7daysago = Prior 7 days, from today 14daysago = Prior 14 days, from today 30daysago = Prior 30 days, from today earliesttodate = Earliest date on system to date dateRange = Enter a specific date range (use date1 and date2 parameters) | No |
date1 | The first date of the range. Use the USA format of MM/DD/YYYY, URL Encoded. For example, 07/14/2014 | No* |
date2 | The last date of the range. The format is the USA version of MM/DD/YYYY, URL Encoded. For example, 08/30/2014 | No* |
cURL Example Request
Example 1: All Students Passing a Specific Exam and Belonging to a Specific Group
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/exam/f5c883/snapshot.json?passorfail=PASS&groupid=494D954400 \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ |
Example 2: All Students Completing a Specific Exam and Belonging to a Specific Group between Jan 1, 2014 and March 31, 2014.
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/exam/f5c883/snapshot.json&timeperiod=daterange&date1=01%2F01%2F2014&date2=03%2F31%2F2014 \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_DATE | The date entered was missing or in an invalid format. The correct format is MM/DD/YYYY and should be URL Encoded if passed in the URL |
INVALID_REQUEST_ERROR | The timeperiod parameter was set to daterange but there was no parameter entered for date1 or date2 |
Get a Question Ranking Report
This request returns a Question Ranking Report, which lists all of the questions in an exam (with exam ID
), the percent correct, percent incorrect and item discrimination.
Returns
A list of questions and the aggregate statistics for each.
Required Permissions
Super User ONLY | None |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/report/exam/{examid}/questionrank.json?examattempt={vocab}&group1={identifier} |
Input Parameters | Description | Required |
---|---|---|
examattempt | The attempt of the exam. Possible values are: all = All Attempts first = 1st Attempt Only second = 2nd Attempt Only last = Last Attempt (default) | No |
group1 | The group ID of the Group. | No |
cURL Example Request
Example 1: List All Exams
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/exam/88cfe393f927ab42/questionrank.json?examattempt=FIRST / -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
NO_EXAMS_COMPLETED | The report could not be run because no student completed this exam |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
Get a Group Analysis Report
This request provides a detailed list of your student groups for a specific exam, also known as a Group Analysis Report. A Group Analysis Report can be filtered by Attempts.
Returns
A list of groups results with filtering parameters applied.
Required Permissions
Report Generation | Generate Quick Reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/report/exam/{examid}/grouptype/{grouptype}/groupanalysis.json?examattempt=all |
Input Parameters | Description | Required |
---|---|---|
examatteempt | The attempt of the exam. Possible values are: all = All Attempts first = 1st Attempt Only second = 2nd Attempt Only last = Last Attempt (default) |
No |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/exam/f5c883/grouptype/f33c68/groupanalysis.json?examattempt=all' \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_REQUEST_ERROR | The examattempt parameter value needs to be -1, 1 or 2 |
Get a Multi-Exam Report
See which students passed or not a series of exams. A Multi-Exam Report can be filtered by Group and/or Passed or Failed exams
Returns
A list of students results with filtering parameters applied.
Required Permissions
Report Generation | Generate Quick Reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/report/multiexam.json?groupid={groupid}&passorfail=FAIL |
Input Parameters | Description | Required |
---|---|---|
passorfail | This parameter takes one of 2 possible values: PASS = passing scores only FAIL = failing scores only |
Yes |
groupid | To specify a group of students, use the group ID of the Group. |
No |
cURL Example Request
Example 1: All Students Passing a two specific Exams
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/multiexam.json?passorfail=PASS' -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "Content-Type: application/json" \ -d '{"examids" : ["88cfe393f927ab42", "52d6300e19b6a5950"]}' |
Example 2: All Students that did not pass pass on two specific Exams and Belonging to a Specific Group
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/multiexam.json?groupid=904e6503&passorfail=FAIL' -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ -H "Content-Type: application/json" \ -d '{"examids" : ["88cfe393f927ab42", "52d6300e19b6a5950"]}' |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_REQUEST_ERROR | The passorfail parameter was invalid. Expecting 'PASS' or 'FAIL' |
Get a Date Range Report
Track results for every exam taken for a specific timeframe. A Date Range Report can be filtered by Group id
Returns
A list of students results with filtering parameters applied.
Required Permissions
Report Generation | Generate Quick Reports |
---|
Usage
GET | https://instructor.exambuilder.com/v2/instructor/{instructorid}/report/daterange.json?groupid={groupid}&date1={encodeddate}&date2={encodeddate} |
Input Parameters | Description | Required |
---|---|---|
groupid | To specify a group of students, use the group ID of the Group. |
No |
date1 | The first date of the range. Use the USA format of MM/DD/YYYY, URL Encoded. For example, 07/14/2014 | Yes |
date2 | The last date of the range. The format is the USA version of MM/DD/YYYY, URL Encoded. For example, 08/30/2014 | Yes |
cURL Example Request
curl |
https://instructor.exambuilder.com/v2/instructor/a1b2c3/report/daterange.json?&groupid=494D954400&date1=01%2F01%2F2014&date2=03%2F31%2F2016' \ -u 4A486C4146459B2995BC:0D7517BAB1018897856082E5D5589500 \ |
Example Response
GUI Accessibility
Yes.
Errors
Error Code | Description |
---|---|
API_AUTHENTICATION_FAILED | The API Key and API Secret combination was invalid |
INVALID_ACTION | The URL path does not exist |
INVALID_INSTRUCTOR | The Instructor ID was invalid |
ROUTE_PERMISSION_ERROR | The Super User of this account did not grant permission to access this resource |
INVALID_EXAM | The exam ID was invalid or insufficient permissions to access this resource |
INVALID_GROUP | The group ID was invalid or insufficient permissions to access |
INVALID_REQUEST_ERROR | The date1 or date2 parameter was invalid or missing. Expecting both parameter to be url encoded. |