Synchronizing the datum of candidates can conveniently exchange the candidates’ datum between the system, and avoid the error that may appear manually. Automatic synchronization is timely and quick, which can synchronize the information of the candidates and the organizations they belong to.

Category Management

Online Exam Maker  manages the candidates by category, which can be understood as the class, the department. Online Exam Maker supports infinite  hierarchical tree group management, as shown in the figure below

(1)Category Addition

The interface to add category of candidates

POST https://www.onlineexammaker.com/index.php?option=com_exams&task=api.newGroup&format=raw

Parameter

code=access code&title=category title&parentGid=0

• code: A unique verification code for each account, String type, a value that can be obtained by associating with Online Exam Maker
• title: the title of category
• parentGid: The ID of the parent category, 0 means the root category is created, and greater than 0 means a subcategory under that category is created

Return if the operation is successful

{
    "status": "ok", //ok means successful， error means failed
    "gid": 1931 //gid means the ID of the new category
}

Return if the operation fails

{
“status”: “error”,
“error”: “the title cannot be empty” //Error message that occurred while creating
}

(2)Category Editing

The interface to edit the name of an existing category

POST https://www.onlineexammaker.com/index.php?option=com_exams&task=api.renameGroup&format=raw

Parameter

code=access code&title=category title&gid=0

• code: A unique verification code for each account, String type, a value that can be obtained by associating with Online Exam Maker
• title: the new title of category
• gid: alter the ID of category, it need to be greater than 0

Return if the operation is successful

{
“status”: “ok”, //ok means successful， error means failed
“gid”: 1931, //gid means the ID of the category
“oldTitle”: “Math 1” //means the original title
}

Return if the operation fails

{
    "status": "error",
    "error": "the title cannot be empty" //Error message that occurred while creating
}

(3)Category Deleting

The interface to delete a group

POST https://www.onlineexammaker.com/index.php?option=com_exams&task=api.delGroup&format=raw

Parameter

code=access code&gid=231

• code: A unique verification code for each account, String type, a value that can be obtained by associating with Online Exam Maker
• gid: delete the ID of category, it need to be greater than 0

Return if the operation is successful

{
    "status": "ok", //ok means successful， error means failed
}

Return if the operation fails

{
    "status": "error",
    "error": "incorrect ID of the category, Please confirm whether you have permission to modify the category's information" //Error message that occurred while creating
}

(4)Category Transfer

The interface  to move a category  to the subgroup of another category

POST https://www.onlineexammaker.com/index.php?option=com_exams&task=api.mvGroup&format=raw

Parameter

code=access code&gid=112&mvToGid=23

• code: A unique verification code for each account, String type, a value that can be obtained by associating with Online Exam Maker
• gid:  the ID of category to move to, it need to be greater than 0
• mvToGid: The ID of the category to move to

Return if the operation is successful

{
    "status": "ok", //ok means successful， error means failed
}

It indicates that a gid has been moved to mvToGid and becomes a subgroup of it

Return if the operation fails

{
    "status": "error",
    "error": "incorrect ID of the category, Please confirm whether you have permission to modify the category's information" //Error message that occurred while creating 
}

(5)Category List Acquisition

The interface to return  all subgroup information under a group (or all groups)

GET https://www.onlineexammaker.com/index.php?option=com_exams&task=api.lsGroups&format=raw

Parameter

code=access code&gid=112

• code: A unique verification code for each account, String type, a value that can be obtained by associating with Online Exam Maker
•  gid: an optional parameter. If this parameter is set, information for all subgroups under that category is listed. If the gid is 0 or not set,  the category data of all root paths will be listed

Return if the operation is successful

{
    "status": "ok", //ok means successful， error means failed，
    "data": [
        {
            "gid": 1312, //category ID
            "title": "category title", //title of the category
        },
        {
            "gid": 1332, //category ID
            "title": "category title", //title of the category
        }
        ...
    ]
}

Return if the operation fails

{
    "status": "error",
    "error": "incorrect ID of the category, Please confirm whether you have permission to modify the category's information" //Error message that occurred while creating 
}

(1)Interface to get the score of one candidate

GET https://onlineexammaker.com/index.php?option=com_exams&task=api.queryResults&format=raw

Parameter:

code=accesscode&eid=examID&sid=candidateID&start=0&limit=30

