Our Business customers can use our public API to integrate TestGorilla into their homegrown ATS or HRIS.
The TestGorilla API allows you to connect your TestGorilla account with another ATS or HRIS tool. It can retrieve assessments, invite candidates, and get test results through an HTTP-based API following the principles of REST. The HTTP protocol rules are followed, enabling the use of simple HTTP client tools like curl. The API is available to account owners on the Business plan.
In this article
6. Test results
TestGorilla API versions
The latest TestGorilla API version is v1.3:
|
Version |
Date Introduced | Available Until |
| v1.3 | August 18, 2022 | No specified date |
| v1.2 | February 19, 2022 | August 17, 2022 |
| v1.1 | November 10, 2021 | February 18, 2022 |
| v1.0 | September 23, 2021 | November 9, 2021 |
| v0.9 | April 27, 2021 | September 22, 2021 |
| v0.8 | Jan 01, 2021 | April 26, 2021 |
2. Authentication
Please reach out to our customer success team for instructions regarding authentication.
3. Assessments
At TestGorilla we distinguish assessments from tests. A candidate takes an assessment, which can consist of up to 5 tests and up to 20 custom questions, depending on your plan.
Customers typically create one assessment for one open position and multiple candidates take the same assessment.
List of assessments
Use the following endpoint to retrieve the list of assessments created in TestGorilla:
GET https://app.testgorilla.com/api/assessments/
Query parameters
status |
Filter the assessments based on their status. The possible values are new, active, and archived.
Example status=new,active Default value: retrieves all the statuses |
||||||||
ordering |
Defines the order of the result list. The possible values are:
This parameter supports ascending and descending order. The default ordering ascending and adding the minus symbol (-), the order will be descending. Example ordering=modified newest on the bottom ordering=-modified newest on the top Default order ing: Order by assessment ID |
||||||||
limit |
The number of records to retrieve. This parameter is used for pagination purposes, defining the size of the page. Default value : 10 |
||||||||
offset |
The offset of the first element. This parameter is used for pagination purposes. Example limit=10&offset=0 1st page of 10 items limit=10&offset=10 2nd page of 10 items Default value : limit=10 and offset=0 |
Request
curl 'https://app.testgorilla.com/api/assessments/?status=active,new' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
{
"count": 27,
"results": [
{
"id": 32,
"name": "Python developer",
"candidates": 42,
"invited": 13,
"started": 8,
"finished": 21,
"status": "active",
"finished_percentage": 50,
"modified": "2021-07-10T15:06:05.719971+00:00"
},
{...}
]
}
Assessment details
Use the following endpoint to retrieve the details for a specific assessment:
GET https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>
Request
curl 'https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'
Response
{
"id": 32,
"modified": "2021-07-10T15:06:05.719971+00:00"
"name": "Python developer",
"candidates": 42,
"invited": 13,
"started": 8,
"finished": 21,
"status": "active",
"finished_percentage": 50,
"benchmark_name": "All candidates",
...
"public_links": [
{
id: 32,
active: true,
candidates_count: 0,
candidates_limit: 0,
label: "General public link",
public_uuid: "<PUBLIC_LINK_UUID>"
}
],
...
}
Retrieving the anti-cheating flags for an assessment
Follow retrieve candidate details to get the <TEST_TAKER_ID> and <CANDIDATURE_ID> of the candidate you'd like the results retrieved for:
curl --location --request GET 'https://app.testgorilla.com/api/assessments/candidates/<TEST_TAKER_ID>/?candidature=<CANDIDATURE_ID>' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
The response includes all candidatures associated to the TEST_TAKER_ID. The following fields correspond to the anti-cheating flags:
- is_exited_full_screen: True if the candidate left the assessment screen, False otherwise.
- is_left_screen: True if the mouse left the assessment screen, False otherwise.
- repeated_ip: True if more than one assessment was completed from the same IP address, False otherwise.
- is_camera_enabled: True if the camera is enabled during the assessment, False otherwise.
{
"id": <TEST_TAKER_ID>,
...
"assessments_detail": [
{
...
"is_exited_full_screen": false,
"is_left_screen": false,
"repeated_ip": true,
"is_camera_enabled": false,
...
}
]
}
Inviting a candidate
Once an assessment has been created, you can invite candidates to take it. Each candidate is identified by a unique test taker ID or by their email address. Candidates can take more than one assessment, but can only take each assessment once.
There are two ways to invite candidates to take assessments:
- Using a public link
- Individually, with an email address and an optional first and last name
| Tip: Candidates can start taking one or more tests or custom questions, abandon the assessment, and come back later to finish it. They do this using the same URL as they used to access the assessment the first time. This is only possible if the assessment is still active. |
Creating a public link for an assessment
You can create a public link to invite candidates using the following URL template .
https://app.testgorilla.com/testtaker/publicinvitation/<PUBLIC_LINK_UUID>
To get the public_uuid for a specific assessment, you need to call the assessment detail endpoint and pick the corresponding UUID. For example, you can use the default public link by pulling the first item from the public_links attribute to create the public link using public_links[0].public_uuid.
Activating/deactivating a public link
You can activate or deactivate a public link using the endpoint PUT https://app.testgorilla.com/api/assessments/public_links/<PUBLIC_LINK_ID> and assigning true or false to the active attribute. Once the link is deactivated, the assessment will not be accessible using the URL.
Request
curl 'https://app.testgorilla.com/api/assessments/public_links/<PUBLIC_LINK_UUID>/' \
-X 'PUT' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>' \
-H 'content-type: application/json' \
--data-binary '{"active":false, "label":"Main", "assessment":<ASSESSMENT_ID>}'
Inviting a candidate using their email address
You can also invite a candidate using their email address and first and last name as the body in the following endpoint request.
POST https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/
| Note: Though recommended, first and last name is optional. |
Request
curl 'https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/' \
-H 'content-type: application/json' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>' \
--data-binary '{"email":"john@example.com","first_name":"John","last_name":"Smith"}'
Response
{
"id":8000,
"assessment":99,
"email":"john@example.com",
"first_name":"John",
"last_name":"Smith",
"invitation_uuid":"d1bb9864-0515-4543-9bac-f26af0b13895",
"created":"2021-09-29T07:55:14.517886+00:00",
"testtaker_id":9999,
"status":"invited"
}
In order to retrieve information about this candidate later, we recommend saving the testtaker_id value.
Retrieving the personalized candidate URL to take the assessment without sending an invitation email to the candidate
If you integrate TestGorilla into your own application and you want to allow your users to take an assessment without the invitation email as a necessary step to start the assessment, you need to fetch the personalized URL for the candidate to take the assessment. This involves two steps.
The first step is to invite the candidate and suppress the invitation email. You can do that by including the no_email parameter to the request to invite a candidate. If you send this parameter as true, the invitation email won't be sent. Save the testtaker_id value from the response below.
Request
curl 'https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/?no_email=true' \
-H 'content-type: application/json' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>' \
--data-binary '{"email":"john@example.com","first_name":"John","last_name":"Smith"}'
Response
{
"id":8000,
"assessment":32,
"email":"john@example.com",
"first_name":"John",
"last_name":"Smith",
...
"testtaker_id":9999,
"status":"invited"
}
The second step is to use the request in Section 5.1 to retrieve the details from all candidates in this assessment, using the assessment_id. Using the testtaker_id of the candidate given in step 1, you can then find the invitation link.
Re-inviting a candidate using their candidature ID
You can resend an invitation to candidates using the candidature ID ( id ). This ID was created when the candidate was first invited (see section 4.3). Alternatively, you can use the endpoint to list all candidates as described in section 5.1 to obtain the id.
Request
curl --location --request POST 'https://app.testgorilla.com/api/assessments/candidature/<ID>/send-invitation/' \
--header 'authorization: Token <YOUR TOKEN GOES HERE>' \
--header 'content-type: application/json' \
--data-raw '{}'
5. Candidates
List of candidates invited to an assessment
Use the following endpoint to retrieve the list of candidates invited to an assessment.
GET https://app.testgorilla.com/api/assessments/candidature?assessment=<ASSESSMENT_ID>
Query Parameters
assessment |
The assessment ID from which you retrieve the participating candidates. This field is required. |
||||||||||||||||||||
status |
Filter the assessments based on their status. The possible values are:
Default value: retrieves all the statuses |
||||||||||||||||||||
ordering |
Defines the order of the result list. The possible values are:
This parameter supports ascending and descending order. The default ordering ascending. By adding the minus symbol (-), the order will be descending. Example ordering=created newest item on the bottom ordering=-created newest item on the top Default ordering: by candidate ID |
||||||||||||||||||||
stage |
Filters the list of candidates based on their stage in the hiring process. The possible values are:
Default value: retrieves all the stages |
||||||||||||||||||||
limit |
The number of records to retrieve. This parameter is used for pagination purposes, defining the size of the page. Default value: 10 |
||||||||||||||||||||
offset |
The offset of the first element. This parameter is used for pagination purposes. Example limit=10&offset=0 1st page of 10 items limit=10&offset=10 2nd page of 10 items Default value : limit=10 and offset=0 |
Request
curl 'https://app.testgorilla.com/api/assessments/candidature/?assessment=<ASSESSMENT_ID>' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
"results": [
{
avg_score: 76,
created: "2021-09-18T09:16:33.975663+02:00",
email: "john@example.com",
full_name: "John Smith",
id: 8000,
invitation_uuid: "edb70e44-271d-4e6a-8533-901fdc95f230",
is_hired: false,
personality_algorithm: 'big_5',
personality: "3-3-1-1-1_30-32-28-19-28",
rating: null
review: null
stage: "HIR"
status: "completed"
testtaker_id: 4276,
invitation_link: "https://assessment.testgorilla.com/testtaker/takeinvitation/edb70e44-271d-4e6a-8533-901fdc95f230",
},
{...}
]
}
| Note: For assessments with more than one personality test, both the personality_ algorithm and personality attribute values are pulled from the first personality tests associated with that assessment. |
Retrieving candidate details
This endpoint provides candidate information such as their full name, email address, the list of assessments the candidate has been invited to, and a consolidated list of tests taken.
| Caution: Up to v0.8 of the API, this endpoint returned all of the results across all assessments taken historically by a specific candidate. In order to improve result information, all result information was moved to the results API endpoint. |
Request
curl 'https://app.testgorilla.com/api/assessments/candidates/<TESTTAKER_ID>/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'
Response
{
"count": 20,
"next": "https://app.testgorilla.com/api/assessments/candidates/?limit=10&offset=10",
"previous": null,
"results": [
{
"id": 321321,
"full_name": "John, Doe",
"email": "johndoe@email.com",
"tests": [
# Grouped list of tests
],
"assessments": [
# List of assessments taken by the candidate
{ "assessment_name": "An assessment" }
...
],
"assessments_count": 1,
"last_activity": "2021-02-23T00:12:40.717337+01:00",
...
},
...
]
}
Deleting a candidate from an assessment
This endpoint will allow you to remove a candidate from an assessment. This may be necessary, for example, if you want to invite the candidate to take the assessment a second time.
curl --location --request DELETE 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Set a candidature stage as REJECTED
Follow retrieve candidate details to get the <CANDIDATURE_ID> of the assessment you’d like to set as REJECTED:
Request
curl --location --request PATCH 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/change_stage/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>' \
--header 'Content-Type: text/plain' \
--data-raw '{ stage: "REJ" }'
Response
The response includes the submitted parameters:
{
"id": <CANDIDATURE_ID>,
"stage": "REJ",
"reminder_sent": false
}
Trigger a rejection email for a candidate
Follow the candidates section to get the <CANDIDATURE_ID> for the candidate you’d like the email triggered.
Make sure the candidature is in REJECTED status when triggering this email. See sections 5.1 and 6.7 for more details.
Request
curl --location --request POST 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/send-reminder/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
curl --location --request POST 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/send-reminder/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
6. Test Results
Retrieving assessment results
A detailed version of each candidate’s test results for a specific assessment can be pulled using the following API endpoint
GET https://app.testgorilla.com/api/assessments/results/?candidature__assessment=<ASSESSMENT_ID>&candidature__test_taker=<TESTTAKER_ID>
Query Parameters
candidature__assessment |
Required | Assessment ID |
candidature_test_taker |
Required | Test taker ID |
Request
curl --location --request GET 'https://app.testgorilla.com/api/assessments/results/?candidature__assessment=<ASSESSMENT_ID>&candidature__test_taker=<TEST_TAKER_ID>' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
{
"count": n,
"results": [
{
"id": 123456,
"name": "Big 5 (OCEAN)",
"score": null,
"status": "published",
"completed": true,
"test_id": 494,
"custom_questions": [],
"algorithm": "big_5",
"is_code_test": false,
"score_display": "2-1-1-2-1_32.0-34.0-33.0-35.0-32.0",
...
},
{
"id": 234567,
"name": "Problem solving",
"score": 85,
"status": "filed",
"completed": true,
"test_id": 7244,
"custom_questions": [],
"algorithm": "basic",
"is_code_test": false,
"score_display": "",
...
},
{...}
]
}
Retrieving assessment results in PDF
Get the list of candidates for an assessment and use the response data and following mapping table to fill the data in Request below to get the results:
testtaker_id |
TEST_TAKER_ID |
id |
CANDIDATURE_ID |
Request
curl --location --request GET 'https://app.testgorilla.com/api/assessments/candidates/<TEST_TAKER_ID>/render_pdf/?candidature=<CANDIDATURE_ID>' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>'
Result types
Test result formats and representations are tied to the algorithm that is used to calculate it. The table below lists the algorithms, the attributes used, and how to analyze those results.
|
Name |
Algorithm |
Result Attr. |
Test Details |
|---|---|---|---|
|
Basic |
basic |
score |
Guide to analyzing results |
|
Custom questions |
custom_questions |
score |
|
|
Personality |
enneagram disc 16_types big_5 |
score_display |
|
|
Culture add |
culture_fit |
score_display |
Using the culture add test |
Basic Tests
Basic tests are those where the algorithm attribute equals basic. The score for these tests is returned in the score attribute.
Custom Questions
Custom questions are represented by an extra test and the results are those where the algorithm attribute equals custom_questions . The score for these tests is returned in the score attribute.
Personality Tests
Big 5 (OCEAN)
The Big 5 personality test results are those where the algorithm attribute equals big_5. For this test, the score_display attribute provides two different representations of the test result, in an encoded string that contains two sections, separated by "_", with five values each:
-
Section 1: The calibrated score, from 1 (Very Low ) to 5 (Very High ) separated by “-“
-
Section 2: The original (unprocessed) score, in decimal values separated by “-“
Those five values correspond to the five factors in the following order:
- Extroversion
- Agreeableness
- Conscientiousness
- Emotional stability
- Openness to experience
You can pick the section you are interested in, splitting the string by '_' (underscore). You can then get each individual result by splitting the string again by '-' (dash).
Example: 2-1-1-2-1_30.0-29.0-33.0-26.0-31.0
- Section 1: 2-1-1-2-1
- Section 2: 30.0-29.0-33.0-26.0-31.0
Within TestGorilla, the result look like the image below:
Enneagram
The Enneagram personality test results are those where the algorithm attribute equals enneagram. For this test, the score_display attribute has one of the following values:
- No results
- Improver
- Giver
- Go-getter
- Contemplator
- Pioneer
- The Devoted
- Cheerleader
- Master
- Agreeable
The only value that does not have a description is No results and will result in an HTTP 404 response if looked up using the description endpoint.
DISC
The DISC personality test results are those where the algorithm attribute equals disc. For this test, the score_display attribute has one of the following values:
| d | i | s | c |
| di | is | sc | cd |
| id | si | cs | dc |
16 types
The 16 types personality test results are those where the algorithm attribute equals 16_types. For this test, the score_display attribute represents the dominant letters across 4 scales: E-I, S-N, T-F, and J-P. As a result, the possible values are:
| ESTJ | ENTJ | ISTJ | INTJ |
| ESTP | ENTP | ISTP | INTP |
| ESFJ | ENFJ | ISFJ | INFJ |
| ESFP | ENFP | ISFP | INFP |
Personality Description Endpoint
If you need a mechanism to dynamically pull a personality report, you can use the personality description endpoint, specifying the algorithm and the corresponding value to get detailed information about what each specific score means.
GET https://app.testgorilla.com/api/tests/personality/<ALGORITHM>/<SCORE>
Request
curl --location --request GET 'https://app.testgorilla.com/api/tests/personality/<ALGORITHM>/<SCORE>' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
{
"personality":"..."
}
For example, if you want to get the details for INTJ - The Intellectual for 16 Types tests, you must send the algorithm 16_types and the score value uses INTJ in the URL.
curl --location --request GET 'https://app.testgorilla.com/api/tests/personality/16_types/INTJ' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
And you will get a response like ...
{
"personality":"<h2>INTJ – The Intellectual</h2>\n \n <h3>Description</h3>\n
<p>INTJs are systematic, analytical, and intuitive thinkers. This
is a rare combination, making it one of the least common personality
... "
}
Coding tests
Retrieving the time used on a coding test
Follow retrieving assessment details to get the <TEST_RESULT_ID> for the coding test to query:
Request
curl --location --request GET 'https://app.testgorilla.com/api/assessments/results/<TEST_RESULT_ID>/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
The response includes the total time allowed (duration) and the time used by the candidate (response_time), both in seconds.
{
"skill_areas_score":[],
"duration":1800.0,
"response_time":739
}
Retrieving the URL to a coding test report
Retrieve assessment details to get the <TEST_RESULT_ID> for the coding test to query:
Request
curl --location --request GET 'https://app.testgorilla.com/api/assessments/code_questions/<TEST_RESULT_ID>/invitation_token/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'
Response
The response includes the code report UUID.
{"invitation_uuid":"<CODE_REPORT_UUID>"}
The report link is formatted as https://app.testgorilla.com/customer/candidates/code-report/<CODE_REPORT_UUID>
| Note: With the above functionalities, you have the ability to manage your candidates inside your own system. To create assessments and write custom questions, you do need to access TestGorilla directly. |