TestGorilla's API documentation

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

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

TestGorilla uses HTTP Token Authentication in each API call. Each API Token expires one hour after the last time it was used. Therefore, it is 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 add a user in the Account settings >> Team management tab in your TestGorilla account.

Note that this email address needs to be validated (through a validation email from us), so it must be a real email address.

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

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

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

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

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":"General public link", "assessment":<ASSESSMENT_ID>}'

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

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

5. Candidates

5.1 List of candidates invited to an assessment

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

Query Parameters

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

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

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

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.

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.