ExamBuilder API Reference

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 members and parameters using multiple words within their name will use the common convention of the first word being lower case and all other words being capitalized, with no white space.

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

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_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_STUDENTThe user ID was invalid or this account does not have permission to this resource

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_STUDENT_EXAMThe 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 AuthoringCreate and edit exams
Exam AuthoringActivate, 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe 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 AuthoringCreate and edit exams
Exam AuthoringActivate, 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_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe 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 StudentsCreate and group students
Managing StudentsEdit and group students
Managing StudentsDelete students
Scheduling StudentsSchedule 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 ParametersDescriptionRequired
firstnameThe student's first nameNo
lastnameThe student's last nameNo
studentidThe User ID assigned to the student by the training departmentNo
sortAn 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
sortdirectionAn 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe 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 StudentsCreate and group students
Managing StudentsEdit and group students
Managing StudentsDelete students
Scheduling StudentsSchedule students and add more time to student exam attempt
Scheduling StudentsReset 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_STUDENTThe 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
firstNameThe student's first name. This is passed in via JSON.Yes
lastNameThe student's last name. This is passed in via JSON.Yes
studentIdA 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
passwordThe password the student will use to log in to the Web portal. This is passed in via JSON.Yes
employee_numberAn optional field (String) that can be used for internal purposes. This is passed in via JSON. No
group_idsAn optional list of group IDs that can be used to assign the new student to demographic groups. This is passed in via JSON.No
JSON Object: {"firstName":"{value}","lastName":"{value}", "studentId":"{value}", "password":"{value}", “employee_number”:”{value}”, "group_ids" : ["{identifier}", "{identifier}"] }

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
OUT_OF_STUDENT_LICENSESAll available licenses used. Additional licenses must be purchased by a Super User to add more students.
FIRST_NAME_REQUIREDThe first name parameter was missing or null
LAST_NAME_REQUIREDThe last name parameter was missing or null
STUDENTID_REQUIREDThe student ID parameter was missing or null
PASSWORD_REQUIREDThe password parameter was missing or null
STUDENTID_EXISTSThe 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
firstNameThe student's first name. This is passed in via JSON.No
lastNameThe student's last name. This is passed in via JSON.No
studentIdA 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
passwordThe password the student will use to log in to the Web portal. This is passed in via JSON.No
employee_numberAn optional field (string) that can be used for internal purposes. This is passed in via JSON. No
JSON Object: {"firstName":"{value}","lastName":"{value}", "studentId":"{value}","password":"{value}", "employee_number":"{value}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
OUT_OF_STUDENT_LICENSESAll available licenses used. Additional licenses must be purchased by a Super User to add more students.
FIRST_NAME_REQUIREDThe first name parameter was missing or null
LAST_NAME_REQUIREDThe last name parameter was missing or null
STUDENTID_REQUIREDThe student ID parameter was missing or null
PASSWORD_REQUIREDThe password parameter was missing or null
STUDENTID_EXISTSThe 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INITIALS_REQUIREDThe initials portion of the URI was missing or invalid.
STUDENT_NOT_FOUNDThe student account was not found. Confirm that the User ID is valid and the student exists
INVALID_STUDENTInsufficient 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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
STUDENT_NOT_FOUNDThe student account was not found. Confirm that the User ID is valid and the student exists
INVALID_STUDENTInsufficient 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 StudentsView student scores and basic reports

Usage

GET https://instructor.exambuilder.com/v2/instructor/{instructorid}/student/{userid}/exams.json
Input Parameters Description Required
showallattempts0 = 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
STUDENT_NOT_FOUNDThe student account was not found. Confirm that the User ID is valid and the student exists
INVALID_STUDENTInsufficient 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 StudentsView 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
STUDENT_NOT_FOUNDThe student account was not found. Confirm that the User ID is valid and the student exists
INVALID_STUDENTInsufficient permission to delete this student.
INVALID_USEREXAMIDThe 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
group IDGroup Name
904e6503Canada
73a183c7Germany
00e41ee7England
group IDGroup Name
ccd6904eSales
39511defHuman Resources
cfb11fa8IT Security

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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe 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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe 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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_CATEGORY_IDThe 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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_GROUPThe 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 StudentsCreate and group students
Managing StudentsEdit 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_GROUPThe 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_CATEGORY_IDThe category ID was invalid
INVALID_GROUPThe 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 StudentsCreate and group students
Managing StudentsEdit and group students

Usage

POST https://instructor.exambuilder.com/v2/instructor/{instructorid}/group/{groupid}/members/add.json
Input Parameters Description Required
userIdThe User ID of the student to be added to the Group.Yes
JSON Object: {"userId":"{identifier}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_STUDENTThe 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
userIdThe User ID of the student to be removed from the Group.Yes
JSON Object: {"userId":"{identifier}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
GROUP_MEMBER_DOES_NOT_EXISTThe student does not exist in this Group
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_STUDENTThe 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:

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 StudentsSchedule students and add more time to student exam attempt
Scheduling StudentsReset or delete student exam attempt

Usage

GEThttps://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?examId={identifier}
GEThttps://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?userId={identifier}
GEThttps://instructor.exambuilder.com/v2/instructor/{instructorid}/student/scheduled.json?examid={identifier}&userId={identifier}
Input Parameters Description Required
useridThe identifier of a unique student. No*
examidThe identifier of a unique exam.No*
* At least one parameter is required

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
USERID_OR_EXAMID_REQUIREDThis request requires at least 1 parameter; either User ID or exam ID. Passing both parameters is allowed
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_STUDENTThis 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
userIdThe identifier of a unique student. This is passed in via JSON.Yes
JSON Object: {"userId":"{identifier}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
STUDENT_ALREADY_SCHEDULEDThis 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:

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_USEREXAMIDThe user exam ID was invalid
DELETE_EXAM_ATTEMPT_FAILEDThe 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_USER_EXAMThe "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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_USER_EXAMThe user exam ID was invalid
STUDENT_NOT_SCHEDULEDThe exam could not be reset because this student is not scheduled for this exam
RESET_FAILED_EXAM_COMPLETEDThe 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
daysAn 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
hoursAn 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
minutesAn 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
JSON Object: {"days":”{value}”,"hours":"{value}","minutes":"{value}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
STUDENT_NOT_SCHEDULEDThis student is not scheduled to take this exam
EXAM_IS_NOT_TIMEDThis exam is not timed. Time can only be added to a timed exam.
NOT_THE_LATEST_EXAM_ATTEMPTThe 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
groupIdTo 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
targetAn 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
JSON Object: {"groupid" : "{identifier}" or 0, "target" : "{vocab}"}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe 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
JSON Object: {"groupid" : "{identifier}" or 0}

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe 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 StudentsSchedule students and add more time to student exam attempt
Scheduling StudentsReset or delete student exam attempt
Report GenerationGenerate Quick Reports

Usage

GET https://instructor.exambuilder.com/v2/instructor/{instructorid}/scheduler/exam/{examid}/schedule/search?filter={identifier}&groupid={identifier}
Input Parameters Description Required
statusThis 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
groupidThe group ID of the GroupNo

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
INVALID_IDAn 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
passorfailThis parameter takes one of 3 possible values:
PASS = passing scores only
FAIL = failing scores only
COMPLETED = both passing and failing scores
No
groupidThe group ID of the GroupNo
timeperiodLimit 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
date1The first date of the range. Use the USA format of MM/DD/YYYY, URL Encoded. For example, 07/14/2014No*
date2The last date of the range. The format is the USA version of MM/DD/YYYY, URL Encoded. For example, 08/30/2014No*
*Both date1 and date2 are required if timeperiod = dateRange

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_DATEThe 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_ERRORThe 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
examattemptThe attempt of the exam. Possible values are:
all = All Attempts
first = 1st Attempt Only
second = 2nd Attempt Only
last = Last Attempt (default)
No
group1The 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
NO_EXAMS_COMPLETEDThe report could not be run because no student completed this exam
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_REQUEST_ERRORThe 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 IDof 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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_REQUEST_ERRORThe 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
date1The first date of the range. Use the USA format of MM/DD/YYYY, URL Encoded. For example, 07/14/2014Yes
date2The last date of the range. The format is the USA version of MM/DD/YYYY, URL Encoded. For example, 08/30/2014Yes

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 CodeDescription
API_AUTHENTICATION_FAILEDThe API Key and API Secret combination was invalid
INVALID_ACTIONThe URL path does not exist
INVALID_INSTRUCTORThe Instructor ID was invalid
ROUTE_PERMISSION_ERRORThe Super User of this account did not grant permission to access this resource
INVALID_EXAMThe exam ID was invalid or insufficient permissions to access this resource
INVALID_GROUPThe group ID was invalid or insufficient permissions to access
INVALID_REQUEST_ERRORThe date1 or date2 parameter was invalid or missing. Expecting both parameter to be url encoded.