TestGorilla's API documentation

Our Business and Enterprise customers can use our public API to integrate TestGorilla into their homegrown ATS or HRIS.

TestGorilla API versions

The latest TestGorilla API version is v1.0:

Version

Date Introduced Available Until
v1.0 September 23, 2021 No specified end date
v0.9 April 27, 2021 September 22, 2021
v0.8 Jan 01, 2021 April 26, 2021


1. API overview

In this article, we explain how to retrieve assessments, invite candidates, and get test results.

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

Please reach out to our support 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.

3.1. List of assessments

Use the GET https://app.testgorilla.com/api/assessments/ endpoint to retrieve the list of assessments created in TestGorilla.

Parameters

status

Optional

Filter the assessments based on their status. The possible values are newactive, and archived

  • new: Assessments to which no candidates have been invited.

  • active: Assessment to which at least one candidate has been invited, irrespective of their completion status.

  • archived: Assessments to which candidates can no longer take. Candidates that were invited before archiving can no longer complete the assessment

This parameter accepts a comma-separated list

Examplestatus=new,active

Default value: retrieves all the statuses

ordering

Optional

Defines the order of the result list. The possible values are: 

  • modified: date of last modification (this includes any progress of candidates participating in the assessments)

  • name: name of the assessment

  • candidates: number of candidates invited

  • finished_percentage:  percentage of candidates started or completed

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 top)

Default ordering: Order by assessment ID

limit

Optional

The number of records to retrieve. This parameter is used for pagination purposes, defining the size of the page.

Default value: 10

offset

Optional

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": "2020-07-10T15:06:05.719971+00:00"
    },
    {...}
  ]
}

3.2. Assessment detail

Use the GET https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID> endpoint to retrieve the details for a specific assessment.

Request

curl 'https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>'

Response

 {
    "id": 32,
    "modified": "2020-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>"
    }
  ],
  ...
}

4. Inviting candidates

Once an assessment has been created, you can invite candidates to take it.

Each candidate is identified by a unique ID or by their email address. They 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

Note: Candidates can start taking one or more tests or custom questions, abandon the assessment, and can come back later to finish it.

They do this using the same URL they used to access the assessment the first time. This is only possible if the assessment is still active.

4.1 Inviting candidates using an assessment's public link

Each assessment is identified by the public_uuid  attribute returned in the assessment detail endpoint (Section 3.2) response.

A public link can be created by replacing the public_uuid value in the following URL template.

https://app.testgorilla.com/testtaker/publicinvitation/<PUBLIC_LINK_UUID>

For example, for an assessment with public_uuid="d799f88f-...-ad9e04435b92"  the public link would be:

https://app.testgorilla.com/testtaker/publicinvitation/d799f88f-...-ad9e04435b92 

4.2 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_ID>/' \ 
-X 'PUT' \
-H 'authorization: Token <YOUR TOKEN GOES HERE>' \
-H 'content-type: application/json' \
--data-binary '{"active" : false, "label":"General public link", "assessment":<ASSESSMENT_ID>}'

4.3 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 of the endpoint POST https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/ in the request. The only required parameter is the email. Both first and last names are 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":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 testtaker_id value.

4.4 Inviting a candidate using their candidature ID

You can also invite candidates using their candidature ID, which can be obtained using the list of candidate endpoints (please see next section).

Request

curl --location --request POST 'https://app.testgorilla.com/api/assessments/candidature/675368/send-invitation/' \
--header 'authorization: Token <YOUR TOKEN GOES HERE>' \
--header 'content-type: application/json' \
--data-raw '{}'


When using POST https://app.testgorilla.com/api/assessments/candidature/675368/send-invitation/ you can include the no_email parameter. If you send this parameter as true, the invitation email won't be sent.

Request

curl --location --request POST 'https://app.testgorilla.com/api/assessments/candidature/675368/send-invitation/?no_email=true' \
--header 'authorization: Token <YOUR TOKEN GOES HERE>' \
--header 'content-type: application/json' \
--data-raw '{}'

 

5. Candidates

5.1 List of candidates invited to an assessment

Use the GET https://app.testgorilla.com/api/assessments/candidature?assessment=<ASSESSMENT_ID> endpoint to retrieve the list of candidates invited to an assessment.

Query Parameters

assessment

Required

The assessment ID from which you retrieve the participating candidates.

status

Optional

Filter the assessments based on their status. The possible values are:

  • invited

  • started

  • completed

Default value: retrieves all the statuses

ordering

Optional

Defines the order of the result list. The possible values are: 

  • created: Date of invitation

  • _full_name: Name of the candidate

  • avg_score: Average score

  • rating: Your custom (5-star) rating of the candidate

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 on the bottom) 
  • ordering=-created (newest on top)

Default ordering: by candidate ID

stage

Optional

Filters the list of candidates based on their stage in the hiring process. The possible values are:

  • NYE: Not evaluated yet

  • EVA: Evaluated

  • IFI: Invited for interview

  • INT: Interviewed

  • IFT: Invited for a take-home test

  • TTC: Take-home test completed

  • REF: References checked

  • OFS: Offer sent

  • HIR: Hired

  • REJ: Rejected

Default value: retrieves all the stages

limit

Optional

The number of records to retrieve. This parameter is used for pagination purposes, defining the size of the page.

Default value: 10

offset

Optional

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: "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_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,
    }, 
    {...}
 ]
}

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.

5.2 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 (Section 6.1).
 

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 Customer
{ "assessment_name": "An assessment" }
...
],
"assessments_count": 1,
"last_activity": "2021-02-23T00:12:40.717337+01:00",
...
},
...
]
}

6. Test Results

6.1. Retrieving assessment results

A detailed version of each candidate’s test results for a specific assessment can be pulled using the API endpoint GET https://app.testgorilla.com/api/assessments/results/?candidature__assessment=<ASSESSMENT_ID>&candidature__test_taker=<TESTAKER_ID>

Query Parameters

candidature__assessment

Required

Assessment ID

candidature__test_taker

Required

Candidate ID

limit

Optional

The number of records to retrieve. This parameter is used for pagination purposes, defining the size of the page.

Default value: 10

offset

Optional

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 --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": 165238,
"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": 165276,
"name": "Problem solving",
"score": 85,
"status": "filed",
"completed": true,
"test_id": 7244,
"custom_questions": [],
"algorithm": "basic",
"is_code_test": false,
"score_display": "",
...
},
    {...}
  ]
}

6.2. 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

What question type should I use?

How can I see how candidates scored on a test?

Custom Questions

custom_questions

score

Why should I rate custom questions?

Personality

enneagram

disc

16_types

big_5

score_display

Test library: Personality & culture tests

Culture Add

culture_fit

score_display

How does the culture add test work?

6.2.1 Basic Tests

Basic tests are those where the algorithm attribute equals basic. The score for these tests is returned in the score attribute.

6.2.2 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.

6.2.3 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:

  1. Extroversion

  2. Agreeableness

  3. Conscientiousness

  4. Emotional stability

  5. Openness to experience

You can pick the section you are interested in, splitting the string by '_' (underscore). You can then get each individual result 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 looks as follows:


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 Contemplator Cheerleader
Improver Pioneer Master
Giver The Devoted Agreeable
Go-getter    

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

6.2.4 Personality Description Endpoint

If you need a mechanism to dynamically pull a personality report, you can use the personality description endpoint GET https://app.testgorilla.com/api/tests/personality/<ALGORITHM>/<SCORE> specifying the algorithm and the corresponding value to get detailed information about what each specific score means.

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
... "
}

 



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.

Support
If you still need help, you can always reach out to the support team. We're happy to answer your questions.