Authentication

You will be provided with a subscription key which must be included in the header of all requests made to the API.

All API requests must be made over HTTPS. Any requests made over HTTP will fail.

You will be provided with both Live and Test keys. Requests made with the test key can be used to test our API before going live. Requests made in test-mode will return dummy responses and no credit will be deducted from your account.

# With curl, you can just pass the correct header with each request
curl -H "Authorization: your_api_key"
https://api.verifile.co.uk/vftapi/v2/applicants
            

Errors

Standard HTTP error codes are returned in the case of a failure. 2xx codes indicate a successful message; 4xx codes indicate an error caused by information provided by the client; and 5xx codes indicate an error on Verifile's servers.

Error codes

The following error codes are used:

Error Code Name Meaning
400 Bad Request Malformed request
401 Unauthorized Invalid authorization credentials
422 Unprocessable Entity Validation error
404 Not Found Resource not found
500 Internal Server Error An unexpected error occurred in our API

Error types

Error Code Type Suggestion
400 bad_request: 'The request could not be understood by the server, please check your request is correctly formatted' Ensure your request is in the correct format.
401 authorization_error: 'Authorization error: please re-check your credentials' Ensure you have entered your API key correctly and are using the right key e.g. live or test.
401 unauthorized_request: 'Unauthorized' Ensure you have entered your API key correctly and are using the right key e.g. live or test.
401 user_authorization_error: 'User is not allowed to access API: please recheck your permissions' User is currently 'read only'. You need to contact an Admin to change to 'standard user'. This will enable you to access the API.
404 resource_not_found: 'The resource could not be found' Ensure you have formatted the URI correctly.
422 validation_error: 'There was a validation error on this request' Check the fields property for a specific error message.
422 invalid_reports_names:'Unprocessable Entity' Ensure you have entered the report name in the correct format. View a request example for your chosen Report Type for guidance e.g. see Document Report
422 invalid_check_type_for_variant:'Unprocessable Entity' Only certain variants can be performed on certain checks. See Report Types for guidance
422 failed_check_requirements: 'Check requirements have not been met for this request' Check all required information has been provided and correctly specified. View an example of a check containing your chosen report in Report Types
422 incomplete_checks: 'Check cannot be created as there are other ongoing checks associated with this applicant' A check on an applicant must be completed before another can commence
500 internal_server_error : 'We're sorry, but something went wrong' The server encountered an error, retry the request. If this message is occuring repeatedly contact Client Support

Error object

Attributes Description
id string
A unique identifier for the error. This can be used as a reference for our technical support team
type string
The type of error returned
message string
A human-readable message giving more details about the error type
fields hash
The list of fields which have errors associated with them. Only applies to validation errors
{
  "error": {
    "id": "544f95539648607d03001542",
    "type": "validation_error",
    "message": "",
    "fields": {
      "email": {
        "messages": [
          "invalid format"
        ]
      },
      "name": {
        "messages": [
          "can't be blank"
        ]
      }
    }
  }
}
            

Back to top


Pagination

Requests that return multiple items, e.g. GET v2/applicants, will be paginated to 20 items by default. You can specify further pages using the ?page parameter and specify page size using the ?per_page parameter.

$ curl https://api.verifile.co.uk/vftapi/v2/applicants?page=2&per_page=50
  -H "Authorization: your_api_key"
            

Pagination info is included in the link header. We recommend that you follow these rather than constructing your own URLs. The possible rel values are next, last, first and prev.

The total count of the resource is included in a custom header X-Total-Count.

Link:   <https://api.verifile.co.uk/vftapi/v2/applicants?page=1&per_page=50>; rel="first",
        <https://api.verifile.co.uk/vftapi/v2/applicants?page=4&per_page=50>; rel="last",
        <https://api.verifile.co.uk/vftapi/v2/applicants?page=3&per_page=50>; rel="next"

X-Total-Count: 178
            

Back to top


Testing

Verifile offers a sandbox environment for simulating API requests to help you test your integration before going live. To use the sandbox environment, you will need a test API key when making calls to the API endpoints. Test keys can be found by logging into your developer portal account. If you don't have an account, sign up and we will assign you a test key. Please make sure you are using the correct key, if you want to test rather than make live requests.

Why use a sandbox environment?

