Skip to content

Checks

This refers to the reference checks that every user in your company has requested.

List Checks

Method GET
Path /checks{?states}{?search}{?requester}{?date_start}{?date_end}{?limit}{?page}{?unread_only}

This endpoint returns the list of reference checks that have been requested by any user in your company. The pages attribute allows you to link to the current, previous and next pages of the checks list.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
states requested,in_progress Yes list Filter the list of checks by given list of states separated by commas. Possible values are requested, in_progress, completed, stopped and expired.
search "" No string Filter the list of checks by searching on various fields of the requester and candidate objects.
requester 0 No integer Filter the list of checks to the ones requested by the logged in User, if it is 1, else return list of all Checks requested by all team members. If the logged in user does not have permission to view other's checks then this param will not have any effect, it will behave like it's value is 1 in this case. Default: 0
date_start "" No datetime Filter the list of checks to the ones requested on or after the given datetime object. The format should be 2017-01-01T00:00:00 UTC. Defaults to minimum date object. Default: ""
date_end "" No datetime Filter the list of checks to the ones requested before the given datetime object. The format should be 2017-12-31T23:59:59 UTC. Defaults to the time the API request was made. Default: ""
limit 20 No integer Limit the list of checks to a certain number. Defaults to 20, maximum can be 100. Default: 20
page 1 No integer The page number in the list of checks. Default: 1
unread_only false No boolean Filter the list of checks to show only unread checks. If set to true, only unread checks will be returned. Default: false
Search syntax and examples

Specific search can be done on candidate name by sending candidate:{name of the candidate}

Specific search can be done on candidate email by sending email:{email of the candidate}

Specific search can be done on questionnaire title by sending questionnaire:{words present in the title of the questionnaire}

Combination search can be done by sending list of search params:-

  • /checks?search=candidate:jane&search=candidate:jake -> /checks?search=candidate:jane OR candidate:jake
  • /checks?search=candidate:jane&search=candidate:jake&search=questionnaire:development -> /checks?search=(candidate:jane OR candidate:jake) AND questionnaire:development
  • /checks?search=candidate:jane&search=candidate:jake&search=questionnaire:development&search=questionnaire:devops -> /checks?search=(candidate:shirish OR candidate:gagan) AND (questionnaire:development OR questionnaire:devops)

Default: ""

Response

200 — application/json

{
"pages": {
    "total": 5,
    "links": {
        "this": "/checks",
        "prev": "",
        "next": "/checks?states=requested,in_progress,completed&search=""&requester=0&date_start=""&date_end=""&limit=20&page=2"
    }
},
"data": [
    {
        "id": 1000,
        "integration": "app",
        "integration_sub": "",
        "requested": "2017-10-17T06:40:08",
        "requester": {
            "id": 100,
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@email.com",
            "url": "/user/100"
        },
        "candidate": {
            "first_name": "Stuart",
            "last_name": "North",
            "email": "stuart.north@example.com"
        },
        "xref": {
            "role": "Engineer",
            "state": "in_progress",
            "state_last_updated": "2017-10-18T09:34:01",
            "criterion": {
                "id": 300,
                "base_id": 100,
                "name": "Demo Criterion - Example",
                "min_referees": 2,
                "min_years": 0,
                "mappings": [
                    {
                        "period_type": "Employment",
                        "questionnaire": "Xref Standard Template"
                    }
                ],
                "url": "/criterion/300"
            },
            "referees": [
                {
                    "name": "Jane Doe",
                    "email": "jane.doe@example.com",
                    "state": "answered",
                    "viewed": false,
                    "url": "/check/report/5000",
                    "company_name": "Test Company",
                    "unusual_activity": "detected"
                },
                {
                    "name": "Bob Piper",
                    "email": "bob@example.com",
                    "state": "accessed",
                    "viewed": false,
                    "url": "",
                    "company_name": "Test Company",
                    "unusual_activity": ""
                }
            ],
        },
        "url": "/check/1000"
    }
]
}

401 — application/json

List Referee Attachments

Method GET
Path /check/{check_id}/attachments

This endpoint returns the list of attachments uploaded by the referee that have been requested by any user in your company. The API returns a 404 response if the check is not found and a 403 response if the requesting user does not have the permissions required to view this check or attachments.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 1000 Yes number A unique identifier of the check.

Response

200 — application/json

