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

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

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 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

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 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

`group ID`	Group Name
904e6503	Canada
73a183c7	Germany
00e41ee7	England

`group ID`	Group Name
ccd6904e	Sales
39511def	Human Resources
cfb11fa8	IT 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 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

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 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

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 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*

* 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 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

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 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

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 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

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 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

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 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*

*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 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.

ExamBuilder API Reference

Introduction

Formatting

Vocabulary

Request Information

Enabler Requests

Get Instructor ID

Returns

Required Permissions

Usage

cURL Example Request

Example Response

GUI Accessibility

Errors

Get SSO Link

Returns

Required Permissions

Usage

cURL Example Request

Example Response

GUI Accessibility

Errors

Get SSO Exam Link

Returns

Required Permissions

Usage

cURL Example Request

Example Response

GUI Accessibility

Errors

Exam Requests

List Exams

Returns

Required Permissions

Usage

cURL Example Request

Example 1: List All Exams

Example 2: Search for an Exam by Name

Example 3: Search for an Exam by Active State

Example Response

GUI Accessibility

Errors

Get Exam

Returns

Required Permissions

Usage

cURL Example Request

Example Response

GUI Accessibility

Errors

Student Requests

List Students

Returns

Required Permissions

Usage

cURL Example Request

Example 1: List All Students (newest students first)

Example 2: Search for a Student

Example Response

GUI Accessibility

Errors

Get Student

Returns

Required Permissions

Usage

cURL Example Request

Example Response

GUI Accessibility

Errors

Create Student

Returns

Required Permissions

Usage

cURL Example Request

Example 1: Create a Student without Groups

Example 2: Create a Student with Groups

Example Response

GUI Accessibility

Errors

Update Student