You can make all the same API requests in the sandbox environment as you would in the live environment. You will also be notified of check/report statuses changes via your registered webhooks. The key differences between the sandbox and live requests are:

  • Checks are not actually run against real-life databases - as some checks leave fingerprint, it is not advisable to make live checks during testing.
  • Check statuses do not change unless you specifically request for this to be done
  • Checks do not incur any charges
  • Sandbox applicants are isolated from the non-sandbox environment

The main reasons for using the sandbox environment are to:

  • Verify that your system network connectivity is compatible with the Verifile Transitional API
  • Verify you are posting all the required data in the right format
  • Verify you are handling the Verifile Transitional API responses correctly
  • Verify your webhook is working

As check results are pre-determined, the sandbox environment is NOT for:

  • Testing check quality
  • Testing check response time

Environments

Environment Base URL
Staging https://api.verifile.co.uk/vft-staging/v2/{endpoint}
Live https://api.verifile.co.uk/vftapi/v2/{endpoint}

Rate limiting

For sandbox requests, there is currently a rate limit of 100 requests every 10 minutes. When you hit the limit, you will see an HTTP 429 too many requests error. You will be prevented from making further sandbox requests within the one-minute time period.

Back to top


Applicant

Applicant Object

An applicant represents the individual the check is being performed on, they may also be referred to as a candidate. To initiate a check, an applicant must first be created. Applicants can be both retrieved and listed.

Required applicant data

The table below states which applicant parameters are required and the validation in place for each.

Attribute Description Mandatory Notes
id string
The unique identifier for the applicant
No This is provided by Verifile in the response
created_at datetime
The date and time when this applicant was created
No This is provided by Verifile in the response
href string
The URI of this resource
No This is provided by Verifile in the response
title string
The applicant's title.
No Allowed valid values are Mr, Mrs, Miss and Ms
first_name string
The applicant's first name
Yes
middle_name string
The applicant's middle name(s) or initial
No
last_name string
The applicant's surname
Yes
email string
The applicant's email address
Yes
gender string
The applicant's gender.
Yes Allowed values are male and female
dob date
The applicant's date of birth in yyyy-mm-dd format
No If a values is not supplied it will be set to a default value that applicant will have to change when filling in their details
telephone string
The applicant's landline phone number
No
mobile string
The applicant's mobile phone number
No
country string
The country where this applicant will be checked.
Yes This must be a three-letter ISO code e.g. GBR or USA. If not provided the default is GBR.
mothers_maiden_name string
The applicant's mother's maiden name
No
previous_last_name string
The applicant's previous surname
No
nationality string
The applicant's current nationality.
No This must be a three-letter ISO code e.g. GBR or USA
country_of_birth string
The applicant's country of birth.
No This must be a three-letter ISO code e.g. GBR or USA
town_of_birth string
The applicant's town of birth
No
id_numbers list id number
A collection of identification numbers belonging to this applicant
No
addresses list address
The address history of the applicant
No

ID Number

Attribute Description
type string
Type of ID number. Valid values are ssn, social_insurance (e.g. UK National Insurance), tax_id, identity_card and driving_license
value string
Value of ID number
Note that ssn supports both the full SSN or the last four digits. If providing the full SSN the value has to be supplied with dashes in the following format: xxx-xx-xxxx
state_code string
Two letter code of issuing state (state-issued driving licenses only)

Address

Attribute Description
flat_number string
The flat number of this address
building_number string
The building number of this address
building_name string
The building name of this address
street string
The street of the applicant's address. There is a 32-character limit on this field for UK addresses
sub_street string
The sub-street of the applicant's address
town string
The town of the applicant's address
state string
The address state. US states must use the USPS abbreviation (see also ISO 3166-2:US), for example AK, CA, or TX.
postcode string
The postcode or ZIP of the applicant's address. For UK postcode, specify the value in the following format: SW4 6EH
country string
The 3 character ISO country code of this address. For example, GBR is the country code for the United Kingdom
start_date date
The date the applicant started living at this address in yyyy-mm-dd format
end_date date
The date the applicant left this address in yyyy-mm-dd format. If current residence, leave null
{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "Male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": "Johnson",
  "previous_last_name": null,
  "nationality": "USA",
  "country_of_birth": "USA",
  "town_of_birth": "New York City",
  "id_numbers": [
    {
      "type": "ssn",
      "value": "433-54-3937"
    },
    {
      "type": "driving_licence",
      "value": "I1234562",
      "state_code": "CA"
    }
  ],
  "addresses": [
    {
      "flat_number": null,
      "building_name": null,
      "building_number": "100",
      "street": "Main Street",
      "sub_street": null,
      "state": null,
      "town": "London",
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-01-01",
      "end_date": null
    },
    {
      "flat_number": "Apt 2A",
      "building_name": null,
      "building_number": "1017",
      "street": "Oakland Ave",
      "sub_street": null,
      "town": "Piedmont",
      "state": "CA",
      "postcode": "94611",
      "country": "USA",
      "start_date": "2006-03-07",
      "end_date": "2012-12-31"
    }
  ]
}
            

