Candidates

Overview

Candidates are individuals who take assessments.

List of candidates invited to an assessment

Use the following endpoint to retrieve the list of candidates invited to an assessment.

Endpoint

GET https://app.testgorilla.com/api/assessments/candidature?assessment=<ASSESSMENT_ID>

Query Parameters

Parameters	Description
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. This parameter supports ascending and descending order. The default ordering ascending. By adding the minus symbol (-), the order will be descending. 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

Example Request

curl 'https://app.testgorilla.com/api/assessments/candidature/?assessment=<ASSESSMENT_ID>' \
-H 'Authorization: Token <YOUR TOKEN GOES HERE>'

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

Endpoint

GET https://app.testgorilla.com/api/assessments/candidates/<TESTTAKER_ID>

Example Request

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

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

Endpoint

DELETE https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>

Example Request

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 would like to set as REJECTED:

Endpoint

PATCH 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/change_stage

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

Example Response

{
    "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 would like the email triggered for.

⚠️

Caution: Make sure the candidature is in REJECTED status when triggering this email.

Endpoint

POST 'https://app.testgorilla.com/api/assessments/candidature/<CANDIDATURE_ID>/send-reminder

Example Request

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

Invitations Test Results