TestGorilla's API documentation

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

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

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

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

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

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 (see Section 3.2) 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.

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

4.3 Inviting a candidate using their email address

You can also invite a candidate using their email address and, optionally, their first and last name as the body of the endpoint POST https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/ in the request.

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.

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

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

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

}

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

curl --location --request DELETE 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/' \
--header 'Authorization: Token <YOUR TOKEN GOES HERE>'

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

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.