Verifile Additional Validation

The Transitional API is a proxy for the Verifile's main API. This means that any orders placed in this transitional API will be routed through the Verifile Main API before background checks on the applicant can be processed. As a result, at the point the check is placed, the following validation will need to be met.

The applicant's first and last name will need to meet the following validation, as will the middle name (if supplied):

  • Minimum of 2 characters
  • Maximum of 60 characters
  • Any alphabetical character
  • Single spaces are allowed but not as the first or last character
  • Hyphens are allowed but not as the first or last character
  • Single quotes are allowed but not as the first or last character
  • A name can have no more than 3 consecutive characters the same, irrespective of case

The applicant's email address will need to meet the following validation:

  • Maximum 60 characters
  • Must contain 1 @ symbol
  • Must contain at least 1 period after the @ symbol
  • At least 2 characters between the @ symbol and the period
  • At least 1 character before the @ symbol
  • Domain must be registered

Back to top


Applicant Endpoints

Create applicant

Before you create any checks, you need to create an applicant.

Standard checks require the applicant to provide their information using Verifile's candidate portal.

Endpoint

POST https://api.verifile.co.uk/vftapi/v2/applicants

$ curl https://api.verifile.co.uk/vftapi/v2/applicants \
  -H "Authorization: your_api_key" \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=Smith' \
  -d 'gender=male' \
  -d 'dob=2013-02-17' \
  -d 'telephone=02088909293' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR' \
  -d 'addresses[][start_date]=2013-08-10'
            

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "Male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": null,
  "previous_last_name": null,
  "nationality": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "id_numbers": [],
  "addresses": [
    {
      "flat_number": null,
      "building_number": "100",
      "building_name": null,
      "street": "Main Street",
      "sub_street": null,
      "town": "London",
      "state": null,
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-08-10",
      "end_date": null
    }
  ]
}
            

Retrieve applicant

A single applicant can be retrieved by calling this endpoint along with the applicant's unique identifier.

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/applicants/{applicant_id}

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123 \
  -H "Authorization: your_api_key"
            

Update applicant

Allows updating of an applicant's information before any checks are created.

  • Partial updates
  • Addresses and ID numbers present will replace existing ones
  • Same applicant validations to create applicant

Endpoint

PUT https://api.verifile.co.uk/vftapi/v2/applicants/{applicant_id}

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123 \
  -H "Authorization: your_api_key" \
  -X PUT
  -d 'last_name=Daniels' \
  -d 'dob=1990-02-17' \
  -d 'addresses[][building_number]=40' \
  -d 'addresses[][street]=Springfield Rd' \
  -d 'addresses[][town]=Teddington' \
  -d 'addresses[][postcode]=TW11 9AP' \
  -d 'addresses[][country]=GBR'
  -d 'addresses[][start_date]=2016-09-10' \
            

EXAMPLE RESPONSE

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Daniels",
  "gender": "Male",
  "dob": "1990-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": null,
  "previous_last_name": null,
  "nationality": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "id_numbers": [],
  "addresses": [
    {
      "flat_number": null,
      "building_number": "40",
      "building_name": null,
      "street": "Springfield Rd",
      "sub_street": null,
      "town": "Teddington",
      "state": null,
      "postcode": "TW11 9AP",
      "country": "GBR",
      "start_date": "2016-09-10",
      "end_date": null
    }
  ]
}
            

Delete applicant

A single applicant can be deleted by calling this endpoint along with the applicant's unique identifier.

NOTE: only applicants that don't have any checks associated can be deleted. Trying to delete an applicant that has checks associated will result in a validation error.

Endpoint

