Skip to content

Referee

This refers to the person that a candidate nominates to testify in writing about their character or ability.

Validate Referee

Method POST
Path /referee/validate

This endpoint validates a referee. It returns a 201 response if the validation was successful. The endpoint returns a 400 response with error in the body if there are validation errors, and a 403 response if the requesting user does not have the permissions required to validate a referee.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Attributes (object)

AttributeTypeDescription
candidate_emailstring, requiredEmail of the candidate.
reference_typenumber, requiredID of the type of reference.
first_namestring, requiredReferee's first name.
last_namestring, requiredReferee's last name.
emailstring, requiredReferee's email address.
phonestring, requiredReferee's phone number, preferably mobile.
position_refereestring, requiredReferee's position at that time.
position_candidatestring, requiredCandidate's position at that time.
start_datestring, requiredReferee start date.
end_datestring, requiredReferee end date.

Body

{
    "candidate_email": 'john.doe@example.com',
    "reference_type": 2,
    "first_name": "Joe",
    "last_name": "Bloggs",
    "email": "joe.bloggs@example.com",
    "phone": "123456789",
    "position_referee": "Manager",
    "position_candidate": "Developer",
    "start_date": "2016-11-10",
    "end_date": "2017-12-20",
    "company_name": "Test Company 1"
}

Response

200 — application/json

400

{
"detail": "Validation error",
"message": {
    "candidate_email": [
        "This field is required.",
        "This field may not be blank."
    ],
    "reference_type": [
        "This field is required."
    ],
    "first_name": [
        "This field is required.",
        "This field may not be blank."
    ],
    "last_name": [
        "This field is required.",
        "This field may not be blank."
    ],
    "email": [
        "This field is required.",
        "This field may not be blank."
    ],
    "phone": [
        "This field is required.",
        "This field may not be blank."
    ],
    "position_referee": [
        "This field is required.",
        "This field may not be blank."
    ],
    "position_candidate": [
        "This field is required.",
        "This field may not be blank."
    ],
    "start_date": [
        "This field is required.",
        "This field may not be blank.",
        "Start date cannot be more recent than the end date."
    ],
    "end_date": [
        "This field is required.",
        "This field may not be blank.",
        "Date cannot go past the current date."
    ],
    "company_name": [
        "This field is required.",
        "This field may not be blank.",
    ],
}
}

403

Replace referee

Unlock Xref Status

Method GET
Path /referee/{referee_id}/replace

This endpoint gets the status of the reference to decide whether to display the Replace button or not. The API returns a 404 response if the check if not present. If the criteria is met, the endpoint returns a 200 response with replace_button set to true otherwise, replace_button is set to false.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
Name Example / default Required Type Description
referee_id 200 Yes number A unique identifier for the referee.

Response

200 — application/json
Body
{
    "data": {
        "replace_button": true
    }
}
404

Send email to replace reference

Method POST
Path /referee/{referee_id}/replace/send_email

This endpoint send an email to the candidate asking them to replace a reference they had provided. The endpoint returns a 404 response if the selected reason could not be matched, and a 200 response is sent if the email was successfully sent.

Selected reason Reason
1 Low quality reference
2 Low word count
3 Unsuitable referee
4 Unusual activity alert
5 Candidate offering an additional reference

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
AttributeTypeDescription
selected_reasonnumber, requiredReason for replacing reference.
Body
{
    "selected_reason": 3
}
Parameters
Name Example / default Required Type Description
referee_id 200 Yes number A unique identifier for the referee.

Response

200 — application/json
404