Our Business and Enterprise customers can use our public API to integrate TestGorilla into their (homegrown) ATS or HRIS. In this article, we explain how to retrieve assessment and candidate data and how to invite candidates.
Please reach out to us if you plan to use our public API. Our developers can bring you up to speed and assist you in your implementation.
1. API overview
TestGorilla provides 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".
2. Authentication
TestGorilla uses HTTP Token Authentication in each API call. Each API Token expires one hour after the last time it was used. It is, therefore, necessary to retrieve a Token in each session using the login endpoint, as explained below.
The API Token should be used in every API call. It is sent in the Authorization header, as follows:
curl 'https://app.testgorilla.com/api/example/endpoint/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'
2.1 Login
It is necessary to have a username and password to retrieve the API Token using the login endpoint. Since you can have multiple users in your TestGorilla account, we recommend creating a specific user just for the API connections. You can do that in the Account Settings >> Team Management tab in your TestGorilla account. Note that this email address should be validated (by setting a password), so it should be a real email account.
Request:
curl 'https://app.testgorilla.com/api/profiles/login/' \
-H 'content-type: application/json' \
--data-binary '{"username":"USER","password":"PASSWORD"}'
Response:
{"token": "<YOUR TOKEN GOES HERE>"}
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 10 custom questions. Customers typically create one assessment for one open position. Multiple candidates can take the assessment. In TestGorilla, the candidate results are presented in a table.
3.1 Retrieving the list of assessments
Use the GET endpoint to retrieve the list of assessments created in TestGorilla.
Parameters:
|
status |
Filter the assessments based on their status. The possible values are new, active, and archived.
This parameter accepts a comma-separated list. Example: 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. By adding the minus symbol (-), the order will be descending. For example:
Default ordering: 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. For example: Page 1: limit=10&offset=0 Page 2: limit=10&offset=10 Page 3: limit=10&offset=20 Default value: 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": 5,
"finished": 24,
"status": "active",
"modified": "2020-07-10T15:06:05.719971+00:00"
},
{...}
]
}
4. Candidates
Once an assessment has been created, you can invite candidates to take the assessment. Candidates are identified by their ID or by their email address. Candidates can take each assessment only once, but they can take more than one assessment. Candidates can start an assessment by taking one or more tests or custom questions, and come back at a later stage to finish the assessment (as long as the assessment is active). To do so, they can use the same URL as they used to access the assessment the first time around.
4.1 Retrieving a list of candidates
Use the GET endpoint to retrieve the list of candidates within an assessment.
Parameters:
|
assessment |
The assessment ID from which you retrieve the participating candidates. |
|
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. For example:
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. For example: Page 1: limit=10&offset=0 Page 2: limit=10&offset=10 Page 3: limit=10&offset=20 Default value: 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: "2020-04-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: "3-3-1-1-1_30-32-28-19-28",
rating: null
review: null
stage: "HIR"
status: "completed"
testtaker_id: 4276
},
{...}
]
}
4.2 Inviting a candidate
By inviting a candidate, TestGorilla will send an invitation email to the candidate to allow them to take the assessment. You can invite candidates in two ways: with a public link or individually, by providing their email address, and, optionally, their first and last name.
4.2.1 Retrieving the public link of an assessment
Request:
curl 'https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'
Response:
{
...
public_links: [
{
active: true,
candidates_count: 0,
candidates_limit: 0,
id: 32,
label: "Main",
public_uuid: "36d655fd-9f5e-4cc8-8ed6-ded0714752bb"
}
],
...
}
You can build the public link as follows:
https://www.testgorilla.com/testtaker/publicinvitation/<PUBLIC_UUID>
4.2.2 Activating/deactivating the public link
Request:
curl 'https://www.testgorilla.com/api/assessments/public_links/<PUBLIC LINK ID>/' \
-X 'PUT' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>' \
-H 'content-type: application/json' \
--data-binary '{"active":false, "label":"Main", "assessment":<ASSESSMENT_ID>}'
Set the active parameter true or false to activate or deactivate the link, respectively.
4.2.3 Inviting a candidate using their email address
You can send the email, first name, and last name in the request. The only required parameter is the email.
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":32,
"email":"john@example.com",
"first_name":"John",
"last_name":"Smith",
"invitation_uuid":"d1bb9864-0515-4543-9bac-f26af0b13895",
"created":"2020-09-29T07:55:14.517886+00:00",
"testtaker_id":4276,
"status":"invited"
}
In order to retrieve information about this candidate in the future, we recommend saving the id value and the testtaker_id value.
4.3 Retrieving candidate results
This endpoint provides all the information about a candidate, across all assessments taken historically by that candidate. To manage our server load across our customer base, we allow candidate result requests to be executed once every 6 hours.
Request:
curl 'https://app.testgorilla.com/api/assessments/candidates/<TESTTAKER_ID>/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'
Response:
{
"id":4276,
"first_name":"John",
"last_name":"Smith",
"email":"john@example.com",
"assessments_detail": [
{
"id":8000,
"assessment_name":"Python developer",
"assessment_id":32,
"invited":"2020-09-29T07:55:14.517886+00:00",
"status":"completed",
"results": [
{
"id":65,
"name":"Python modelling test",
"score":"80",
"completed":true,
"is_code_test":false,
"score_display":"",
"score_description":""
},
{...}
],
"average":70,
"test_taker_photos":[{image:"https://..."}, {image:"https://..."}, ...],
"is_exited_full_screen":false,
"is_left_screen":false,
"modified":"2020-09-29T07:55:14.518277+00:00",
"personality_results":[
{
completed: true
id: 59
name: "Big5 Personality Test"
score_description: "Long text..."
score_display: "3-3-1-1-1_30-32-28-19-28"
}
],
"custom_results":[
{
custom_questions: [
{
question: {
text: "The video question itself, e.g. Why do you want to work for us?"
type: "video"
},
resources: [
{
file: "URL TO DOWNLOAD THE VIDEO"
type: "video"
}
],
review: {
comment: "Your comments",
score: 5
}
},
{
question: {
answers: [
{text: "Answer option 1"}
{text: "Answer option 2"}
{text: "Answer option 3"}
{text: "Answer option 4"}
],
text: "The multiple-choice question",
type: "multiple-choice"
},
answers: [{text: "Answer option 3"}],
review: {
comment: "Some comments",
score: 5
}
}
],
review: {
comment: "Some comments",
score: 5,
}
}
],
"ip":null,
"repeated_ip":false,
"geoip":{},
"user_agent":{}
},
{...}
]
}
With the aforementioned 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.
If you have additional requirements regarding your integration, please reach out to us.