DELETE https://api.verifile.co.uk/vftapi/v2/applicants/{applicant_id}

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123 \
  -H "Authorization: your_api_key"
  -X DELETE
            

List applicants

All the applicants you have created can be retrieved from this endpoint

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/applicants/

$ curl https://api.verifile.co.uk/vftapi/v2/applicants \
  -H "Authorization: your_api_key"
            

EXAMPLE RESPONSE

{
  "applicants": [
    {
      "id": "1030303-123123-123123",
      "first_name": "John"
      ...
    },
    {
      "id": "1030303-123123-123145",
      "first_name": "Jane"
      ...
    }
  ]
}
            

Back to top

Checks

Check Object

Checks are performed on an applicant. Checks can be created and retrieved.

A check consists of many reports. See reports and report types to learn more.

The check object is used to track the type and status of a check, and contains the nested resource reports.

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "standard",
  "status": "complete",
  "result": "clear",
  "redirect_uri": null;,
  "results_uri": null,
  "download_uri": null,
  "form_uri": "https://secure.verifile.co.uk/jump/9692e6a4-9b2c-4b54-8e82-12eeef07f16d",
  "reports": [
    "1030303-123123-375629",
    "1030303-123123-456789"
  ],
  "tags": [
    "My tag",
    "Another tag"
  ],
  "activity_years": 7,
}
            
Attribute Description
id string
The unique identifier for the check.
created_at timestamp
The date and time at which the check was initiated.
href string
The API endpoint to retrieve the check.
type string
The type of check: standard or express.
status string
The current state of the check in the checking process.
tags list [string]
A list of tags associated with this check.
result string
The overall result of the check, based on the results of the constituent reports.
download_uri string
A link to a PDF output of the check results. Append .pdf to get the pdf file.
form_uri string
A link to the applicant form, if the check is of type standard
redirect_uri string
For standard checks, redirect to this URI when the applicant has submitted their data.
results_uri string
A link to the corresponding results page on the Verifile dashboard
reports list reports expandable
The list of report objects associated with the check.
activity_years int
The minimum number of years of activity the the candidate will have tio provide when filling out their online form. This is used in conjunction with activity reports.

Check status

Status Description
awaiting_applicant We are currently waiting for the applciant to fill out their online form.
on_hold We are currently waiting for you, the client, or the applciant to complete an action to be able to continue with the background screening.
in_progress We are currently processing the check.
complete All reports for the applicant have been completed or withdrawn.

Back to top

Check endpoints

Create check

Checks are initiated using this endpoint.

You can set up a webhook to listen for the results of reports.

Having created the first check, you are allowed to create further checks for the same applicant, as long as the previous check is not still ongoing (i.e. check has been completed, withdrawn or cancelled). You will receive an error message if you try to create a check for an applicant with an ongoing check. Applicant details can be updated between check creations.

ENDPOINT

POST https://api.verifile.co.uk/vftapi/v2/applicants/{applicant_id}/checks

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: your_api_key" \
  -d 'type=standard' \
  -d 'reports[][name]=identity' \
  -d 'reports[][name]=criminal_history' \
  -d 'reports[][variant]=enhanced' \
  -d 'reports[][options][][name]=adults_barred_list' \
  -d 'criminal_history_report_details[JobRoleId]=62' \
  -d 'criminal_history_report_details[place_of_work]=care home' \
  -d 'tags[]=My tag' \
  -d 'tags[]=Another tag'

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: your_api_key" \
  -d 'type=standard' \
  -d 'report_type_groups[]=22' \
  -d 'criminal_history_report_details[JobRoleId]=62' \
  -d 'criminal_history_report_details[place_of_work]=care home' \
  -d 'tags[]=My tag' \
  -d 'tags[]=Another tag'
            

EXAMPLE RESPONSE

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "standard",
  "status": "awaiting_applicant",
  "result": null,
  "results_uri": null,
  "redirect_uri": null,
  "form_uri": "https://secure.verifile.co.uk/jump/9692e6a4-9b2c-4b54-8e82-12eeef07f16d",
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221",
      "breakdown": {},
      "properties": {}
    },
    {
      "id": "6951786-123123-316712",
      "name": "document",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
      "breakdown": {},
      "properties": {}
    }
  ],
  "tags": [
    "My tag",
    "Another tag"
  ],
  "activity_years": null,
}
            

ARGUMENTS

