LAN Exam Maker (On-Premise Version) API & SSO Help Document¶
OnlineExamMaker platform offers 2 API call methods for our SaaS version (OnlineExamMaker) and on-premise version (LAN Exam Maker). If you buy our on-premise version software, and want to login with SSO, or get candidate date, exam report data, or manage student groups from the software, you can read this API help document for on-premise version.
Single Sign-On (SSO) for LAN Exam Maker (On-Premise Version)¶
Note: 1. Please replace the API url with your own IP+port or own domain name. 2. Get verification code in "System Settings" -> "API & SSO Settings" in your LAN Exam Maker dashboard.
Single sign-on (SSO) allows candidates to log in their own system only and click on the online exam entrance to take exams without login their candidate accounts again.
For example, one company has his own OA system and use SSO, an employee logs into the OA system, he can click the entrance of the exam in the system without login his candidate account again.
1. Online exam taker login with SSO (API for on-premise version)¶
The SSO to Exam allows exam takers to click the exam entrance directly on the user system to enter the exam, and no additional identity authentication is required. Below is the usage:
Request
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.newStudentSSO&format=raw
Request data
code=authorization code&loginValue=login field value&password=password&eid=exam ID
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- loginValue: The unique login field of exam takers，you can use student email, or phone number as loginvalue.
- password: Candidate password. If a candidate doesn't have password, you can leve a blank.
- eid: Exam id.
After successful login, the system will automatically jump to the online exam, and no identity verification is required.
2. Candidate dashboard login with SSO (API for on-premise version)¶
The principle of single sign-on to the candidate dashboard is the same as single sign-on to the online exam, the difference is that the eid parameter is not passed or 0 is passed.
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.newStudentSSO&format=raw&loginValue=13487361736&password=1294783&eid=0
When the system determines that the eid is 0, it will automatically jump to the candidate dashboard interface.
3. Sub-admin login with SSO (API for on-premise version)¶
Sub-admins sign in dashboard using SSO, here is the interface:
Request
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.childAdminSSO&format=raw
Request data
code=authorization code&email=email&password=password
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- email: The email of the sub-admin, this value is required.
- password: The password of the sub-admin, this value is required.
After successful login, the system will automatically jump to the management backend
Get exam score (API for on-premise version)¶
Note: 1. Please replace the API url with your own IP+port or own domain name. 2. Get verification code in "System Settings" -> "API & SSO Settings" in your LAN Exam Maker dashoboard.
1. Get exam score of a single candidate¶
Get exam score of a single candidate
Here is the API interface
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.queryResults&format=raw
Parameter:
code=authorization code&eid=exam ID&loginValues=candidate login field&start=0&limit=30
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- eid: Exam id.
- loginValue: The unique login field of exam takers，you can use student email, or phone number as loginvalue.
- year: Used to query data of different years. The default is the current year. Example: 2024. This is an optional parameter.
- start: Used for paging display when the amount of data is large, indicating the data offset of the paging, the default value is 0. This is an optional parameter.
- limit: Used for distributed display when the amount of data is large. Set the number of data to be displayed per page. The default value is 30. This is an optional parameter.
This interface returns all the test record information of the examinee in this exam
[
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//The link to view detailed exam details has a 30-minute time limit. If you exceed 30 minutes, you must obtain the link again.
"score": 30,//Exam score, float type
"startTime": 1539075728,//The timestamp when the candidate starts answering the questions, int type, unit s (seconds)
"endTime": 1539075828,//The timestamp of the examinee submitting the paper, int type, unit s (seconds)
"status": 1,//Exam status, 1 means normal submission, 0 means the test is in progress, 2 means automatic submission after timeout, 3 means forced submission by the administrator, and 4 means submission by the system
},
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//The link to view detailed exam details has a 30-minute time limit. If you exceed 30 minutes, you must obtain the link again.
"score": 32,//Exam score, float type
"startTime": 1539075628,//The timestamp when the candidate starts answering the questions, int type, unit s (seconds)
"endTime": 1539075828,//The timestamp of the examinee submitting the paper, int type, unit s (seconds)
"status": 1,//Exam status, 1 means normal submission, 0 means the test is in progress, 2 means automatic submission after timeout, 3 means forced submission by the administrator, and 4 means submission by the system
},
]
2. Get exam scores of all candidates¶
If you do not set loginValues for particular exam takers， the system will return exam scores of all candidates.
[
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//The link to view detailed exam details has a 30-minute time limit. If you exceed 30 minutes, you must obtain the link again.
"score": 30,//Exam score, float type
"startTime": 1539075728,//The timestamp when the candidate starts answering the questions, int type, unit s (seconds)
"endTime": 1539075828,//The timestamp of the examinee submitting the paper, int type, unit s (seconds)
"loginValues": 19382,
"name": "James"
},
{
"viewResult":"http://192.168.0.1:5858/viewresult/token",//The link to view detailed exam details has a 30-minute time limit. If you exceed 30 minutes, you must obtain the link again.
"score": 32,//Exam score, float type
"startTime": 1539075628,//The timestamp when the candidate starts answering the questions, int type, unit s (seconds)
"endTime": 1539075828,//The timestamp of the examinee submitting the paper, int type, unit s (seconds)
"loginValues": 19310, //Candidate login field
"name": "Mark" //Candidate name
},
]
3. Get the list of exams¶
You can get the list of exams via API, here is the example:
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.getExams&format=raw
Parameter:
code=authorization code&start=0&limit=30
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- start: Used for paging display when the amount of data is large, indicating the data offset of the paging, the default value is 0. This is an optional parameter.
- limit: Used for distributed display when the amount of data is large. Set the number of data to be displayed per page. The default value is 30. This is an optional parameter.
Return data:
[
{
"eid": 23812,//Exam id，int type.
"title": "English Grammar Level Test", // Exam title,string type.
"img": "http://192.168.0.1:5858/xxxxx.jpg",// Link of exam cover，string type.
"url": "http://192.168.0.1:5858/23812", //exam link, string type.
"createTime": 1539075828,//Unix timestamp of the test exam creation time, int type, unit s (seconds)
"available": 1, //Whether the exam is available，int type, 1 means available, 0 means unavailable.
"times": 3918, //Exam taken time
"category": "Languae Learning" //Exam category
},
...
]
Candidate management (API for on-premise version)¶
Note: 1. Please replace the API url with your own IP+port or own domain name. 2. Get verification code in "System Settings" -> "API & SSO Settings" in your LAN Exam Maker dashoboard.
1. Get candidate field information¶
Below is the interferce to get candidate field information.
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.getStudentFields&format=raw
code=authorization code
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
Return data:
[
{
"sFid":1,// Field id, int type.
"label": "name", //Field label, string type.
"isLoginField": false, //Whether it is a login field. There can only be one login field. If it does not exist or is equal to false, it is a normal field. Boolean type
}
]
Return data:
[
{
"sFid": 1,
"sLabel": "name"
},
{
"sFid": 2,
"sLabel": "gender"
},
{
"sFid": 4,
"sLabel": "phone"
},
{
"sFid": 5,
"sLabel": "ID"
},
{
"sFid": 10,
"sLabel": "password"
},
//The above fields are system default fields. There may be more fields in reality.
...
]
You can add and mofidy fields in LAN exam system.
2. Batch insert candidate information¶
You can add one or multiple candidates via API, here is the example:
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.addStudentsV2&format=raw
Parameter:
code=authorization code
students=[ //Candidate array, each element object represents a candidate
{ //Represents a candidate information object
"gid": 11, //The id of the candidate group
"fields": [ //Candidate information
{
"sFid": 1, // Candidate field id, int type, this value can be obtained through the "Get Candidate Information Field" API, such as the "Mobile Phone" field id is 4, the name field id is 1.
"value":"John" //The value of the candidate field. If the value of sFid is 1, fill in the name here.
},
...
{
"sFid": 4, // Candidate field id, int type, this value can be obtained through the "Get Candidate Information Field" API, such as the "Mobile Phone" field id is 4, the name field id is 1
"value":"13800000000" //The value of the candidate field. For example, if the value of sFid is 4, enter the mobile phone number here.
}
]
},
...
{ //Represents a candidate information object
"gid": 11, //The id of the candidate group
"fields": [ //Candidate information
{
"sFid": 1, // Candidate field id, int type, this value can be obtained through the "Get Candidate Information Field" API, such as the "Mobile Phone" field id is 4, the name field id is 1.
"value":"Tony
" //The value of the candidate field. If the value of sFid is 1, fill in the name here.
},
...
{
"sFid": 4, // Candidate field id, int type, this value can be obtained through the "Get Candidate Information Field" API, such as the "Mobile Phone" field id is 4, the name field id is 1.
"value":"13800000001" //The value of the candidate field. For example, if the value of sFid is 4, enter the mobile phone number here.
}
]
}
]
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- students: The students you want to add, gid is the group ID you want to add.
This interface returns the successfully added candidate sid
{
"status": "ok", //Returns ok if successful, error if failed
"success": [ //The data added successfully, each element is an object, sid represents the candidate id, index represents the data index of the candidate to be added
{
"sid":123,
"index":1
},
{
"sid":125,
"index":2
}
],
"fail": [3,4,5] //Fail indicates the index of failed candidates
}
3. Modify candidate information in batches¶
You can modify the information of one or multiple candidate via API interferce.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.updateStudents&format=raw
Parameter:
code=authorization code
stuInfo=[ //Candidate array, each element object represents a candidate
{ //Represents a candidate information object
"sid": 11, //Candidate id, id and login value cannot be empty at the same time, one must be filled in
"loginValue":"Morris" //Candidate login value, id and login value cannot be empty at the same time, one must be filled in
"fields": [ //Candidate information
{
"sFid": 1, // Candidate field id, int type, this value can be obtained through the "Get Candidate Information Field" API, such as the "Mobile Phone" field id is 4, the name field id is 1.
"value":"Jack" //The value of the candidate field. If the value of sFid is 1, fill in the name here.
},
]
},
]
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- stuInfo: The candidate information to be updated, sid represents the candidate ID, loginValue represents the candidate login value, and fields represents the candidate's field information
This interface returns the successfully modified candidate sid or login value.
{
"status": "ok", //Returns ok if successful, error if failed
"success": [1,2], //Indicates the successful candidate ID or login value
"fail": [3,4,5] //fail indicates the failed candidate ID or login value
}
4. Batch delete candidate information¶
Use this API interface to delete one or multiple candidates.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.delStudents&format=raw
Parameter:
code=authorization code
loginValues=["1000","10001"] //Candidate login value list, string array, choose between id and login value, login value is read first
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- loginValues: Display the list of candidate login values to be deleted.
This interface returns the successfully deleted candidate sid or login value.
{
"status": "ok", //Returns ok if successful, error if failed
"success": [1,2], //Indicates the sid or login value of the candidates
"fail": [3,4,5] //Fail indicates the sid or login value of the failed candidate
}
If the operation fails, the return value is:
{
"status": "error", //Returns ok if successful, error if failed
"error": "invalid sid" //error, returns unsuccessful sid
}
5. Move candidates to a group¶
Use this interface to move one or more candidates to one or more groups.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.mvStudents&format=raw
Parameter:
code=authorization code
mvStuInfo={
"gids": [22,33], //If there are multiple values in gids, it means adding the candidate to these groups (PS a candidate is allowed to exist in multiple groups at the same time)
"loginValues":["John","Andres"] //Candidate login field value, string array
"action": "addto|moveto" //Addto means adding to a group. At this time, a candidate may exist in multiple groups. Moveto means moving to a group. At this time, the candidate only exists in one group.
}
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- mvStuInfo: The candidates that need to be moved.
This interface returns the loginValue of the successfully added candidate.
{
"status": "ok", //Returns ok if successful, error if failed
"success": [1,2], //sid or login value of the successful candidates
"fail": [3,4,5] //fail show the candidates that fail to move.
}
If the operation fails, the return value is:
{
"status": "error", //Returns ok if successful, error if failed
"error": "invalid sid" //error, returns unsuccessful info.
}
6. Get candidate information¶
You can use this API interface to get the information of one or multiple candidates.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.getStudentsInfo&format=raw
Parameter:
code=authorization code
loginValues=[13212,2382,392]
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- loginValues: The list of candidate loginvalues.
You can check the information of up to 10 candidates at a time.
If the operation is successful, the return value is:
{
"status": "ok", //Returns ok if successful, error if failed
"data": [
{
"loginValue":"John",//Candidate login value. If the request is loginValues, then loginValue is returned.
"fields":[
{
"sFid":1,
"label":"name",
"value": "John"
},
{
"sFid":13,
"label":"team",
"value": "Department"
}
],
"group": [
"gid": 123, //Group ID
"title": "English Learning" //Group name
]
},
{
"loginValue": 3925, //Candidate ID
"loginValue":"Tom",//Candidate login value. If the request is loginValues, then loginValue is returned.
"fields":[
{
"sFid":1,
"label":"name",
"value": "Tom"
},
{
"sFid":13,
"label":"team",
"value": "Department"
}
],
"group": [
"gid": 123, //Group ID
"title": "English Learning" //Group name
]
}
]
}
If the operation fails, the return value is:
{
"status": "error", //Returns ok if successful, error if failed
"error": "invalid sid" //error, returns unsuccessful info.
}
Candidate group management (API for on-premise version)¶
Note: 1. Please replace the API url with your own IP+port or own domain name. 2. Get verification code in "System Settings" -> "API & SSO Settings" in your LAN Exam Maker dashoboard.
The system allows exam organizers manage students, employees, learners in groups, you can create, delete, or rename a goup directly.
1. Add a candidate group¶
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.newGroup&format=raw
Parameter:
code=authorization code&title=group title&parentGid=0
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- title: Group title.
- parentGid: Parent node id. If the value is 0, it means inserting the root node.
If the operation is successful, the return value is:
{
"status": "ok", //ok means success, error means error
"gid": 1931 //gid is the ID of new created group.
}
If the operation fails, the return value is:
{
"status": "error",
"error": "Title cannot be empty" //Error information
}
2. Edit group name¶
This API interface can be use to modify the group name of the currunt group.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.renameGroup&format=raw
Parameter:
code=authorization code&title=group title&gid=0
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- title: New group name.
- gid: The id of the group that are modified.
If the operation is successful, the return value is:
{
"status": "ok", //ok means success, error means error
"gid": 1931, //Group ID
"oldTitle": "Math 1" //Old group title name
}
If the operation fails, the return value is:
{
"status": "error",
"error": "Title cannot be empty" //Error information
}
3. Delete a candidate group¶
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.delGroup&format=raw
Parameter:
code=authorization code&gid=231
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- gid: The id of the group that is deleted.
If the operation is successful, the return value is:
{
"status": "ok", //ok means success, error means error
}
If the operation fails, the return value is:
{
"status": "error",
"error": "Incorrect group ID, please confirm whether you have permission to modify the group information" //Error information
}
4. Move a candidate group¶
Move a group to be a subgroup of another group.
POST http://192.168.0.1:5858/index.php?option=com_exams&task=api.mvGroup&format=raw
Parameter:
code=authorization code&gid=112&mvToGid=23
Parameter description:
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- gid: The id of the group that is moved.
- mvToGid: The id of the targeted group.
If the operation is successful, the return value is:
{
"status": "ok", //ok means success, error means error
}
If the operation fails, the return value is:
{
"status": "error",
"error": "Incorrect group ID, please confirm whether you have permission to modify the group information" //Error information
}
5. Get group list¶
Returns all subgroup information under a group (or all groups).
GET http://192.168.0.1:5858/index.php?option=com_exams&task=api.lsGroups&format=raw
Parameter:
code=authorization code&gid=112
- code: Verification code (string data type) is unique to each account, users of LAN Exam Maker can get it in "System Settings".
- gid(Optional): If this parameter is set, the information of all subgroups under the group will be listed. If gid is 0 or not set, it means listing the group data under all root paths.
If the operation is successful, the return value is:
{
"status": "ok", //ok means success, error means error，
"data": [
{
"gid": 1312, //Group ID
"title": "English Learning", //Group title
},
{
"gid": 1332, //Group ID
"title": "Math Skills", //Group title
}
...
]
}
If the operation fails, the return value is:
{
"status": "error",
"error": "Incorrect group ID, please confirm whether you have permission to modify the group information" //Error information
}