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
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
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
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)
| Attribute | Type | Description |
id | number | ID of the check. |
integration | string | The integration that created the check. |
integration_sub | string | The integration sub that created the check. |
requested | string | Time the check was requested. |
requester | object | User object who requested this check. |
id | number | ID of the user. |
first_name | string | User's first name. |
last_name | string | User's last name. |
email | string | User's email address. |
url | string | API endpoint to retrieve this object. |
candidate | object | Candidate object for this check. |
first_name | string | Candidate's first name. |
last_name | string | Candidate's last name. |
email | string | Candidate's email address. |
company | object | Company object associated with the check |
id | number | The company ID. |
xref | object | The Xref object for this check. |
id | number | The Xref ID for this check. |
role | string | The role description for which the candidate is being assessed. |
state | string | State of the check as of now. ['requested','deleted','in_progress','expired','completed','stopped'] |
state_last_updated | string | Time the state was last updated. |
criterion | object | The Criterion object for this check. |
id | number | ID of the criterion. |
base_id | number | Base creation used for creation. |
name | string | Criterion's name. |
min_referees | number | Minimum referees required. |
min_years | number | Minimum years to cover. |
mappings | array | Questionnaire mappings for each period type. |
mapping_1 | object | |
period_type | string | |
questionnaire | string | |
mapping_2 | object | |
period_type | string | |
questionnaire | string | |
url | string | API endpoint to retrieve this object. |
referees | array | List of referees for this check. |
referee_1 | object | |
name | string | Referee's name. |
email | string | Referee's email. |
phone | string | Referee's phone number. |
role | string | Referee's role at the time. |
state | string | Referee's state. |
viewed | boolean | True if the user has viewed it already, False otherwise. |
url | string | API endpoint to retrieve this referee's answers. |
company_name | string | Referee's company at the time. |
competencies | array | |
comptency_1 | object | |
competency | string | The name of the competency. |
score | number | The candidate's score for this competency provided by the referee. |
average | number | The average rating for this competency across all candidates. |
sentiment | object | The breakdown of the sentiment analysis of the referee's text answers. |
positive | number | The percentage of postive sentiment. |
neutral | number | The percentage of neutral sentiment. |
negative | number | The percentage of negative sentiment. |
referee_start_date | object | The start date for the referee's feedback. |
year | number | |
month | number | |
day | number | |
referee_end_date | object | The end date for the referee's feedback. |
year | number | |
month | number | |
day | number | |
referee_2 | object | |
name | string | Referee's name. |
email | string | Referee's email. |
phone | string | Referee's phone number. |
role | string | Referee's role at the time. |
state | string | Referee's state. |
viewed | boolean | True if the user has viewed it already, False otherwise. |
url | string | API endpoint to retrieve this referee's answers. |
company_name | string | Referee's company at the time |
competencies | array | |
comptency_1 | object | |
competency | string | The name of the competency |
score | number | The candidate's score for this competency provided by the referee |
average | number | The average rating for this competency across all candidates |
sentiment | object | The breakdown of the sentiment analysis of the referee's text answers |
positive | number | The percentage of postive sentiment |
neutral | number | The percentage of neutral sentiment |
negative | number | The percentage of negative sentiment |
referee_start_date | object | The start date for the referee's feedback. |
year | number | |
month | number | |
day | number | |
referee_end_date | object | The end date for the referee's feedback. |
year | number | |
month | number | |
day | number | |
timeline_gaps | array | List of timeline gaps (e.g. Unemployment, travel) |
timeline_gap_1 | object | |
start_date | object | |
year | number | |
month | number | |
day | number | |
end_date | object | |
year | number | |
month | number | |
day | number | |
gap_type | string | Candidates's selection from dropdown list |
description | | Free form text entry provided by candidate |
price | object | The price incurred when the check was requested. |
value | number | Price value. |
currency | string | Credit currency (three letter abbreviation e.g. "AUD") |
earliest_timeline_date | object | The earliest date in the candidate's timeline |
year | number | |
month | number | |
day | number | |
latest_timeline_date | object | The latest date in the candidate's timeline |
year | number | |
month | number | |
day | number | |
url | string | API 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
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
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
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
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
| Attribute | Type | Description |
role | string, required | A string identifying the role for which the candidate is being interviewed for. |
employer | object, optional | Employer 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. |
email | string, optional | Employer's email address. |
candidate | object, required | Details of the candidate. |
first_name | string, required | Candidate's first name. |
last_name | string, required | Candidate's last name. |
email | string, required | Candidate's email address. |
phone | string, required | Candidate's phone number, preferably mobile. |
criterion | object, required | Criterion to be used for the check with values to override. |
id | number, required | ID of the criterion to be used. |
min_years | number | Minimum number of years for this criterion |
min_referees | number, optional | Minimum number of referees to request for the check. |
gap | | Maximum allowed gap between employment histories |
enforce | boolean | Whether to enforce the gap definition. |
unit | string | 'week' or 'days' |
value | number | Number of days or weeks (as per unit) |
note_to_candidate | string, optional | The note that will go in the email to the candidate. |
note_to_referee | string, optional | The note that will go in the email to the referee. |
custom_id | | an optional reference ID which will be returned on the payload and on the webhook updates |
hiring_account | | an 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
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
| Attribute | Type | Description |
role | string, required | A string identifying the role for which the candidate is being interviewed for. |
candidate | object, required | Details of the candidate. |
first_name | string, required | Candidate's first name. |
last_name | string, required | Candidate's last name. |
email | string, required | Candidate's email address. |
phone | string, required | Candidate's phone number, preferably mobile. |
ip_address | string, optional | Candidate's IP address. This is critical for fraud detection. |
criterion | object, required | Criterion to be used for the check with values to override. |
id | number, required | ID of the criterion to be used. |
min_referees | number, optional | Minimum number of referees to request for the check. |
note_to_candidate | string, optional | The note that will go in the email to the candidate. |
note_to_referee | string, optional | The note that will go in the email to the referee. |
referees | array | List of referees for the candidate. |
referee | object | Details of the referee. |
reference_type | number, required | ID of the type of reference. |
first_name | string, required | Referee's first name. |
last_name | string, required | Referee's last name. |
email | string, required | Referee's email address. |
phone | string, required | Referee's phone number, preferably mobile. |
position_referee | string, required | Referee's position at that time. |
position_candidate | string, required | Candidate's position at that time. |
start_date | string, required | Referee start date. |
end_date | string, required | Referee end date. |
company_name | string, required | The 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
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
| Attribute | Type | Description |
role | string, required | A string identifying the role for which the candidate is being interviewed for. |
employer | object, optional | Employer 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. |
email | string, optional | Employer's email address. |
candidate | object, required | Details of the candidate. |
first_name | string, required | Candidate's first name. |
last_name | string, required | Candidate's last name. |
email | string, required | Candidate's email address. |
phone | string, required | Candidate's phone number, preferably mobile. |
ip_address | string, optional | Candidate's IP address. This is critical for fraud detection. |
criterion | object, required | Criterion to be used for the check with values to override. |
id | number, required | ID of the criterion to be used. |
min_referees | number, optional | Minimum number of referees to request for the check. |
note_to_candidate | string, optional | The note that will go in the email to the candidate. |
note_to_referee | string, optional | The note that will go in the email to the referee. |
referees | array | List of referees for the candidate. * Reference types are attached as separate objects in examples below, |
Employment: Employment | object | |
reference_type: 17 | number, required | Employment |
first_name | string, required | Referee's first name. |
last_name | string, required | Referee's last name. |
email | string, required | Referee's email address. |
phone | string, required | Referee's phone number, preferably mobile. |
position_referee | string, required | Referee's position at that time. |
position_candidate | string, required | Candidate's position at that time. |
start_date | string, required | Referee start date. |
end_date | string, required | Referee end date. |
company_name | string, required | The company the referee worked for with the candidate. |
referee | object | Details of the referee. |
reference_type: 23 | number, required | Voluntary |
first_name | string, required | Referee's first name. |
last_name | string, required | Referee's last name. |
email | string, required | Referee's email address. |
phone | string, required | Referee's phone number, preferably mobile. |
start_date | string, required | Referee start date. |
end_date | string, required | Referee end date. |
company_name | string, required | The company the referee worked for with the candidate. |
referee | object | Details of the referee. |
reference_type: 26 | number, required | Academic |
first_name | string, required | Referee's first name. |
last_name | string, required | Referee's last name. |
email | string, required | Referee's email address. |
phone | string, required | Referee's phone number, preferably mobile. |
institution | string, required | The institution the candidate attended with the referee. |
course | string, required | The candidate’s course. |
start_date | string, required | Referee start date. |
end_date | string, required | Referee end date. |
referee | object | Details of the referee. |
reference_type: 27 | number, required | Character |
first_name | string, required | Referee's first name. |
last_name | string, required | Referee's last name. |
email | string, required | Referee's email address. |
phone | string, required | Referee's phone number, preferably mobile. |
relationship | string, required | The referee’s relationship with the candidate. |
start_date | string, required | Referee start date. |
end_date | string, required | Referee end date. |
custom_id | | an 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
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
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
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
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
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
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)
| Attribute | Type | Description |
email | string, required | Email of the line manager. |
language_code | string, required | Language 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
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
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Body
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