TestGorilla's API documentation

Updated July 19, 2024 14:28

Our Pro 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 Pro plan with 100+ FTEs.

Approx. reading time 11 minutes

Available integrations

TestGorilla supports integration with the following ATS systems:

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

Authentication

Please reach out to our customer success team for instructions regarding authentication.

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.

new	assessment to which no candidates have been invited
active	assessments to which at least one candidate has been invited, irrespective of their completion status
archived	assessment 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.

Example

status=new,active

Default value: retrieves all the statuses

ordering

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

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

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:

invited	the candidate has been invited to the assessment but has not yet started
started	the candidate has started the assessment but has not completed it
completed	the candidate has completed the assessment fully

Default value: retrieves all the statuses

ordering

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

NYE	Not yet evaluated
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

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

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	Using custom questions
Personality	enneagram disc 16_types big_5	score_display	Interpreting personality tests
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 can manage your candidates inside your own system. To create assessments and write custom questions, you do need to access TestGorilla directly.

TestGorilla's API documentation

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

In this article

Available integrations

TestGorilla API versions

Authentication

Assessments

List of assessments

Assessment details

Retrieving the anti-cheating flags for an assessment

Inviting a candidate

Creating a public link for an assessment

Activating/deactivating a public link

Inviting a candidate using their email address

Retrieving the personalized candidate URL to take the assessment without sending an invitation email to the candidate

Re-inviting a candidate using their candidature ID

Candidates

List of candidates invited to an assessment

Retrieving candidate details

Deleting a candidate from an assessment

Set a candidature stage as REJECTED

Trigger a rejection email for a candidate

Test Results

Retrieving assessment results

Retrieving assessment results in PDF

Result types

Basic Tests

Custom Questions

Personality Tests

Personality Description Endpoint

Coding tests

Retrieving the time used on a coding test

Retrieving the URL to a coding test report

Articles in this section