type required
standard must be used, it is the only type supported. See Check Types.
reports optional
Array of Reports being requested for this check.
report_type_groups optional
Array containing ids of the required Report type groups.
criminal_history_report_details optional
Hash containing properties required for basic, standard or enhanced UK criminal history reports. Only required for checks containing these specific reports. See Criminal history report details arguments.
tags optional
Array of tags being assigned to this check. The first tag in this array will be stored in as the purchase order number.
activity_years optional
The minimum number of years of activity the the candidate will have tio provide when filling out their online form. This is used in conjunction with activity reports.
suppress_form_emails ignored
In all cases the candidate will be sent an email with their candidate portal login details. The wording of this email may be customised.
async ignored
Standard checks are by their nature always asynchronous.
charge_applicant_for_check ignored
Assumed to be false in all cases. For more information speak to your Verifile account manager.

Note that either reports or report_type_groups must be specified when creating a check.

REPORT ARGUMENTS

name required
The name of the report type. The possible report types are detailed here. For more information please see our product description.
variant optional
The name of the report type variant, if required.
options optional
Array of Report Options hashes

REPORT OPTIONS ARGUMENTS

name required
The name of the option to be enabled.
options optional
Any Report Options hashes that apply to this option. (Can only be nested to 1 level)

CRIMINAL HISTORY REPORT DETAILS ARGUMENTS

job_role optional
The applicant's job role for which you would like to request a UK criminal history report.*
purpose optional
The purpose for which you would like to request a basic UK criminal history report. If provided, this value must be either employment or other.*
place_of_work optional
The place of work where the applicant will be carrying out their role.
For basic UK criminal history reports the value provided here must be either England, Wales, or Scotland.*
employer_name optional
The name of the employer*
employment_sector optional
The place of work where the applicant will be carrying out their role. For basic UK criminal history reports the value provided here must be one of those listed here.*
JobRoleId optional
The pre-defined job role to be used for standard or enhanced UK criminal history reports.**

*This information is required to be able to conduct basic UK criminal history reports.

**This information is required to be able to conduct standard or enhanced UK criminal history reports.

Our client team can advise you should you have any issues with job roles and any other DBS queries.

List checks

All checks belonging to an applicant can be listed from this endpoint.

GET https://api.verifile.co.uk/vftapi/v2/applicants/{applicant_id}/checks

$ curl https://api.verifile.co.uk/vftapi/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: your_api_key"
            

Back to top


Reports

Report object

The report object contains the state and relevant details of the particular report. The structure of the object is listed below.

The breakdown hash contains the details of the particular report and differs for each report type. The format of the breakdown and properties for each report type is listed below.

{
  "id": "6951786-123123-316712",
  "name": "identity",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "awaiting_data",
  "result": null,
  "sub_result": null,
  "variant": null,
  "options": {},
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}
            
Attribute Description
id string
The unique identifier for the report
created_at timestamp
The date and time at which the report was first initiated
name string
Report type string identifier. See Report Types
href string
The API endpoint to retrieve the report
status string
The current state of the report in the checking process
result string
The result of the report
sub_result string
The sub_result of the report. It gives a more detailed result for document reports only, and will be null otherwise
variant string
Report variant string identifier. Some reports e.g. criminal_history have sub-types, which are identified by this field. These are detailed in Report Types
options string
Report options. Some reports e.g. criminal_history expose additional options. These are detailed in Report Types
breakdown hash
The details of the report. This is specific to each type of report
properties hash
The properties associated with the report, if any

Report status

Status Description
awaiting_data Verifile has made a request to one of its data providers and we are waiting on their reply.
paused Report is paused until you, i.e. the client, complete and action manually in the Verifile portal.
awaiting_approval Report is going through manual review.
complete Report is done.
cancelled The report has been cancelled.

Retrieve report

A single report can be retrieved using this endpoint with the corresponding unique identifier.

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/checks/{check_id}/reports/{report_id}

$ curl https://api.verifile.co.uk/vftapi/v2/checks/8546921-123123-123123/reports/1256879-123123-456789 \
  -H "Authorization: your_api_key"
            

List reports

All the reports belonging to a particular check can be listed from this endpoint.

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/checks/{check_id}/reports

$ curl https://api.verifile.co.uk/vftapi/v2/checks/8546921-123123-123123/reports \
  -H "Authorization: your_api_key"
            

Back to top

Report Types

Criminal History Report