• code: the verification code unique to each account, string type, please contact us to get it.
• eid is the exam ID
• sid represents the candidate ID, optional parameter, if the parameter is 0 or not provided, it will display all the candidates
• start is used for paging display when the amount of data is large, indicating the data offset of the paging; defaulting it is 0, optional parameters.
• limit is used for distribution display when the amount of data is large, set the number of data displayed per page; defaulting it is 30, optional parameters.

Return data of  all the candidates’ test record :

[
    {
        "viewResult":"https://ks.onlineexammaker.com/viewresult/token",//Check the link for detailed exam details, there is a 30-minute time limit, you must re-obtain the link after 30 minutes
        "score": 30,//score，float type
        "startTime": 1539075728,//Timestamp when the candidate started answering, int type, unit:s (seconds)
        "endTime": 1539075828,//Timestamp for submitting papers, int type, unit:s (seconds)
        "status": 1,//Indicates the answering status, 1 indicates normal submission, 0 is in the test, 2 indicates automatic submission during timeout, 3 indicates forced submission by the administrator, and 4 indicates that the system executes the submission
    },
    {
        "viewResult":"https://ks.onlineexammaker.com/viewresult/token",//Check the link for detailed exam details, there is a 30-minute time limit, you must re-obtain the link after 30 minutes
        "score": 32,//score，float type
        "startTime": 1539075628,//Timestamp when the candidate started answering, int type, unit:s (seconds)
        "endTime": 1539075828,//Timestamp for submitting papers, int type, unit:s (seconds)
        "status": 1,//Indicates the answering status, 1 indicates normal submission, 0 is in the test, 2 indicates automatic submission during timeout, 3 indicates forced submission by the administrator, and 4 indicates that the system executes the submission
    },
]

(2)Interface to get the score records of all candidates

If no sid is specified, then all the test record data will be returned.

[
    {
        "viewResult":"https://ks.onlineexammaker.com/viewresult/token",//Check the link for detailed exam details, there is a 30-minute time limit, you must re-obtain the link after 30 minutes
        "score": 30,//score，float type
        "startTime": 1539075728,//Timestamp when the candidate started answering, int type, unit:s (seconds)
        "endTime": 1539075828,//Timestamp for submitting papers, int type, unit:s (seconds)
        "sid": 19382,
        "name": "Tom"
    },
    {
        "viewResult":"https://ks.onlineexammaker.com/viewresult/token",//Check the link for detailed exam details, there is a 30-minute time limit, you must re-obtain the link after 30 minutes
        "score": 32,//score，float type
        "startTime": 1539075628,//Timestamp when the candidate started answering, int type, unit:s (seconds)
        "endTime": 1539075828,//Timestamp for submitting papers, int type, unit:s (seconds)
        "sid": 19310, //Candidates ' ID 
        "name": "Tom" //Cnadidates 'name
    },
]

(3)Inteface to get  the exam list

If there are many exans, you need to dynamically obtain the exam list through the following interface.

GET https://onlineexammaker.com/index.php?option=com_exams&task=api.getExams&format=raw

Parameter:

code=accesscode&start=0&limit=30

• code: the verification code unique to each account, string type, please contact us to get it.
• start is used for paging display when the amount of data is large, indicating the data offset of the paging; defaulting it is 0, optional parameters
• limit is used for paging display when the amount of data is large, set the number of data displayed per page; defaulting it is 30, optional parameters

Return data：

[
    {
        "eid": 23812,//exam id，int type
        "title": "exam title", // exam title，string type
        "img": "https://fs.onlineexammaker.com/xxxxx.jpg",// Link to exam cover，string type
        "url": "https://ks.onlineexammaker.com/23812", //exam link，string type
        "createTime": 1539075828,//Unix timestamp of exam creating time, int type, unit:s (seconds)
        "available": 1, //Whether the test paper is available, int type, 1 means available, 0 means unavailable
        "times": 3918, //exam taking times
        "category": "category name" //exam category name
    },
    ...
]

1. Candidate information field

The Interface to  get candidatas’ fields:

GET https://onlineexammaker.com/index.php?option=com_exams&task=api.getStudentFields&format=raw

(1) Data Interface

code=accesscode

• code: the verification code unique to each account, string type, please contact us to get it.

(2)Return data

[
    {
        "sFid":1,// field id，int
        "label": "name", //field， string
        "isLoginField": false, //if shows false, means it is the ordinary field instead of login field
    }
]

(3)The data returned normally is as follows

[
    {
        "sFid": 1,
        "sLabel": "name"
    },
    {
        "sFid": 2,
        "sLabel": "gender"
    },
    {
        "sFid": 4,
        "sLabel": "phone number"
    },
    {
        "sFid": 5,
        "sLabel": "ID card"
    },
    {
        "sFid": 10,
        "sLabel": "password"
    },
    //all aboveare thedefault fields, may be more, please refer to the actual object obtained
    ...
]