Body
{
   "check_id":1,
   "requester":{
      "id":1,
      "first_name":"Douglas",
      "last_name":"Matthews",
      "email":"douglas.matthews@test.com",
      "url":"/user/1"
   },
   "candidate":{
      "email":"ryan.rodriguez@test.com",
      "first_name":"Ryan",
      "last_name":"Rodriguez"
   },
   "referees":[
      {
         "name":"Chad Pacheco",
         "email":"chad.pacheco@test.com",
         "status":"answered",
         "viewed":false,
         "url":"/check/1/report/2",
         "company_name":"Company #0",
         "attachmens":[
            {
               "id":"64bbbaf3930f481c9088c276af48a8bd",
               "description":"Referee Attachment File Description 0",
               "name":"referee_attachment_file_0.pdf",
               "referee_email":"chad.pacheco@test.com",
               "url":"/check/1/attachment/64bbbaf3930f481c9088c276af48a8bd"
            },
            {
               "id":"779c0de304b84d6998776869be713f5a",
               "description":"Referee Attachment File Description 1",
               "name":"referee_attachment_file_1.pdf",
               "referee_email":"chad.pacheco@test.com",
               "url":"/check/1/attachment/779c0de304b84d6998776869be713f5a"
            }
         ]
      },
      {
         "name":"Christopher Porter",
         "email":"christopher.porter@test.com",
         "status":"answered",
         "viewed":false,
         "url":"/check/1/report/3",
         "company_name":"Company #0",
         "attachmens":[
            {
               "id":"43c2532a23964878b41e333015a156b3",
               "description":"Referee Attachment File Description 2",
               "name":"referee_attachment_file_2.pdf",
               "referee_email":"christopher.porter@test.com",
               "url":"/check/1/attachment/43c2532a23964878b41e333015a156b3"
            }
         ]
      }
   ]
}

401 — application/json

{
"detail": "Authentication credentials were not provided."
}

404

403

400

Check Operations

Retrieve a Check

Method GET
Path /check/{id}

This endpoint returns information relevant to the check, such as the requested time, the requester and details of the candidate, as well as the xref object. The API returns a 404 response if the check is not found and a 403 response if the requesting user does not have the permissions required to view this check.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
Name Example / default Required Type Description
id 1000 Yes number A unique identifier of the check.

Response

