TestGorilla's public API documentation

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 through our API.

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

  • 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 cannot answer test questions anymore.

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: 

  • 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. By adding the minus symbol (-), the order will be descending. For example:

  • ordering=modified  → newest on the bottom
  • ordering=-modified  → newest on top

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:

  • invited
  • started
  • completed

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 (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. For example:

  • ordering=created → newest on the bottom. 
  • ordering=-created → newest on 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 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

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.