• If you want to add and modify the fields, please login the system and go to the candidate management.

2. Candidates Mangemanet

Candidate management interface provides functions to add, modify and delete candidate information.

(1)Interface to add candidates:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.addStudentsV2&format=raw

Parameter:

code=accesscode
students=[                      //candidates group，Each item object represents one candidate
    {                           //represents one candidate
        "gid": 11,              //id for the group
        "fields": [             //candidates information item
            {
                "sFid": 1,      // field id，int，can be got from the api of field，e.g.:"iphone number"id is 4, Name is 1
                "value":"Tom"  //field，e.g.: if sFid is 1，then it is name
            },
        ]
    },
]

• code: the verification code unique to each account, string type, please contact us to get it.
• Students indicates the candidate information to be added, and gid indicates the group to which the candidate is to be added. If it is multiple groups, please use a comma to separate  string. Fields indicate candidates’ information items.

The return data when add successfully:

{
    "status": "ok",     //Successful return:ok, failed to return:error
    "success": [        //Successfully added data, each element is an object, sid indicates the candidate id, index indicates the order 
        {
            "sid":123,
            "index":1
        },
        {
            "sid":125,
            "index":2
        }
    ], 
    "fail": [3,4,5]     //fail means the students failed to add
}

(2)Interface to modify candidates information:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.updateStudents&format=raw

Parameter:

code=accesscode
stuInfo=[                      //candidates group，Each item object represents one candidate
    {                           //represents one candidate item
        "sid": 11,              //candates id，id and login value cannot be empty at the same time, one must be filled in
        "loginValue":"Tom"     //login field，id and login value cannot be empty at the same time, one must be filled in
        "fields": [             //candidates' information
            {
                "sFid": 1,      // ield id，int，can be got from the api of field，e.g.:"iphone number"id is 4, Name is 1
                "value":"Tony"  //field，e.g.: if sFid is 1，then it is name
            },
        ]
    },
]

• code: the verification code unique to each account, string type, please contact us to get it.
• stuInfo indicates the candidate information to be updated, sid indicates the candidate ID, loginValue indicates the candidate login field. Fields indicate candidates’ information items.

The return data when modify successfully:

{
    "status": "ok",     //Successfully return:ok, failed to return:error
    "success": [1,2],    //candidates'id or login field successfully added
    "fail": [3,4,5]     //candidates'id or login field fail to be added
}

(3)Interface to delete candidates:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.delStudents&format=raw

Parameter:

code=accesscode
sids=[139, 392, 193, 932] //Candidate's ID list, choose one of id and login value, read the login value first
loginValues=["1000","10001"] //Candidate login value list, string array; choose one of id and login value, read login value first

• code: the verification code unique to each account, string type, please contact us to get it.
• sids represents the ID list of candidates to be deleted

The return data if delete successfully:

{
    "status": "ok",     //Successfully return:ok, failed to return:error
    "success": [1,2],    //candidates'id or login field successfully added
    "fail": [3,4,5]     //candidates'id or login field fail to be added
}

The return data if fail to delete:

{
    "status": "error",     //Successfully return:ok, failed to return:error
    "error": "Invalid sid"    //error means the items fail to delete
}

(4)Interface to move candidates to groups:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.mvStudents&format=raw

Parameter:

code=accesscode
mvStuInfo={
    "gids": [22,33], //If there are multiple fields in gids, it means adding candidates to these groups (PS: one candidate can exist in multiple groups at the same time)    
    "sids": [2213,3910] //Candidate's ID list, choose one of id and login value, read the login value first
    "loginValues":["Tom","Mary"] //Candidate login value, string array; choose one of id and login value, read login value first
    "action": "addto|moveto" //action，addto means to add to the group, one candidate can exist in multiple groups; moveto means to move to the group, one candidate only can exist in one group. If the action is moveto, the gids can only be one, if there are multiple gids, only the first one is selected
}

• code: the verification code unique to each account, string type, please contact us to get it.
• mvStuInfo represents the data information to be moved

The return data if succeed:

{
    "status": "ok",     //Successfully return:ok, failed to return:error
    "success": [1,2],    //candidates'id or login field successfully added
    "fail": [3,4,5]     //candidates'id or login field fail to be added
}

The return data if fail:

{
    "status": "error",     //Successfully return:ok, failed to return:error
    "error": "Invalid sid"    //error means the items fail to move

(5)Interface to get candidates’ information:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.getStudentsInfo&format=raw

Parameter:

code=accesscode
sids=[13212,2382,392]

• code: the verification code unique to each account, string type, please contact us to get it.
• sids represents the ID list of candidates
• can only check the information of up to 10 candidates at a time

The return data if succeed:

{
    "status": "ok",     //Successfully return:ok, failed to return:error
    "data": [
        {
            "sid": 3922, //ID of candidates
            "loginValue":"Tom",//Candidate login field, if loginValues is requested, loginValue is returned
            "fields":[
                {
                    "sFid":1,
                    "label":"name",
                    "value": "Tom"
                },
                {
                    "sFid":13,
                    "label":"one group",
                    "value": "all groups"
                }
            ],
            "group": [
                "gid": 123, //ID of groups
                "title": "group name" //group name
            ]
        },
        {
            "sid": 3925, //ID of candidate
            "loginValue":"Tom",//Candidate login field, if loginValues is requested, loginValue is returned
            "fields":[
                {
                    "sFid":1,
                    "label":"name",
                    "value": "Tom"
                },
                {
                    "sFid":13,
                    "label":"one group",
                    "value": "all groups"
                }
            ],
            "group": [
                "gid": 123, //ID of group
                "title": "group name" //group name
            ]
        }
    ]
}

The return data if fail:

{
    "status": "error",     //Successfully return:ok, failed to return:error
    "error": "Invalid sid"    //error means the items fail to get
}

(6)Interface to get candidate groups’ information:

POST https://onlineexammaker.com/index.php?option=com_exams&task=api.getStudents&format=raw

Parameter:

code=accesscode
start=0
limit=30

• code: the verification code unique to each account, string type, please contact us to get it.
• start is used for paging display when the amount of data is large, indicating the data offset of the paging; defaulting it is 0, optional parameters.
• limit is used for distribution display when the amount of data is large, set the number of data displayed per page; defaulting it is 30, optional parameters.

The return data if succeed:

{
    {
        "sid": "90068", //candidate id
        "fields": [ //information item
            {
                "label": "name",
                "sFid": "1",
                "value": "candidate from api"
            },
            {
                "label": "email",
                "sFid": "3",
                "value": "54457@qq.com"
            },
            {
                "label": "password",
                "sFid": "10",
                "value": "123456"
            }
        ]
    },
    {
        "sid": "90067",
        "fields": [
            {
                "label": "name",
                "sFid": "1",
                "value": "candidate from api"
            },
            {
                "label": "email",
                "sFid": "3",
                "value": "4544@qq.com"
            },
            {
                "label": "password",
                "sFid": "10",
                "value": "123456"
            }
        ]
    }
}

The return data if fail:

{
    "status": "ok",
    "message": "empty"
}

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, that means, he can directly take exams without logging his candidate account again.

Ⅰ. SSO Interface to Exam

The SSO to Exam allows candidates to click the exam entrance directly on the user system to enter the exam, and no additional identity authentication is required.

(1) Request Interface

GET https://www.onlineexammaker.com/index.php?option=com_exams&task=api.newStudentSSO&format=raw

(2) Data Interface

code=accesscode&loginValue=loginfield&password=password&eid=exam ID

• code: the verification code unique to each account, string type, please contact us to get it
• loginValue:the login field for students’ account, if you set mobile phone number as the login account, then here is the mobile phone number
• eid:the id of the exam

Ⅱ．SSO Interface to Candidate Back-end

The principle of SSO to Candidate Back-end is the same as the Exam’s. The difference is the eid. The eid here should be “0”, or don’t put the eid here.

Interface:

GET https://www.onlineexammaker.com/index.php?option=com_exams&task=api.newStudentSSO&format=raw&loginValue=13487361736&password=1294783&eid=0

When the system judges that eid is 0, it will automatically jump to the candidate’s back-end.

Ⅲ．SSO Interface to Sub Admin Back-end

The SSO to Sub Admin allows sub administrator to login their company’s system to enter the Admin back-end.

(1) Request Interface:

GET https://www.onlineexammaker.com/index.php?option=com_exams&task=api.childAdminSSO&format=raw

(2) Data Interface:

code=accesscode&email=emailaddress&password=password

• code: the verification code unique to each account, string type, please contact us to get it
• email:the email address of sub administrator, required
• password:the login password of sub administrator, required

After the sub administrator logs in successfully, the system will automatically jump to Admin Back-end.