200 — application/json
Attributes (object)
AttributeTypeDescription
idnumberID of the check.
integrationstringThe integration that created the check.
integration_substringThe integration sub that created the check.
requestedstringTime the check was requested.
requesterobjectUser object who requested this check.
idnumberID of the user.
first_namestringUser's first name.
last_namestringUser's last name.
emailstringUser's email address.
urlstringAPI endpoint to retrieve this object.
candidateobjectCandidate object for this check.
first_namestringCandidate's first name.
last_namestringCandidate's last name.
emailstringCandidate's email address.
companyobjectCompany object associated with the check
idnumberThe company ID.
xrefobjectThe Xref object for this check.
idnumberThe Xref ID for this check.
rolestringThe role description for which the candidate is being assessed.
statestringState of the check as of now. ['requested','deleted','in_progress','expired','completed','stopped']
state_last_updatedstringTime the state was last updated.
criterionobjectThe Criterion object for this check.
idnumberID of the criterion.
base_idnumberBase creation used for creation.
namestringCriterion's name.
min_refereesnumberMinimum referees required.
min_yearsnumberMinimum years to cover.
mappingsarrayQuestionnaire mappings for each period type.
mapping_1object
period_typestring
questionnairestring
mapping_2object
period_typestring
questionnairestring
urlstringAPI endpoint to retrieve this object.
refereesarrayList of referees for this check.
referee_1object
namestringReferee's name.
emailstringReferee's email.
phonestringReferee's phone number.
rolestringReferee's role at the time.
statestringReferee's state.
viewedbooleanTrue if the user has viewed it already, False otherwise.
urlstringAPI endpoint to retrieve this referee's answers.
company_namestringReferee's company at the time.
competenciesarray
comptency_1object
competencystringThe name of the competency.
scorenumberThe candidate's score for this competency provided by the referee.
averagenumberThe average rating for this competency across all candidates.
sentimentobjectThe breakdown of the sentiment analysis of the referee's text answers.
positivenumberThe percentage of postive sentiment.
neutralnumberThe percentage of neutral sentiment.
negativenumberThe percentage of negative sentiment.
referee_start_dateobjectThe start date for the referee's feedback.
yearnumber
monthnumber
daynumber
referee_end_dateobjectThe end date for the referee's feedback.
yearnumber
monthnumber
daynumber
referee_2object
namestringReferee's name.
emailstringReferee's email.
phonestringReferee's phone number.
rolestringReferee's role at the time.
statestringReferee's state.
viewedbooleanTrue if the user has viewed it already, False otherwise.
urlstringAPI endpoint to retrieve this referee's answers.
company_namestringReferee's company at the time
competenciesarray
comptency_1object
competencystringThe name of the competency
scorenumberThe candidate's score for this competency provided by the referee
averagenumberThe average rating for this competency across all candidates
sentimentobjectThe breakdown of the sentiment analysis of the referee's text answers
positivenumberThe percentage of postive sentiment
neutralnumberThe percentage of neutral sentiment
negativenumberThe percentage of negative sentiment
referee_start_dateobjectThe start date for the referee's feedback.
yearnumber
monthnumber
daynumber
referee_end_dateobjectThe end date for the referee's feedback.
yearnumber
monthnumber
daynumber
timeline_gapsarrayList of timeline gaps (e.g. Unemployment, travel)
timeline_gap_1object
start_dateobject
yearnumber
monthnumber
daynumber
end_dateobject
yearnumber
monthnumber
daynumber
gap_typestringCandidates's selection from dropdown list
descriptionFree form text entry provided by candidate
priceobjectThe price incurred when the check was requested.
valuenumberPrice value.
currencystringCredit currency (three letter abbreviation e.g. "AUD")
earliest_timeline_dateobjectThe earliest date in the candidate's timeline
yearnumber
monthnumber
daynumber
latest_timeline_dateobjectThe latest date in the candidate's timeline
yearnumber
monthnumber
daynumber
urlstringAPI endpoint to retrieve this object.
Body
{
    "id": 1000,
    "integration": "app",
    "integration_sub": "",
    "requested": "2017-10-17T06:40:08",
    "requester": {
        "id": 100,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@email.com",
        "url": "/user/100"
    },
    "candidate": {
        "first_name": "Stuart",
        "last_name": "North",
        "email": "stuart.north@example.com"
    },
    "company": {
        "id": 100
    },
    "xref": {
        "id": 900,
        "role": "Engineer",
        "state": "in_progress",
        "state_last_updated": "2017-10-18T09:34:01",
        "criterion": {
            "id": 300,
            "base_id": 300,
            "name": "Demo Criterion - Example",
            "min_referees": 2,
            "min_years": 0,
            "mappings": [
                {
                    "period_type": "Employment",
                    "questionnaire": "Xref Standard Template"
                }
            ],
            "url": "/criterion/300"
        },
        "referees": [
            {
                "name": "Jane Doe",
                "email": "jane.doe@example.com",
                "phone": "0412345678",
                "role": "Manager Role",
                "state": "answered",
                "viewed": false,
                "url": "/check/report/5000",
                "company_name": "Test Company",
                "competencies": [
                    {
                        "competency": "Communication",
                        "score": 1.0,
                        "average": 5.1458
                    },
                    {
                        "competency": "Leadership",
                        "score": 2.0,
                        "average": 5.311
                    },
                    {
                        "competency": "Honesty & Integrity",
                        "score": 3.0,
                        "average": 5.0923
                    },
                    {
                        "competency": "OH&S",
                        "score": 4.0,
                        "average": 5.1828
                    }
                ],
                "sentiment": {
                    "positive": 0,
                    "neutral": 100,
                    "negative": 0
                },
                "unusual_activity": "",
                "referee_type": "Employment",
                "referee_start_date": {
                    "year": 2017,
                    "month": 1,
                    "day": 1
                },
                "referee_end_date": {
                    "year": 2022,
                    "month": 1,
                    "day": 1
                }
            },
            {
                "name": "Bob Piper",
                "email": "bob@example.com",
                "phone": "0498765432",
                "role": "Manager Role",
                "state": "accessed",
                "viewed": false,
                "url": "",
                "company_name": "Test Company",
                "competencies": [
                    {
                        "competency": "Communication",
                        "score": 2.0,
                        "average": 5.1458
                    },
                    {
                        "competency": "Leadership",
                        "score": 6.0,
                        "average": 5.311
                    },
                    {
                        "competency": "Honesty & Integrity",
                        "score": 5.0,
                        "average": 5.0923
                    },
                    {
                        "competency": "OH&S",
                        "score": 6.0,
                        "average": 5.1828
                    }
                ],
                "sentiment": {
                    "positive": 0,
                    "neutral": 100,
                    "negative": 0
                },
                "unusual_activity": "confirmed",
                "referee_type": "Employment",
                "referee_start_date": {
                    "year": 2017,
                    "month": 1,
                    "day": 1
                },
                "referee_end_date": {
                    "year": 2022,
                    "month": 1,
                    "day": 1
                }
            }
        ],
        "timeline_gaps": [
            {
                "start_date": {
                    "year": 2022,
                    "month": 1,
                    "day": 2
                },
                "end_date": {
                    "year": 2022,
                    "month": 7,
                    "day": 1
                },
                "gap_type": "Travel",
                "description": "Around the world"
            }
        ],
        "price": {
            "value": 49.99,
            "currency": "AUD"
        },
        "earliest_timeline_date": {
            "year": 2017,
            "month": 1,
            "day": 1
        },
        "latest_timeline_date": {
            "year": 2022,
            "month": 7,
            "day": 1
        }
    },
    "url": "/check/1000"
}
401 — application/json
{
"detail": "Authentication credentials were not provided."
}
404
403

Cancel a Check

Method DELETE
Path /check/{id}

A check can only be cancelled if it is in a requested or in_progress state. The state can be queried via the xref object of the 'Retrieve a check' operation. This endpoint returns a 400 response if the check cannot be cancelled, a 412 response if the check is in stopped state already, a 404 response if the check is not found, and a 403 response if the requesting user does not have the permissions required to cancel this check. It returns a 200 response containing STOPPED or DELETED in the response body, depending on which state the check was in prior to the call.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
Name Example / default Required Type Description
id 1000 Yes number A unique identifier of the check.

Response

