Invitations

Overview

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

Endpoint

GET 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 below and assigning true or false to the active attribute. Once the link is deactivated, the assessment will not be accessible using the URL.

Endpoint

PUT https://app.testgorilla.com/api/assessments/public_links/<PUBLIC_LINK_ID>

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

⚠️

Note: Though recommended, first and last name is optional.

Endpoint

POST https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/

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

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

Endpoint

POST https://app.testgorilla.com/api/assessments/<ASSESSMENT_ID>/invite_candidate/?no_email=true

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

Example 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. Alternatively, you can use the endpoint to list all candidates as described in section 5.1 to obtain the id.

Endpoint

POST https://app.testgorilla.com/api/assessments/candidature/<ID>/send-invitation/

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

Assessments Candidates