In the article below you will find important information about the usage of the Testinvite’s API for fetching test results according to ticket ids. We will firstly explain structure and types of the request body, and then show some examples of calls in Postman and in different programming languages. Lastly we will describe the structure of the response body.
If you want to try API requests immediately you can check the Postman collection we have created for you. Please click here to download the Postman collection.
There are 4 required properties for fetching test results related with a ticket: "requester", "taskId", "kind", and "tickets". Requester is an object containing properties related with authentication. Mainly you should include your organization's id and organization's private key in "auth" property of requester. "taskId" is the id of the task whose results going to be fetched. "kind" is used to mention according to what you want to query test results. For now our system has a query for test test results only according to ticket id so, it should be "by-ticket". Lastly, "tickets" is an array of objects where each array takes one property: "ticketId". You can find ids of tickets in the response of the ticket creation.
You can find request body's types in chart below representing body in tree view.
In the examples below, you can see 2 different fetch requests. The example on the left is created in POSTMAN, and the right one is created according to cURL. You can use these examples simply by using your organization's id, private key, and taskId. To fetch your candidates' test results you should employ ticket ids that you gor from ticket creation request's response.
Code examples below contain only required properties and are created for one ticket. You can see one object with "ticketId" property in the "tickets" array.
Example body
{
"requester": {
"name": "Organization Name",
"auth": {
"organizationId": "zUH8oMYJ60As4HYP",
"privateKey": "a8faef00-43c1-11ed-81bc-976010"
}
},
"taskId": "tcxHArKva33C8VxCZcjy",
"kind": "by-ticket",
"tickets": [
{
"ticketId": "33C8VxCZcjytcxHAr"
}
]
}
cURL
curl --location --request POST
'https://www.testinvite.com/api/v1/fatih/query-test-results' \
--header 'Content-Type: application/json' \
--data-raw '{
"requester": {
"name": "Organization Name",
"auth": {
"organizationId": "zUH8oMYJ60As4HYP48Zx",
"privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c0d"
}
},
"taskId": "Qj33evNTg7IjLnao2Ux1",
"kind": "by-ticket",
"tickets": [
{
"ticketId": "0dxZm5WJ42cbxCP6DQbn"
}
]
}'
Requests below have two ticket ids in the tickets array which means that response will include multiple results in its "payload" array.
Example body
{
"requester": {
"name": "Organization Name",
"auth": {
"organizationId": "zUH8oMYJ60As4HYP48Zx",
"privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c"
}
},
"taskId": "Qj33evNTg7IjLnao2Ux1",
"kind": "by-ticket",
"tickets": [
{
"ticketId": "0dxZm5WJ42cbxCP6DQbn"
},
{
"ticketId": "xCP6DQbn0dxZm5WJ42cb"
}
]
}
cURL
curl --location --request POST
'https://www.testinvite.com/api/v1/fatih/query-test-results' \
--header 'Content-Type: application/json' \
--data-raw '{
"requester": {
"name": "Organization Name",
"auth": {
"organizationId": "zUH8oMYJ60As4HYP48Zx",
"privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c0d"
}
},
"taskId": "Qj33evNTg7IjLnao2Ux1",
"kind": "by-ticket",
"tickets": [
{
"ticketId": "0dxZm5WJ42cbxCP6DQbn"
},
{
"ticketId": "ggHtHoz0LbATu5C2VGGn"
}
]
}'
Response body mainly consists of two parts: "kind" and "payload". Kind property takes value according to the response status. If there is no error it should be "zetok", if there is, it will be "zeterror". As it contains all data about test results, payload array is the essential part of the response body. It is an array consisted of object/s where all the test result data is restored. In every object you should see different properties such as "ticketId", "testReference", "meta", and "testInstanceId" etc. We will explain here only important properties for test scores and further api calls.
The most important properties in payload are: "result", "testInstanceId", and "ticket". Test instance id is a string that is going to be used in fetching monitoring assets of the exam. So, if you have opened monitoring options for the task you should save this id in order to make api call for fetching monitoring assets. Result is an object, consisting of properties containing result data of the exam. Essential properties of result object are: "dimensions", "stats", and "sections". Dimensions property is important if you have included dimensions in the system for questions. "stats" is an object where general results of the exam are included. You can find in it candidate's wrong and right answers, total point that could be gained from the exam etc. "point" and "totalPoint" show the candidate's points and total points that could be gained from the exam respectively. "sections" is an array of objects where section-based data of results is contained. The structure of each object in the array is similar to "result" object where in them only section-based data is restored.
Response body will be as the tree view below. Instead of giving all types in the body we will mention only important ones in test results.
You can see one response example below for fetching one ticket's results. After having this response, it is recommended that you should save "testInstanceId", "point" and "totalPoints" in the stats property of result object for further process.
Response for Fetching one Ticket's Results
{
"kind": "zetok",
"payload": [
{
"ticketId": "0dxZm5WJ42cbxCP6DQbn",
"apiTaskTicketRequestId": "ryakw32wZAGcZdo14NCi",
"external": {
"id": null,
"data": null
},
"testReference": {
"kind": "testreference",
"title": "API Test1",
"organizationId": "zUH8oMYJ60As4HYP48Zx",
"testId": "ocMYFZc41A5SLflug5GE"
},
"meta": {
"folder": "general",
"group": "general",
"labels": [],
"tagLines": [
"requester",
"requester_*/|-?*_Yusuf's Company"
],
"tagMap": {
"requester": "Yusuf's Company"
}
},
"result": {
"sections": [
{
"sectionInstanceUUID": "bf8464a0-43c0-11",
"stats": {
"noOfMatchQuestion": 0,
"noOfAnswered": 5,
"noOf100": 5,
"noOfInvalid": 0,
"noOfMultipleChoiceQuestion": 5,
"noOfIneffective": 0,
"noOfEvaluated": 0,
"noOfPartial": 0,
"noOfEmpty": 0,
"noOfInputQuestion": 0,
"totalPoint": 5,
"noOfIgnored": 0,
"noOfNotAnswered": 0,
"noOfManual": 0,
"point": 5,
"noOf0": 0,
"noOfQuestions": 5,
"noOfMissingEvaluation": 0,
"noOfNegative": 0,
"negative": 0,
"noOfPointy": 5,
"noOfRequireEvaluation": 0
},
.
.
.
"sectionIndex": 0
}
],
"dimensions": {},
"stats": {
"noOfNegative": 0,
"totalPoint": 5,
"noOfNotAnswered": 0,
"noOf100": 5,
"noOfPointy": 5,
"noOfMultipleChoiceQuestion": 5,
"noOfEvaluated": 0,
"noOfAnswered": 5,
"noOfEmpty": 0,
"noOfMatchQuestion": 0,
"noOfIneffective": 0,
"noOfPartial": 0,
"point": 5,
"noOfManual": 0,
"noOf0": 0,
"noOfQuestions": 5,
"noOfIgnored": 0,
"noOfRequireEvaluation": 0,
"noOfMissingEvaluation": 0,
"noOfInputQuestion": 0,
"negative": 0,
"noOfInvalid": 0
},
},
.
.
.
},
]
}