200 — application/json
{
"detail": "Check was STOPPED."
}
400
{
"detail": "Error",
"message": "Check cannot be cancelled when it is in EXPIRED or COMPLETED state."
}
412
{
"detail": "Check cannot be cancelled when it is already STOPPED."
}
404
403

Hide Check

Method POST
Path /check/{check_id}/hide

This endpoint hides a check. It returns a 200 response if the check was successfully hidden. The endpoint returns a 404 response if the check is not found or is already hidden, and a 403 response if the requesting user does not have the permissions required to hide a check.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
Name Example / default Required Type Description
check_id 100 Yes number A unique identifier of the check.

Response

200 — application/json
404
403

Create a new Check

Method POST
Path /check

This endpoint creates a new check. It returns a 201 response if the request was successful. The response body follows the same format as the ‘Retrieve a check' endpoint. The endpoint returns a 400 response with error in the body if the request was not successful, and a 403 response if the requesting user does not have the permissions required to create a new check.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
AttributeTypeDescription
rolestring, requiredA string identifying the role for which the candidate is being interviewed for.
employerobject, optionalEmployer email address to attribute this request to. This will only work if the request is authenticating via a machine user. The employer must already exist within the machine user's company for this to work.
emailstring, optionalEmployer's email address.
candidateobject, requiredDetails of the candidate.
first_namestring, requiredCandidate's first name.
last_namestring, requiredCandidate's last name.
emailstring, requiredCandidate's email address.
phonestring, requiredCandidate's phone number, preferably mobile.
criterionobject, requiredCriterion to be used for the check with values to override.
idnumber, requiredID of the criterion to be used.
min_yearsnumberMinimum number of years for this criterion
min_refereesnumber, optionalMinimum number of referees to request for the check.
gapMaximum allowed gap between employment histories
enforcebooleanWhether to enforce the gap definition.
unitstring'week' or 'days'
valuenumberNumber of days or weeks (as per unit)
note_to_candidatestring, optionalThe note that will go in the email to the candidate.
note_to_refereestring, optionalThe note that will go in the email to the referee.
custom_idan optional reference ID which will be returned on the payload and on the webhook updates
hiring_accountan optional hiring account ID
Body
{
    "role": "System Engineer",
    "employer": {
        "email": "john.citizen@example.com"
    },
    "candidate": {
        "first_name": "Joe",
        "last_name": "Bloggs",
        "email": "joe.bloggs@example.com",
        "phone": "123456789"
    },
    "criterion": {
        "id": 100,
        "min_referees": 2,
        "min_years": 0,
        "note_to_candidate": "some note to the candidate",
        "note_to_referee": "some note to the referee",
        "gap": {
            "enforce": true,
            "unit": "days",
            "value": 30
        }
    },
    "custom_id": 100,
    "hiring_account": 1
}

Response

201 — application/json
{
"id": 1001,
"requested": "2017-25-12T09:13:00",
"requester": {
    "id": 100,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@email.com",
    "url": "/user/100"
},
"candidate": {
    "first_name": "Joe",
    "last_name": "Bloggs",
    "email": "joe.bloggs@example.com"
},
"xref": {
    "role": "System Engineer",
    "state": "requested",
    "state_last_updated": "",
    "criterion": {
        "id": 100,
        "name": "Demo Criterion - Example",
        "min_referees": 2,
        "min_years": 0,
        "mappings": [
            {
                "period_type": "Employment",
                "questionnaire": "Xref Standard Template"
            }
        ],
        "url": "/criterion/100"
    },
    "referees": [],
    "price": {
        "value": 49.99,
        "currency": "AUD"
    },
    "hiring_account": {
        "id": "1",
        "name": "hiringAccount1"
    }
},
"url": "/check/1001",
"custom_id": 100
}
400
{
"detail": "Error",
"message": {
    "role": [
        "This field is required.",
        "This field may not be blank."
    ],
    "candidate": [
        "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.",
            "Enter a valid email address."
        ],
        "phone": [
            "This field is required.",
            "This field may not be blank.",
            "Invalid phone number entered",
            "Phone number entered is too short"
        ]
    ],
    "criterion": [
        "This field is required.",
        "Invalid criterion was given.",
        "Criteria is not valid or active for your company",
        "id": [
            "This field is required."
        ],
        "min_referees": [
            "This field is required.",
            "A criterion must have a minimum of 1 reference",
            "Ensure this value is less than or equal to 5."
        ],
        "note_to_candidate": [
            "Ensure this value is less than or equal to 500 characters."
        ],
        "note_to_referee": [
            "Ensure this value is less than or equal to 500 characters."
        ]
    ]
}
}
403

Validate a new Check with pre-populated Referees

Method POST
Path /check/with-referees/validate

