Criteria
Criteria are the prerequisites that a reference check must meet before it will be marked as completed. Criteria are created by you, or other users of your company.
List Criteria
|
|
| Method |
GET |
| Path |
/criteria{?search}{?limit}{?page}{?include_partner_criteria} |
This endpoint returns the list of criteria used by your company. If your company does not have any criteria set up, it will return the parent company's criteria as the default, instead.
The pages attribute allows you to link to the current, previous and next pages of the list of criteria.
Request
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
| Name |
Example / default |
Required |
Type |
Description |
search |
"" |
No |
string |
Filter the list of items by searching on name. Default: "" |
limit |
20 |
No |
integer |
Limit the list of items to a certain number. Defaults to 20, maximum can be 100. Default: 20 |
page |
1 |
No |
integer |
The page number in the list of items. Default: 1 |
include_partner_criteria |
False |
No |
boolean |
Includes a list of partner company's criteria |
Response
200 — application/json
{
"pages": {
"total": 5,
"links": {
"this": "/criteria",
"prev": "",
"next": "/criteria?search=""&limit=20&page=2"
}
},
"data": [
{
"id": 150,
"base_id": None,
"name": "5 years and 2 referees with 4 weeks gap",
"min_years": 5,
"min_referees": 2,
"created_on": "2017-11-02 16:28:59.141390",
"created_by": "John Smith",
"note_to_candidate": "note to candidate",
"note_to_referee": "note to referee",
"mappings": [
{
"period_type_name": "Employment",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 1
},
{
"period_type_name": "Academic",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 2
}
],
"url": "/criterion/150"
},
{
"id": 151,
"base_id": 150,
"name": "5 years and 2 referees with 4 weeks gap",
"min_years": 5,
"min_referees": 2,
"created_on": "2017-11-02 16:28:59.141390",
"created_by": "Test Name",
"note_to_candidate": "note to candidate",
"note_to_referee": "note to referee",
"mappings": [
{
"period_type_name": "Employment",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 1
},
{
"period_type_name": "Academic",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 2
}
],
"url": "/criterion/151"
}
],
"partner_criteria": [
{
"id": 152,
"base_id": 153,
"name": "Partner company criteria",
"min_years": 0,
"min_referees": 1,
"mappings": [
{
"period_type_name": "Employment",
"questionnaire_id": 4134,
"questionnaire_title": "Junior (Entry level)"
}
],
"created_on": "2024-05-27T06:33:33Z",
"created_by": "Company Admin",
"note_to_candidate": "partner comp note to candidate",
"note_to_referee": "partner comp note to referee",
"url": "/criterion/152"
}
]
}
401 — application/json
{
"detail": "Authentication credentials were not provided."
}
403
List Reference Types
|
|
| Method |
GET |
| Path |
/reference_types/{?limit}{?page} |
This endpoint returns the list of allowed reference types for each criteria. The developer will need to do a GET on this endpoint
to be able to specify the type_id on the questionnaire mapping upon creating a criterion (read Criterion operations below).
The pages attribute allows you to link to the current, previous and next pages of the list of reference types.
Request
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Parameters
| Name |
Example / default |
Required |
Type |
Description |
limit |
20 |
No |
integer |
Limit the list of items to a certain number. Defaults to 20, maximum can be 100. Default: 20 |
page |
1 |
No |
integer |
The page number in the list of items. Default: 1 |
Response
200 — application/json
{
"pages": {
"total": 1,
"links": {
"this": "/reference_types",
"prev": "",
"next": ""
}
},
"data": [
{
"id": 1,
"name": "Employment",
},
{
"id": 2,
"name": "Academic",
],
}
]
}
401 — application/json
{
"detail": "Authentication credentials were not provided."
}
403
Criterion Operations
Retrieve a Criterion
|
|
| Method |
GET |
| Path |
/criterion/{id} |
Returns information relevant to the criterion, such as minimum number of referees, notes to candidate and referees.
This endpoint returns a 404 response if the criterion is not found, a 403 response if the requesting user does not have the permissions required to view the criterion.
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 criterion. |
Response
200 — application/json
Attributes (object)
| Attribute | Type | Description |
id | number | ID of the criterion |
base_id | number | Base criterion used in creation of this criterion |
name | string | Name of the criterion |
min_years | number | Minimum number of years for this criterion |
min_referees | number | Minimum number of referees for this criterion |
created_on | string | Created date for this criterion |
created_by | string | First name and last name of the user who created this criterion |
note_to_candidate | string | |
note_to_referee | string | |
mappings | array | List of period type and questionnaire mapping for this criterion |
mapping | object | |
period_type_name | string | Name of the period type |
questionnaire_title | string | Title of the questionnaire |
questionnaire_id | number | ID of the questionnaire |
url | string | API endpoint to retrieve this criterion |
Body
{
"id": 150,
"base_id": 120,
"name": "5 years and 2 referees with 4 weeks gap",
"min_years": 5,
"min_referees": 2,
"created_on": "2017-11-02 16:28:59.141390",
"created_by": "Joe Bloggs",
"note_to_candidate": "note to candidate",
"note_to_referee": "note to referee",
"mappings": [
{
"period_type_name": "Employment",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 1
},
{
"period_type_name": "Academic",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 2
}
],
"url": "/criterion/150"
}
401 — application/json
{
"detail": "Authentication credentials were not provided."
}
404
403
Deactivate a Criterion
|
|
| Method |
DELETE |
| Path |
/criterion/{id} |
A criterion can only be deactivated if the requesting user has the permissions required to edit the criterion.
This endpoint returns a 404 response if the criterion is not found, and a 403 response if the requesting user does not have the permissions required to deactivate this criterion.
Once deactivated, this endpoint returns a 200 response.
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 criterion. |
Response
200 — application/json
{
"detail": "Criterion has been deleted"
}
400 — application/json
{
"detail": "Error",
"message": "Some error message"
}
404
403
Create a Criterion
|
|
| Method |
POST |
| Path |
/criterion |
This endpoint creates a new criterion. It returns a 201 response if the request was successful.
The request body mostly follows the same format as the ‘Retrieve a criterion' endpoint but will also require a gap definition.
Gap Definition is the maximum allowed gap between employment histories in 'weeks' or 'days'.
The response body follows the same format as 'Retrieve a criterion' 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 criterion.
Request
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
| Attribute | Type | Description |
name | string | Name of the criterion |
min_years | number | Minimum number of years for this criterion |
min_referees | number | Minimum number of referees for this criterion |
note_to_candidate | string | |
note_to_referee | string | |
gap_definition | object | Maximum allowed gap between employment histories |
unit | string | 'week' or 'days' |
value | number | Number of days or weeks (as per unit) |
questionnaire_type_mappings | array | List of type ids (see section on 'List Reference Types') and questionnaire mapping for this criterion |
mapping | object | |
type_id | number | ID of Reference Type |
questionnaire_id | number | ID of the questionnaire |
url | string | API endpoint to retrieve this criterion |
Body
{
"name": "1 year and 1 referee with no gaps",
"min_referees": 1,
"min_years": 1,
"note_to_candidate": "note to candidate",
"note_to_referee": "note to referee",
"gap_definition:": {
"unit": "weeks",
"value": 4
},
"questionnaire_type_mappings": [
{
"type_id": 17,
"questionnaire_id": 1
}
]
}
Response
201 — application/json
Attributes (object)
| Attribute | Type | Description |
id | number | ID of the criterion |
name | string | Name of the criterion |
min_years | number | Minimum number of years for this criterion |
min_referees | number | Minimum number of referees for this criterion |
created_on | string | Created date for this criterion |
created_by | string | First name and last name of the user who created this criterion |
note_to_candidate | string | |
note_to_referee | string | |
mappings | array | List of period type and questionnaire mapping for this criterion |
mapping | object | |
period_type_name | string | Name of the period type |
questionnaire_title | string | Title of the questionnaire |
questionnaire_id | number | ID of the questionnaire |
url | string | API endpoint to retrieve this criterion |
Body
{
"id": 150,
"name": "1 year and 1 referee with no gaps",
"min_years": 2,
"min_referees": 2,
"created_on": "2017-11-02 16:28:59.141390",
"created_by": "Joe Bloggs",
"note_to_candidate": "note to candidate",
"note_to_referee": "note to referee",
"mappings": [
{
"period_type_name": "Employment",
"questionnaire_title": "Xref Standard Template",
"questionnaire_id": 1
},
],
"url": "/criterion/150"
}
400 — application/json
{
"detail": "Error",
"message": {
"min_years": ["This field is required."],
}
}
401 — application/json
{
"detail": "Authentication credentials were not provided."
}
404
403