Skip to content

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

Headers

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

Headers

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

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

Response

200 — application/json
Attributes (object)
AttributeTypeDescription
idnumberID of the criterion
base_idnumberBase criterion used in creation of this criterion
namestringName of the criterion
min_yearsnumberMinimum number of years for this criterion
min_refereesnumberMinimum number of referees for this criterion
created_onstringCreated date for this criterion
created_bystringFirst name and last name of the user who created this criterion
note_to_candidatestring
note_to_refereestring
mappingsarrayList of period type and questionnaire mapping for this criterion
mappingobject
period_type_namestringName of the period type
questionnaire_titlestringTitle of the questionnaire
questionnaire_idnumberID of the questionnaire
urlstringAPI 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

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

Headers
Authorization: Bearer YOUR_JWT_TOKEN_HERE
Content-Type: application/json
Attributes (object)
AttributeTypeDescription
namestringName of the criterion
min_yearsnumberMinimum number of years for this criterion
min_refereesnumberMinimum number of referees for this criterion
note_to_candidatestring
note_to_refereestring
gap_definitionobjectMaximum allowed gap between employment histories
unitstring'week' or 'days'
valuenumberNumber of days or weeks (as per unit)
questionnaire_type_mappingsarrayList of type ids (see section on 'List Reference Types') and questionnaire mapping for this criterion
mappingobject
type_idnumberID of Reference Type
questionnaire_idnumberID of the questionnaire
urlstringAPI 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)
AttributeTypeDescription
idnumberID of the criterion
namestringName of the criterion
min_yearsnumberMinimum number of years for this criterion
min_refereesnumberMinimum number of referees for this criterion
created_onstringCreated date for this criterion
created_bystringFirst name and last name of the user who created this criterion
note_to_candidatestring
note_to_refereestring
mappingsarrayList of period type and questionnaire mapping for this criterion
mappingobject
period_type_namestringName of the period type
questionnaire_titlestringTitle of the questionnaire
questionnaire_idnumberID of the questionnaire
urlstringAPI 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