This endpoint validates a check with pre-populated referees attached. 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 request a check.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
AttributeTypeDescription
rolestring, requiredA string identifying the role for which the candidate is being interviewed for.
candidateobject, requiredDetails of the candidate.
first_namestring, requiredCandidate's first name.
last_namestring, requiredCandidate's last name.
emailstring, requiredCandidate's email address.
phonestring, requiredCandidate's phone number, preferably mobile.
ip_addressstring, optionalCandidate's IP address. This is critical for fraud detection.
criterionobject, requiredCriterion to be used for the check with values to override.
idnumber, requiredID of the criterion to be used.
min_refereesnumber, optionalMinimum number of referees to request for the check.
note_to_candidatestring, optionalThe note that will go in the email to the candidate.
note_to_refereestring, optionalThe note that will go in the email to the referee.
refereesarrayList of referees for the candidate.
refereeobjectDetails of the referee.
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.
company_namestring, requiredThe company the referee worked for with the candidate.
Body
{
    "role": "System Engineer",
    "candidate": {
        "first_name": "Joe",
        "last_name": "Bloggs",
        "email": "joe.bloggs@example.com",
        "phone": "123456789",
        "ip_address": "192.168.1.2"
    },
    "criterion": {
        "id": 100,
        "min_referees": 2,
        "note_to_candidate": "some note to the candidate",
        "note_to_referee": "some note to the referee"
    },
    "referees": [
        {
            "reference_type": 1,
            "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": {
    "role": [
        "This field is required.",
        "This field may not be blank."
    ],
    "candidate": [
        "This field is required."
    ],
    "criterion": [
        "This field is required."
    ],
    "referees": [
        "This field is required."
    ],
}
}
403

Create a new Check with pre-populated Referees

Method POST
Path /check/with-referees

This endpoint creates a check with pre-populated referees attached. It returns a 201 response if the request was successful. If the reference_type is "Employment", the "position_referee" and "position_candidate" fields must be provided for referees. If the reference_type is "Voluntary", all fields are mandatory for referees. If the reference_type is "academic", the "institution" and "course" fields must be provided for referees. If the reference_type is "character", the "relationship" field must be provided. 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 request a check.

Request

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
AttributeTypeDescription
rolestring, requiredA string identifying the role for which the candidate is being interviewed for.
employerobject, optionalEmployer email address to attribute this request to. This will only work if the request is authenticating via a machine user. The employer must already exist within the machine user's company for this to work.
emailstring, optionalEmployer's email address.
candidateobject, requiredDetails of the candidate.
first_namestring, requiredCandidate's first name.
last_namestring, requiredCandidate's last name.
emailstring, requiredCandidate's email address.
phonestring, requiredCandidate's phone number, preferably mobile.
ip_addressstring, optionalCandidate's IP address. This is critical for fraud detection.
criterionobject, requiredCriterion to be used for the check with values to override.
idnumber, requiredID of the criterion to be used.
min_refereesnumber, optionalMinimum number of referees to request for the check.
note_to_candidatestring, optionalThe note that will go in the email to the candidate.
note_to_refereestring, optionalThe note that will go in the email to the referee.
refereesarrayList of referees for the candidate. * Reference types are attached as separate objects in examples below,
Employment: Employmentobject
reference_type: 17number, requiredEmployment
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.
company_namestring, requiredThe company the referee worked for with the candidate.
refereeobjectDetails of the referee.
reference_type: 23number, requiredVoluntary
first_namestring, requiredReferee's first name.
last_namestring, requiredReferee's last name.
emailstring, requiredReferee's email address.
phonestring, requiredReferee's phone number, preferably mobile.
start_datestring, requiredReferee start date.
end_datestring, requiredReferee end date.
company_namestring, requiredThe company the referee worked for with the candidate.
refereeobjectDetails of the referee.
reference_type: 26number, requiredAcademic
first_namestring, requiredReferee's first name.
last_namestring, requiredReferee's last name.
emailstring, requiredReferee's email address.
phonestring, requiredReferee's phone number, preferably mobile.
institutionstring, requiredThe institution the candidate attended with the referee.
coursestring, requiredThe candidate’s course.
start_datestring, requiredReferee start date.
end_datestring, requiredReferee end date.
refereeobjectDetails of the referee.
reference_type: 27number, requiredCharacter
first_namestring, requiredReferee's first name.
last_namestring, requiredReferee's last name.
emailstring, requiredReferee's email address.
phonestring, requiredReferee's phone number, preferably mobile.
relationshipstring, requiredThe referee’s relationship with the candidate.
start_datestring, requiredReferee start date.
end_datestring, requiredReferee end date.
custom_idan optional reference ID which will be returned on the payload and on the webhook updates
Body
{
    "role": "System Engineer",
    "employer": {
        "email": "john.citizen@example.com"
    },
    "candidate": {
        "first_name": "Joe",
        "last_name": "Bloggs",
        "email": "joe.bloggs@example.com",
        "phone": "123456789",
        "ip_address": "192.168.1.2"
    },
    "criterion": {
        "id": 100,
        "min_referees": 2,
        "note_to_candidate": "some note to the candidate",
        "note_to_referee": "some note to the referee"
    },
    "referees": [
        {
            "reference_type": 17,
            "first_name": "James",
            "last_name": "Smith",
            "email": "james.smith@org1.com",
            "phone": "123456789",
            "position_referee": "Manager",
            "position_candidate": "Developer",
            "start_date": "2016-11-10",
            "end_date": "2017-12-20",
            "company_name": "Test Company 1"
        },
        {
            "reference_type": 23,
            "first_name": "James",
            "last_name": "Smith",
            "email": "james.smith@org1.com",
            "phone": "123456789",
            "start_date": "2012-11-10",
            "end_date": "2019-12-20",
            "company_name": "Test Company 1"
        },
        {
            "reference_type": 26,
            "first_name": "Joan",
            "last_name": "Bloggs",
            "institution": "UNSW",
            "course" : "Maths101",
            "email": "james.smith@university.com",
            "phone": "123456789",
            "start_date": "2012-11-10",
            "end_date": "2019-12-20"
        },
        {
            "reference_type": 27,
            "first_name": "Joan",
            "last_name": "Bloggs",
            "relationship" : "friend",
            "email": "james.smith@personalemail.com",
            "phone": "123456789",
            "start_date": "2012-11-10",
            "end_date": "2019-12-20"
        }
    ],
    "custom_id": 100
}

Response

201 — application/json
{
"id": 1001,
"requested": "2017-25-12T09:13:00",
"requester": {
    "id": 100,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@email.com",
    "url": "/user/100"
},
"candidate": {
    "first_name": "Joe",
    "last_name": "Bloggs",
    "email": "joe.bloggs@example.com"
},
"xref": {
    "role": "System Engineer",
    "state": "requested",
    "state_last_updated": "",
    "criterion": {
        "id": 100,
        "name": "Demo Criterion - Example",
        "min_referees": 2,
        "min_years": 0,
        "mappings": [
            {
                "period_type": "Employment",
                "questionnaire": "Xref Standard Template"
            }
        ],
        "url": "/criterion/100"
    },
    "referees": [
        {
            "reference_type": 17,
            "first_name": "James",
            "last_name": "Smith",
            "email": "james.smith@org1.com",
            "phone": "123456789",
            "position_referee": "Manager",
            "position_candidate": "Developer",
            "start_date": "2016-11-10",
            "end_date": "2017-12-20",
            "company_name": "Test Company 1"
        }
    ]
},
"url": "/check/1001",
"price": {
    "value": 49.99,
    "currency": "AUD"
},
"candidate_url": "candidate.xref.com/?t=candidate_unique_token",
"custom_id": 100
}
400
# Error for missing required academic reference fields
{
"detail": "Validation Error",
"message": {
"referees": [
{
"non_field_errors": [
"institution",
"course"
]
}
]
}
}
400
# Error for missing required character reference field
{
"detail": "Validation Error",
"message": {
"referees": [
{
"non_field_errors": [
"relationship"
]
}
]
}
}
400
{
"detail": "Validation Error",
"message": {
    "referees": [
        {
            "reference_type": [
                "Reference type does not exist"
            ]
        }
    ]
}
}

Retrieve a Report

Method GET
Path /check/{check_id}/report/{referee_id}

This endpoint returns a 200 response if accepted, with a URL linking to the reference check report. It returns a 404 response if the check or the referee is not found, and a 403 response if the requesting user does not have the permissions required to view the check.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
referee_id 200 Yes number A unique identifier for the referee.

Response

200 — application/json

{
"url": "https://a-url-for-the-report-at.xref.com"
}

404

403

Retrieve a PDF Report

Method GET
Path /check/{check_id}/report/{referee_id}/pdf{?binary}

This endpoint returns a 200 response if accepted and automatically downloads the file in PDF format. It returns a 404 response if the check or the referee is not found, a 403 response if the requesting user does not have the permissions required to view the check, and a 400 for any errors downloading the file.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
referee_id 200 Yes number A unique identifier for the referee.
binary 0 No integer response content-type is application/octet-stream if value is 1 otherwise, it will return the PDF file.

Response

200 — application/json

404

403

400

Retrieve a JSON Report

Method GET
Path /check/{check_id}/report/{referee_id}/json

This endpoint returns a 200 response if accepted and returns report data in JSON format. Note: The reference_summary field will only be available for companies that are also enterprise customers and have enabled AI summaries. It returns a 404 response if the check or the referee is not found, a 403 response if the requesting user does not have the permissions required to view the check.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
referee_id 200 Yes number A unique identifier for the referee.

Response

200 — application/json

{
"candidate": {
    "id": 483759,
    "name": "Emma Watson",
    "position": "Test Analyst",
    "verb": "Employed at",
    "modifications": [],
    "email": "test@test.com",
    "phone_number": "12345678",
    "organisation": "An_organisation",
    "answers": [
        {
            "question_type": "boolean+textarea",
            "question": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
            "answer_txt": "",
            "answers": [
                {
                    "show_additional_info": true,
                    "text": "No",
                    "id": 0,
                    "value": 0
                },
                {
                    "show_additional_info": false,
                    "text": "Yes",
                    "id": 1,
                    "value": 1
                }
            ],
            "answer_chk": 1
        }
    ],
},
"referee": {
    "id": 483760,
    "name": "Jira Li",
    "position": "Manager",
    "organisation": "Kite",
    "date_answered": "2019-02-01T08:48:31+11:00",
    "email": "test_referee@test.com",
    "phone_number": "1234",
    "uploaded_pdf_url": "https://a-url-for-the-report-at.xref.com",
    "uploaded_pdf_title": "title.pdf",
    "candidate_position": "candidate sample position",
    "modifications": [
        {
            "field": "Candidate End Date",
            "original": "2019-01-29",
            "updated": "2019-01-31"
        },
        {
            "field": "Candidate Job Title",
            "original": "QA",
            "updated": "Intern"
        }
    ],
    "stats": {
        "word_count": 21,
        "word_count_average": 118,
        "turnaround": 0,
        "turnaround_average": 8,
        "sentiment": {
            "enable": true,
            "sentiment": {
                "negative": "0",
                "neutral": "15",
                "positive": "85"
            }
        }
    },
    "answers": {
        "questionnaire_title": "Xref Standard Bilingual",
        "questionnaire_is_standard": false,
        "answer_lines": [
            {
                "count": 2,
                "global_count": 6,
                "answer_txt": "Lorem ipsum",
                "question": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud",
                "answers": [],
                "question_type": "textarea",
                "answer_chk": 0
            },
            {
                "count": 1,
                "global_count": 6,
                "answer_txt": "Lorem",
                "question": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam",
                "answers": [
                    {
                        "show_additional_info": true,
                        "text": "Always exceeded expectations",
                        "id": 7,
                        "value": 7
                    },
                    {
                        "show_additional_info": true,
                        "text": "Often exceeded expectations",
                        "id": 6,
                        "value": 6
                    },
                    {
                        "show_additional_info": true,
                        "text": "Occasionally exceeded expectations",
                        "id": 5,
                        "value": 5
                    },
                    {
                        "show_additional_info": true,
                        "text": "Met expectations",
                        "id": 4,
                        "value": 4
                    },
                    {
                        "show_additional_info": true,
                        "text": "Occasionally fell short of expectations",
                        "id": 3,
                        "value": 3
                    },
                    {
                        "show_additional_info": true,
                        "text": "Often fell short of expectations",
                        "id": 2,
                        "value": 2
                    },
                    {
                        "show_additional_info": true,
                        "text": "Never met expectations",
                        "id": 1,
                        "value": 1
                    },
                    {
                        "show_additional_info": true,
                        "text": "N/A",
                        "id": 0,
                        "value": 0
                    }
                ],
                "question_type": "select+textarea",
                "answer_chk": 4
            }
        ],
    },
    "core_competency": true,
    "unusual_activity": {
        "status": "valid",
        "findings": {
            "flag_ip_address": true,
            "flag_browser": true,
            "flag_email_address": false,
            "flag_mobile_match_referee_referee": false,
            "flag_mobile_match_referee_candidate": false,
            "resolution_flag": "suspicious",
            "marked_by": "A person"
        },
        "notes": [
            {
                "updated": "2019-10-04 13:26:42.808007",
                "comment": "Fake comment",
                "employer_name": "Jane Doe"
            }
        ]
    }
    "competencies": {
        "chart_data": [
            {
                "competency": "Communication",
                "score": 7.0,
                "average": 5.3571
            },
            {
                "competency": "Leadership",
                "score": 7.0,
                "average": 4.8522
            },
            {
                "competency": "Honesty & Integrity",
                "score": 6.0,
                "average": 5.7749
            },
            {
                "competency": "OH&S",
                "score": 7.0,
                "average": 5.1177
            }
        ],
        "overall_average": 5.2755,
        "candidate_score": 6.75
    },
    "timeline": {
        "earliest_timeline_date": {
            "year": 2016,
            "month": 4,
            "day": 1
        },
        "latest_timeline_date": {
            "year": 2019,
            "month": 10,
            "day": 8
        },
        "coverage_start_date": {
            "year": 2016,
            "month": 4,
            "day": 1
        },
        "coverage_end_date": {
            "year": 2019,
            "month": 10,
            "day": 8
        },
        "referee_start_date": {
            "year": 2016,
            "month": 4,
            "day": 1
        },
        "referee_end_date": {
            "year": 2019,
            "month": 10,
            "day": 8
        }
    },
    "attachments": [
        {
            "uuid": "70f5ef59-5096-4a33-b5d9-661648aada71",
            "file_name": "referee_attachment_file_1.pdf",
            "description": "Referee Attachment File Description 1",
            "created_date": "2019-10-04 13:26:42.808007"
        }
    ],
    "opt_in": {
        "exists": true,
        "company": "pdf org",
        "answers": {
            "answer_chk": true,
            "referee_current_job_title": "Manager",
            "referee_current_organisation": "Modify",
            "custom_question": "Looking for Job",
            "custom_question_enabled": false,
            "opted_in_for": 1,
            "type": 2,
            "location": {
                "administrative": "Western Australia",
                "country": "Australia",
                "name": "Perth"
            },
            "additional_info": "Option section---------"
        }
    },
    "reference_summary": {
        "id": 1234,
        "ref_count": 1,
        "summary": "Emma worked at a company for 2 years. Her manager reports that she was an excellent employee during her time, excelling at teamwork, and won the Nobel Peace Prize.",
        "areas_of_strength": [
            {
                "title": "Teamwork",
                "description": "Emma excels at working in a team environment."
            },
        ],
        "areas_of_improvement": [],
        "areas_of_note": [
            {
                "title": "Won the Nobel Peace Prize",
                "description": "Emma won the Nobel Peace Prize in 2018."
            },
        ]
    }
}
}

404

403

Retrieve a Referee Attachment

Method GET
Path /check/{check_id}/attachment/{attachment_id}{?binary}

This endpoint returns a 200 response if accepted and automatically downloads the file. It returns a 404 response if the check or the attachment is not found, a 403 response if the requesting user does not have the permissions required to view the check, and a 400 for any errors downloading the file.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
attachment_id c29d85463879434cabe6318884630123 Yes string A unique identifier for the attachment.
binary 0 No integer response content-type is application/octet-stream if value is 1 otherwise, it will return the PDF file.

Response

200

404

403

400

Retrieve a Check Lifecycle

Method GET
Path /check/{check_id}/lifecycle

This endpoint returns a 200 response if accepted and returns lifecycle data in JSON format. It returns a 404 response if the check is not found and a 403 response if the requesting user does not have the permissions required to view the check.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.

Response

200 — application/json

{
"id": 7000,
"lifecycle": [
    {
        "user_id": 223345,
        "user_type": "referee",
        "user_name": "John Smith",
        "action": "agreed",
        "action_arg1": "ref",
        "action_arg2": "referee from candidate app",
        "action_arg3": "message: changes:{}",
        "action_date": "2022-06-01T00:20:23.000000Z",
        "translate": true,
        "ip_address": "27.28.29.46",
        "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36",
        "location": "",
        "city": "Sydney",
        "country": "AU",
        "isp": "TPG Internet"
    },
    {
        "user_id": 223344,
        "user_type": "candidate",
        "user_name": "John Smith",
        "action": "submitted",
        "action_arg1": "John Smith",
        "action_arg2": "candidate app",
        "action_arg3": "",
        "action_date": "2022-05-31T00:19:54.000000Z",
        "translate": true,
        "ip_address": "27.28.29.45",
        "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36",
        "location": "",
        "city": "Sydney",
        "country": "AU",
        "isp": "Telstra"
    },
    {
        "user_id": 223344,
        "user_type": "system",
        "user_name": "John Smith",
        "action": "notified",
        "action_arg1": "employer",
        "action_arg2": "",
        "action_arg3": "",
        "action_date": "2022-06-03T01:13:34.000000Z",
        "translate": true,
        "ip_address": "",
        "browser": "",
        "location": "",
        "city": "",
        "country": "",
        "isp": ""
    }
]
}

Send report to the line manager

Method POST
Path /check/{check_id}/referee/{referee_id}/report/share

This endpoint sends an email to the line manager with a link to access the report. A response code of 200 is returned when an email is successfully sent to the line manager. An error code of 400 is returned when the email is not sent to the line manager. This can happen if either the email or language code is missing from the payload, or if the domain does not belong to the list of company domains.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Parameters

Name Example / default Required Type Description
check_id 100 Yes number A unique identifier of the check.
referee_id 200 Yes number A unique identifier for the referee.

Attributes (object)

AttributeTypeDescription
emailstring, requiredEmail of the line manager.
language_codestring, requiredLanguage code.

Body

{
"email": "john.doe@example.com",
"language_code": "en-au"
}

Response

200

400

{
"detail": "Error",
"message": "Some error message"
}

Add a Note to Unusual-Activity

Method POST
Path /check/{check_id}/report/{referee_id}/ua/note

This endpoint returns a 201 response if note to unusual-activity is added. It returns a 404 response if the check or the referee is not found, a 403 response if the requesting user does not have the permissions required to view the check, and a 400 response if there is a body params error.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Body

{
    "comments": "Test note for the unusual-activity"
}

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
referee_id 3214 Yes number A unique identifier for the referee.

Response

201

404

403

400

Add Resolution for Unusual-Activity

Method POST
Path /check/{check_id}/report/{referee_id}/ua/resolution

This endpoint returns a 201 response if added resolution is successful. Resolution can be 0(Valid) or 1(Suspicious). It returns a 404 response if the check or the referee is not found, a 403 response if the requesting user does not have the permissions required to view the check, and a 400 response if there is a body params error.

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json

Body

{
    "resolution": 0
}

Parameters

Name Example / default Required Type Description
check_id 7000 Yes number A unique identifier of the check.
referee_id 3214 Yes number A unique identifier for the referee.

Response

201

404

403

400