A criminal history report identifies whether an applicant has a criminal record within the United Kingdom.

There are three different variants of criminal history report: basic, standard, and enhanced. Different roles require different levels of check; if you're unsure which type you need try using the DBS Eligibility Tool, or our client support team can advise you on which choice is right for your company and roles.

Verifile requires you to agree job roles for standard and enhanced criminal checks prior to placing orders. If you try and order either standard or enhanced and it cannot map to a live job role, the order will be rejected.

Criminal history reports also require additional details to be specified for us to be able to request data from the record agency. They should be specified when the check is created.

{
  "id": "6951786-123123-316712",
  "name": "criminal_history",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "variant": "standard"
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}
            

Right to Work Report

A right to work report identifies whether an applicant has the right to work within the United Kingdom.

Document requirements

Document requirements for a right to work report are

for UK/EU/EEA (European Economic Area)/Swiss citizens

  • a national identity document (i.e., Passport, UK Biometric Residence Permits, EU/EEA/Swiss National ID card) OR
  • a UK birth certificate, along with an NI document (i.e., NI card itself, government letter displaying the name and the NI number, P45/P60 document)

for citizens of other nationalities

  • a passport, along with a valid UK work visa/work permit page of same passport
{
  "id": "6951786-123123-316712",
  "name": "right_to_work",
  "created_at": "2014-05-23T13:50:33Z",
  "status": "complete",
  "result": "clear",
  "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
  "breakdown": {},
  "properties": {}
}
            

Verifile Reports

Verifile offers over 500 different types of report, all of which are available for you to order through the Transitional API.

To discuss the availability of these additional checks, please speak to your account manager.

You can view all of of your currently available report types by using the report types endpoint.

$ curl GET https://api.verifile.co.uk/vftapi/v2/reporttypes \
  -H "Authorization: your_api_key"
            

Back to top

Webhooks

Verifile provides webhooks to alert you of changes in the status of your resources (i.e., checks and reports). These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the event.

All check/report status changes trigger webhook notifications, even for those that complete instantly.

Sandbox checks and reports also trigger webhook notifications. Your can create and configure webhooks to receive status changes from sandbox, live or both environments.

Webhook endpoints can be registered through the API.

Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response within 10 seconds. Otherwise, we will attempt to resend the notification up to 4 times within the following 12 hours.

Quick tip: for initial testing, you can create a temporary endpoint URL using free hosted services to quickly inspect webhook requests.

Events

The following events will trigger a message to registered webhooks:

Resource Events Description
check check.completed A check has been completed.
report report.awaiting_approval A report has transitioned to the "Awaiting Approval" status.
report report.completed A report has been completed and results are available.

Attributes

Attribute Description
payload hash
The top level element
resource_type string
Indicates the resource affected by this event
action string
The event that triggered this webhook, e.g. report.completed
object hash
The object affected by this event. This will contain an id and an href to retrieve that resource
{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "12345-23122-32123",
      "status": "completed",
      "completed_at": "2014-05-23 13:50:33 UTC",
      "href": "https://api.verifile.co.uk/vftapi/v2/checks/12343-11122-09290/reports/12345-23122-32123"
    }
  }
}
            

Register webhook

Webhook URLs can be registered using this endpoint. By default, webhooks are subscribed to all events, but can be subscribed to a subset using the events array.

Endpoint

POST https://api.verifile.co.uk/vftapi/v2/webhooks

$ curl https://api.verifile.co.uk/vftapi/v2/webhooks \
  -H "Authorization: your_api_key" \
  -d 'url=https://webhookendpoint.url' \
  -d 'enabled=true' \
  -d 'environments[]=live' \
  -d 'environments[]=sandbox' \
  -d 'events[]=report.completed' \
  -d 'events[]=check.completed' \
            

EXAMPLE RESPONSE

{
  "id": "fcb73186-0733-4f6f-9c57-d9d5ef979443",
  "url": "https://webhookendpoint.url",
  "enabled": true,
  "href": "/v2/webhooks/fcb73186-0733-4f6f-9c57-d9d5ef979443",
  "environments": [
    "live",
    "sandbox"
  ],
  "events": [
    "report.completed",
    "check.completed"
  ]
}
            

Arguments

url required
The url that will listen to notifications (must be https).
enabled optional
Determine if the webhook should be active.<br/ > If the enabled parameter is omitted it will be set as true.
environments optional
The environments from which the webhook will receive events.<br/ > Allowed values are "sandbox" and "live".
If the environments parameter is omitted the webhook will receive events from both environments.
events optional
The events that should be published to the webhook.
The supported events are:
"report.completed", "report.withdrawn", "check.completed", "check.started", "check.form_opened", "check.form_completed"<br/ > If the events parameter is omitted all the events will be subscribed.

Retrieve webhook

A single webhook can be retrieved by calling this endpoint along with the webhook's unique identifier.

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/webhooks/{webhook_id}

$ curl https://api.verifile.co.uk/vftapi/v2/webhooks/1030303-123123-123123 \
  -H "Authorization: your_api_key"
            

List webhooks

All the webhooks you have created can be retrieved from this endpoint

Endpoint

GET https://api.verifile.co.uk/vftapi/v2/webhooks/

$ curl https://api.verifile.co.uk/vftapi/v2/webhooks \
  -H "Authorization: your_api_key"
            

EXAMPLE RESPONSE

{
  "webhooks": [
    {
      "id": "dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "url": "https://demo.com",
      "enabled":false,
      "href": "/v2/webhooks/dd0a89e4-d44e-417a-aec4-01137d01ae59",
      "environments": [
        "sandbox"
      ],
      "events": [
        "check.started"
      ]
    },
    {
      "id": "bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "url": "https://demo2.com",
      "enabled": true,
      "href": "/v2/webhooks/bfc727a8-f7bf-4073-b123-ed70a70f58e5",
      "environments": [
        "live"
      ],
      "events": [
        "report.completed",
        "check.completed"
      ]
    }
  ]
}
            

Back to top


Report Type Groups

Report type groups will be created by Verifile when setting up client accounts, and therefore Report Type Group Id numbers will change (from Onfido's) as clients start to use the VFT-API.

To set up or update your report type groups, please contact your Verifile account manager.

The report type group object defines the set of reports to be requested in a check. The structure of the object is listed below.

{
  "id": "8546921-123123-123123",
  "name": "Senior level",
  "group_only": false,
  "report_types": [
    {
      "id": "4566764-567657-234445",
      "name": "identity"
    },
    {
      "id": "2344556-236767-786868",
      "name": "right_to_work"
    },
    {
      "id": "7857345-234234-565345",
      "name": "criminal_history",
      "variant": "basic",
      "options": []
    }
  ]
}
            
Attribute Description
id string
The unique identifier for the group.
name string
The group's name, as specified under your account.
group_only boolean
Always true. If a report type group is ordered, we will assume you want to order all report within this group.
report_types list [object]
A list of objects containing information regarding the different report types included in this group.

Retrieve report type group

A single report type group can be retrieved by calling this endpoint with the group's unique identifier.

ENDPOINT

GET https://api.verifile.co.uk/vftapi/v2/report_type_groups/{report_type_group_id}

$ curl https://api.verifile.co.uk/vftapi/v2/report_type_groups/8546921-123123-123123 \
  -H "Authorization: your_api_key"
            

List report type groups

All report type groups belonging to your account can be listed from this endpoint.

GET https://api.verifile.co.uk/vftapi/v2/report_type_groups

$ curl https://api.verifile.co.uk/vftapi/v2/report_type_groups \
  -H "Authorization: your_api_key"
            

Back to top


Job Roles

A job role ID is required when placing a standard or enhanced Criminal Record report. This should be supplied in the criminal history report details arguments.

Job roles must be pre-approved, prior to placing an check and are bespoke to each client and their needs.

You can GET a list of available job roles using the job roles endpoint.

A list of job roles can be retrieved by calling this endpoint.

ENDPOINT

GET https://api.verifile.co.uk/vftapi/v2/jobroles

$ curl https://api.verifile.co.uk/vftapi/v2/report_type_groups/8546921-123123-123123 \
  -H "Authorization: your_api_key"
            

EXAMPLE RESPONSE

[
    {
        "id": 1290,
        "roleTitle": "Engineer in Fake hospital",
        "roleCheckType": "Standard",
        "workingWithVulnerableAdults": false,
        "workingWithChildren": false,
        "workingFromHome": false,
        "vulnerableAdultsInWorkEnvironment": true,
        "childrenInWorkEnvironment": true,
        "isVolunteer": false
   }
]