Verifile API Documentation

This documentation is under review and is subject to change at any time

The Verifile API exists so that you can build integrations between your system and Verifile's background screening platform.

Verifile's API will integrate easily with any system that can make REST API calls. You might be using an Applicant Tracking System, or a bespoke in-house system. Verifile's API provides you with end points for

Creating orders for background screening checks
Querying the status of an order, at any time
Retrieving the data acquired for any check, at any time
Registering webhooks to be notified of updates
Obtaining a consolidated Final Report

Use the links in the sidebar to browse topics of interest, or jump right in to code using the quick-start.

Quick start

Place an order

Two identifiers are required to authenticate; a subscription key and a Verifile user id.

Request body

Order details are supplied as a JSON body.

Complete example in C#

This is a complete example of using the API to create an order.

A few things to note -

Examples are shown in C# and use Verifile's sandbox (testing) environment with a Demo account.
The authentication keys are real - you can copy/paste this code and expect it to work.
The /orders/candidateentry endpoint creates what we call a candidate entry order. This is a type of order where the candidate will be invited to supply all the necessary information using Verifile's web portal. The other type of order is client entry, where all this information is provided in one go, when order is placed.
Once signed up you will take control of your own unique Verifile user id and authentication keys.
Similarly, once signed up, you'll be able to log in to Verifile's web portal to further customise and set up your account.
Don't forget that JSON is case-sensitive.

About

Verifile's API follows REST design principles. It accepts standard HTTP verbs, JSON request bodies, and it returns JSON responses along with standard HTTP response codes.

To start using the API, you can use the Demo account. When you're ready to begin building your integration you should switch to the keys found in your individual account. You'll be able to manage your own keys, changing them if needed, by logging in to your API account.

Do note that the orders created using the demo account will be periodically deleted (weekly or more often) so you should not rely on this account in any way. It's just for demonstration purposes. Similarly, you should not send any confidential information using the Demo account.

Sandbox

The Sandbox is a safe place for experimentation and testing.

It's what we recommend when you first start building your integration with our API.

It's a copy of Verifile's live system, including the API and the web portal. It's just like the real thing, but without any live data (unless you send some, which you shouldn't).

The Sandbox has some automation built into it that will ensure certain checks are processed and move through statuses as if they were being processed by our operations team.

Orders created in the sandbox are free of charge, you won't be invoiced for them.

Similarly, none of these orders will be visible to Verifile's operations team.

Apart from the restriction of not sending any real candidate data, you're free to use the Sandbox as you wish. Do get in touch if we can help with your integration and testing scenarios.

Authentication

Authentication headers

To authenticate you must provide two headers with each request.

Ocp-Apim-Subscription-Key is your individual, secret key. It controls access to your account, and to the data stored against your account. For this reason it must not be shared outside your organisation, and best practice would be to store this key securely in your production environment, limiting access to those who need it.

If at any time you wish to change the key you may do so via your developer portal account. You'll actually find two keys in your account, and either key may be used at any time. The idea behind two keys is that you can use the second key while regenerating the first key. This way you can avoid any interruption in your production service while changing keys.

In conjunction with your secret key, your VerifileUserId identifies which Verifile user account will be used to place the order. This user account will be associated with a company account, which in turn might be a subsidiary of a parent company account.

You will receive your VerifileUserId by email once your account has been created.

Account Setup

The process of setting up an account is very simple.

If you just want to try the API you can initially use the Demo account.
When you're ready for more serious testing and integration you should request your own account by using the sign-up form.
An account manager will be in touch to ensure we understand your integration goals, so that we can correctly configure your account.
Once your account has been set up we will send your Verifile User Id by email, and you'll be able to test and develop your integration with our system.
Depending on your company's hierarchy, we may also send you Subsidiary User Ids
We will work with you to ensure your integration for certain checks (mainly criminal checks ordered in client-entry mode) is legally compliant. Be aware that we'll ask for evidence (e.g. screen shots) of your integration in these cases.
If you have questions please contact us by email at api@verifile.co.uk

How to...

This section contains cookbook-style examples for quick reference.

How to create an order

Candidate-entry order

Client-entry order

If the order is successfully placed, you will receive a 201 (created) HTTP status code and a response body containing the new order number.

For candidate-entry orders, an email will be sent to the candidate, inviting them to use Verifile's portal.

Depending on account preferences, an email may also be sent to the account holder, confirming the order.

How to order a package

Ordering a package is simply a matter of specifying the package name along with the usual data.

Package Order, full JSON body

How to get the status of an order

{
    "id": 8200,
    "candidateFullName": "Mr Paul Smyth",
    "orderStatus": "Awaiting candidate entry",
    "checkStatuses": [
        {
            "checkName": "AcademicQualificationUK",
            "checkStatusDescription": "Awaiting candidate entry"
        },
        {
            "checkName": "AcademicQualificationUK",
            "checkStatusDescription": "Awaiting candidate entry"
        },
        {
            "checkName": "AcademicQualificationUK",
            "checkStatusDescription": "Awaiting candidate entry"
        },
        {
            "checkName": "AcademicQualificationUK",
            "checkStatusDescription": "Awaiting candidate entry"
        }
    ]
}

How to retrieve a Final Report

How to register a webhook to be notified of status changes

How to get a list of all open orders

An order is considered open when its status is not cancelled or completed.

How to place an order under a subsidiary account

Specify the subsidiary using the VerifileSubsidiaryOrganisationId header.

Note that

VerifileSubsidiaryOrganisationId is an optional header, required only when the user's company account is different to the desired subsidiary account
The user's account must belong to the desired subsidiary, or to a parent company.
The user must have permission to place orders for the desired subsidary
Users within a subsidiary may not place orders for parent or sibling companies

How to get a list of packages that may be ordered

Here's an example of a response where just one package is available.

Concepts

This section covers concepts and terminology that will help you better understand how Verifile's API operates.

Checks and Packages

A check is a request to carry out some kind of background screening. An order may request one or more checks, for example a UK Credit Check.
A package is a convenient way of ordering a predefined set of specific checks, for example a UK Credit Check AND 3 Years Employment History.

Client-entry and Candidate-entry Orders

Verifile makes a distinction between two types of order:

The first type is called candidate-entry. This is where, once an order has been placed by the client, the candidate will be invited (usually by email) to log in to Verifile's web portal and enter their personal details, as required to complete the checks.

The second type is called client-entry. This is where the client will supply all of the necessary information at the same time as placing the order. For client-entry orders, the candidate may never contact Verifile directly.

Final Report

An order will contain one or more checks. When all of those checks are concluded, the data collected along with results of the checks are shown in the Final Report. Typically the final report is available as PDF.

Interim Report

This report is the same as Final Report but it is available at any time, including before all checks (in the order) are concluded.

API Reference

Field Types

Throughout the API documentation you will find references to various Field Types that are described in this section.

The most important of these field types is the Candidate Object. It's referenced in every order.

Candidate Object

Field name is 'Candidate'

Field	Type	Description
CurrentName	Current Name Object	Field Validation This field is mandatory
PreviousNames	Previous Names Object	Field Validation This field is optional Mandatory for client-entry orders, disallowed for candidate-entry orders
AddressList	Address List Object	Field Validation This field is optional Mandatory for client-entry orders, disallowed for candidate-entry orders
PersonalInfo	Personal Information Object	Field Validation This field is mandatory
Identity	Identity Object	Field Validation This field is optional Mandatory for client-entry orders, disallowed for candidate-entry orders

Current Name Object

The Current Name object is used to supply the current name of a person, usually the candidate.

Field	Type	Description
Title	String	The person's title Field Validation Values for this field must be from the title value set. This field is optional Mandatory for client-entry orders
FirstName	String	The person's first name Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory
MiddlesNames	String	The person's middle names Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is optional
LastName	String	The person's last name Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory
IsFromBirth	Boolean	Field Validation This field is optional Mandatory for client-entry orders
KnownFromDate	String (yyyy-mm-dd)	Field Validation This field is optional Mandatory for client-entry orders if IsFromBirth is false, disallowed for candidate-entry orders

Example of a CurrentName for a client-entry order

"CurrentName": {
  "Title": "Mr",
  "FirstName": "John",
  "MiddleNames": "Alan",
  "LastName": "Smith",
  "IsFromBirth": true,
  "KnownFromDate":  null
}

Example of a CurrentName for a candidate-entry order

"CurrentName": {
  "Title": "Mr",
  "FirstName": "John",
  "MiddleNames": "D'Michael",
  "LastName": "Smith"
}

Previous Names Object

Field name is 'PreviousNames'

Field	Type	Description
Title	String
FirstName	String (Name)	Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory
MiddleNames	String (Name)	Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is optional
LastName	String (Name)	Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory
KnownFromDate	String (yyyy-mm-dd)	Date that the candidate started using this name Field Validation This field is optional Mandatory if IsFromBirth is false
KnownToDate	String (yyyy-mm-dd)	Date that the candidate stopped using this name Field Validation This field is mandatory

Example of PreviousNames Object

"PreviousNames": [
  {
    "IsFromBirth": false,
    "KnownFromDate": "1980-01-01",
    "KnownToDate": "1990-01-01",
    "Title": "Miss",
    "FirstName": "Chantelle",
    "MiddleNames": "Barrett",
    "LastName": "Jones",
  },
  {
    "IsFromBirth": true,
    "KnownFromDate": null,
    "KnownToDate": "1980-01-01",
    "Title": "Miss",
    "FirstName": "Chantelle",
    "MiddleNames": "Barrett",
    "LastName": "Higgins",
  }
]

Generic Name Object

The Generic Name object is used to supply the name of a person, for example the name of a contact.

Field	Type	Description
Title	String	The person's title Field Validation Values for this field must be from the title value set. This field is optional
FirstName	String	The person's first name Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory
MiddlesNames	String	The person's middle names Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is optional
LastName	String	The person's last name Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is mandatory

Example

Here is an example of using generic name for the field CheckAcademicContactName.

"CheckAcademicContactName": {
    "Title": "Mr",
    "FirstName": "John",
    "MiddleNames": "Francis",
    "LastName": "Smith"
}

Generic Address Object

The Generic Address object is used to supply addresses throughout the API.

Field	Type	Description
PoBoxNumber	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 250 characters This field is optional
BusinessName	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 250 characters This field is optional
FlatNumber	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is mandatory
HouseNumber	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is mandatory
HouseName	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 60 characters This field is mandatory
StreetName	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 60 characters This field is mandatory
Locality	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional
Town	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is mandatory
County	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional
State	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 30 characters This field is optional
Postcode	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is mandatory
Country	String	Field Validation Values for this field must be from the country value set. This field is optional Mandatory for some checks (refer to check documentation)

Example address

"Address": {
  "PoBoxNumber": "PO Box 789",
  "BusinessName": "My Business",
  "FlatNumber": "6b",
  "HouseNumber": "999",
  "HouseName": "House View",
  "StreetName": "Gold Furlong",
  "Locality": "Marston Moretaine",
  "Town": "Bedford",
  "County": "Bedfordshire",
  "State": "England",
  "Postcode": "MK43 0EG",
  "Country": "GB"
}

Personal Information Object

Field	Type	Description
MobilePhone	Telephone Object
HomePhone	Telephone Object
Gender	String	Field Validation Values for this field must be from the gender value set. This field is optional Mandatory for client-entry orders
DateOfBirth	String (yyyy-mm-dd)	Field Validation This field is mandatory
PurchaseOrderNumber	String	Your purchase order reference Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional
OtherReference	String	An optional reference to use if helpful to you Field Validation The minimum length of this field is 1 characters The maximum length of this field is 128 characters This field is optional
PositionAppliedFor	String	The job role that the candidate has applied for Field Validation The minimum length of this field is 1 characters The maximum length of this field is 60 characters This field is optional
ApplicantNotes	String	Any additional notes pertinent to the order Field Validation The minimum length of this field is 1 characters The maximum length of this field is 1024 characters This field is optional
FSAApproved	Boolean	Indicates whether the candidate is FCA/PRA approved
HasValidDrivingLicense	Boolean	Indicates whether the candidate has a valid driving licence Field Validation This field is optional Disallowed for candidate-entry orders
ApplicantType	String	Field Validation Values for this field must be from the applicanttype value set. This field is optional Mandatory for client-entry orders
CurrentNationality	String	Indicates the applicant's current nationality Field Validation Values for this field must be from the country value set. This field is optional
CandidateEmail	String (Email address)	Field Validation This field is optional Mandatory for candidate-entry orders
BirthCertificationNumber	Boolean	The candidate's birth certificate number Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional Disallowed for candidate-entry orders
MotherMaidenName	String (Name)	The candidate's mother's maiden name Field Validation This field is optional Disallowed for candidate-entry orders
NationalityAtBirth	String	The candidate's nationality at birth Field Validation Values for this field must be from the country value set. This field is optional Disallowed for candidate-entry orders
CountryOfBirth	String	The country the candidate was born in Field Validation Values for this field must be from the country value set. This field is optional Disallowed for candidate-entry orders
TownOfBirth	String	The town the candidate was born in Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional Disallowed for candidate-entry orders
VisaNationality	String	The candidate's visa nationality Field Validation Values for this field must be from the country value set. This field is optional Disallowed for candidate-entry orders
BirthCertificateCountry	String	The candidate's birth certificate issuing country Field Validation Values for this field must be from the country value set. This field is optional Disallowed for candidate-entry orders
EUNationalIdCardCountry	String	The candidate's EU ID card issuing country Field Validation Values for this field must be from the country value set. This field is optional Disallowed for candidate-entry orders

Additional notes

If HasValidDrivingLicense is true then the candidate must supply a valid driving licence
CurrentNationality is mandatory if the candidate doesn't have a valid passport.
CurrentNationality is disallowed if the candidate has a valid passport.
Criminal Record (Basic Disclosure Scotland) checks require the following personal information fields
- MotherMaidenName
- NationalityAtBirth
- CountryOfBirth
- TownOfBirth
- VisaNationality
- BirthCertificateCountry
- EUNationalIdCardCountry

Example of personal information supplied for a candidate-entry order

"PersonalInfo": {
  "MobilePhone": {
    "PhoneNumber": "077777777777",
    "CountryCode": "CN"
  },
  "HomePhone": {
    "PhoneNumber": "01111111111",
    "CountryCode": "CN"
  },
  "Gender": "Male",
  "DateOfBirth": "1992-09-28",
  "PurchaseOrderNumber": "ABC123",
  "OtherReference": "ABC123",
  "PositionAppliedFor": "Engineer",
  "ApplicantNotes": "Candidate is on holiday for 2 weeks",
  "FSAApproved": false,
  "ApplicantType": "Candidate",
  "CandidateEmail": "demo@example.com"
}

Example of personal information supplied for a client-entry order

"PersonalInfo": {
  "MobilePhone": {
    "PhoneNumber": "077777777777",
    "CountryCode": "CN"
  },
  "HomePhone": {
    "PhoneNumber": "01111111111",
    "CountryCode": "CN"
  },
  "Gender": "Male",
  "DateOfBirth": "1992-09-28",
  "PurchaseOrderNumber": "ABC123",
  "OtherReference": "ABC123",
  "PositionAppliedFor": "Engineer",
  "ApplicantNotes": "Candidate is on holiday for 2 weeks",
  "FSAApproved": false,
  "HasValidDrivingLicense": true,
  "ApplicantType": "Candidate",
  "CurrentNationality": "CN",
  "CandidateEmail": "demo@example.com",
  "BirthCertificationNumber": "225197",
  "MotherMaidenName": "Maiden",
  "NationalityAtBirth": "CN",
  "CountryOfBirth": "CN",
  "TownOfBirth": "Beijing",
  "BirthCertificateCountry": "CN"
}

Telephone Object

Field	Type	Description
PhoneNumber	String (telephone number)	Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CountryCode	String	Field Validation Values for this field must be from the country value set. This field is optional

Examples

    "MobilePhone": {
        "PhoneNumber": "077777777777",
        "CountryCode": "CN"
    },
    
    "HomePhone": {
        "PhoneNumber": "01111111111",
        "CountryCode": "CN"
    }

Address List Object

An address list is an array of Address Objects

Field	Type	Description
Address	Address Object	Field Validation This field is mandatory
IsCurrentAddress	Boolean	Field Validation This field is mandatory
DateMovedToThisAddress	String (yyyy-mm-dd)	The date that the candidate moved to this address Field Validation This field is mandatory
DateLeftThisAddress	String (yyyy-mm-dd)	The date that the candidate left this address Field Validation This field is optional Mandatory if 'IsCurrentAddress' is false

Example

"AddressList": [
  {
    "Address": {
      "BusinessName": "The Business",
      "FlatNumber": "6b",
      "HouseNumber": "999",
      "HouseName": "House View",
      "StreetName": "Gold Furlong",
      "Locality": "Marston Moretaine",
      "Town": "Bedford",
      "County": "Bedfordshire",
      "State": "England",
      "Postcode": "MK43 0EG",
      "Country": "GB"
    }
    "DateMovedToThisAddress": "2014-05-05",
    "DateLeftThisAddress": null,
    "IsCurrentAddress": true
  }
]

Identity Object

Field name is 'Identity'

Field	Type	Description
Passport Object	Passport Document Object
Driving Document	Driving Document Object
National Insurance or Overseas Identity Document	National Insurance Document Object

Example of an Identity Object

"Identity": {
  "PassportDocument": {
    "PassportIssuingCountry": "123456789",
    "PassportNumber": "GB",
    "PassportIssueDate": "2014-01-01",
    "PassportExpiryDate": "2023-12-31"
  },
  "DrivingDocument": {
    "DriverLicenseType": "Photo",
    "DriverLicenseIssuingCountry": "GB",
    "DriverLicenseNumber": "Smith608292JA9UC",
    "DriverLicenseDate": "1978-12-29"
  },
  "NationalInsuranceNumberDocument": {
    "OverseasIdentityNumber": {
      "IssuingCountry": null,
      "IdentityNumber": null
    },
    "NationalInsuranceNumber": "JR123456A"
  }
}

Passport Document Object

Field name is 'PassportDocument'

Field	Type	Description
PassportIssuingCountry	String	The country that issued the candidate's passport Field Validation Values for this field must be from the country value set. This field is mandatory
PassportNumber	String	Field Validation This field is mandatory UK passports must be 9 digits
PassportIssueDate	String (yyyy-mm-dd)
PassportExpiryDate	String (yyyy-mm-dd)

Example of a Passport Document Object

  "PassportDocument": {
    "PassportIssuingCountry": "123456789",
    "PassportNumber": "GB",
    "PassportIssueDate": "2014-01-01",
    "PassportExpiryDate": "2023-12-31"
  }

Driving Document Object

Field name is 'DrivingDocument'

Field	Type	Description
DriverLicenseType	String	Field Validation Values for this field must be from the licencetype value set. This field is optional
DriverLicenseIssuingCountry	String	Field Validation Values for this field must be from the country value set. This field is optional
DriverLicenseNumber	String
DriverLicenseDate	String (yyyy-mm-dd)	Issued date Field Validation This field is mandatory

Example of a Driving Document Object

  "DrivingDocument": {
    "DriverLicenseType": "Photo",
    "DriverLicenseIssuingCountry": "GB",
    "DriverLicenseNumber": "Smith608292JA9UC",
    "DriverLicenseDate": "1978-12-29"
  }

National Insurance Number Document Object

Field name is 'NationalInsuranceNumberDocument'

Field	Type	Description
NationalInsuranceNumber	String	Field Validation The minimum length of this field is 8 characters The maximum length of this field is 9 characters This field is optional
OverseasIdentityNumber	Overseas Identity Number Object

Example of a National Insurance Number Document Object

  "NationalInsuranceNumberDocument": {
    "OverseasIdentityNumber": {
      "IssuingCountry": null,
      "IdentityNumber": null
    },
    "NationalInsuranceNumber": "JR123456A"
  }

Overseas Identity Number Object

Field name is 'OverseasIdentityNumber'

Field	Type	Description
IssuingCountry	String	Field Validation Values for this field must be from the country value set. This field is optional
IdentityNumber	String	Field Validation The minimum length of this field is 1 characters The maximum length of this field is 97 characters This field is optional

Example of an Overseas Identity Number Object

    "OverseasIdentityNumber": {
      "IssuingCountry": null,
      "IdentityNumber": null
    }

Value Sets

Valuesets are used to constrain data to a specified list. Throughout this documentation you will see reference to value set keys, for example country. This tells you that you may only specify a value that exists in the country value set.

GET metadata/valuesets

Returns a list of all valuesets.

Sample Response

{
"valueSets": [
{
"id": "title",
"description": "List of titles"
},
{
"id": "gender",
"description": "List of genders"
},
{
"id": "country",
"description": "List of 2 letter country codes (ISO 3166)"
},
{
"id": "fcapraapproval",
"description": "FCA/PRA approved values"
},
{
"id": "driverlicensetypes",
"description": "Driving licence types"
},
{
"id": "applicanttype",
"description": "Lists the different applicant types for order submission"
},
{
"id": "orderreportlayouts",
"description": "Lists the final report format options"
},
{
"id": "dbsjobroles",
"description": "DBS Job Roles"
},
{
"id": "dbscandidatesconsentforcertificateaccess",
"description": "Candidate's consent to allow 3rd party to access DBS electronic certificate"
},
{
"id": "dbscheckpurpose",
"description": "DBS Check's purpose"
},
{
"id": "dbsemploymentsector",
"description": "DBS check's Employment Sector"
},
{
"id": "dbspapercertificatedestination",
"description": "DBS check's paper certificate destination when chosen one"
},
{
"id": "dbsidentitydocuments",
"description": "DBS Identity Documents"
},
{
"id": "dynamicidentitydocuments",
"description": "Documents that can be used in conjunction with various checks"
},
{
"id": "dbsacceptabledocuments",
"description": "Filtered set of DBS Identity Documents"
},
{
"id": "regulatedauthoritycodes",
"description": "ID codes for the regulatory authorities used in regulated references and returned in packages"
},
{
"id": "webhookevents",
"description": "Webhook event types"
},
{
"id": "cifasworkingmembers",
"description": "Cifas Working Members"
},
{
"id": "filetypes",
"description": "List of acceptable file types"
},
{
"id": "documentsides",
"description": "The valid sides of a document"
},
{
"id": "postofficeconfigurations",
"description": "Post Office configurations"
},
{
"id": "postofficedocumenttypes",
"description": "Post Office document types"
},
{
"id": "refinements",
"description": "List of Refinement options"
},
{
"id": "proofofresidentialaddress",
"description": "List of document proofs of residential address for Disclosure Scotland checks"
},
{
"id": "proofofidentity",
"description": "List of document proofs of candidate's identity for Disclosure Scotland checks"
},
{
"id": "employmentstatus",
"description": "List of employment statuses for employment checks"
},
{
"id": "employmentcontactemployer",
"description": "Options for how soon Verifile can contact the employer for employment checks"
},
{
"id": "selfemploymentstatus",
"description": "Self employment status values for employment checks"
},
{
"id": "employmentreasonforleaving",
"description": "Candidates reason for leaving the employer for employment checks"
},
{
"id": "membershipstatus",
"description": "List of Membership Statuses"
}
]
}

Get values for a valueset

GET metadata/valuesets/{id}/values

Returns a description and lists values of the valueset.

Sample response for valueset `title`

{
"valuesInSet": [
{
"value": "Mr"
},
{
"value": "Ms"
},
{
"value": "Mrs"
},
{
"value": "Miss"
},
{
"value": "Dr"
},
{
"value": "Professor"
},
{
"value": "Baron"
},
{
"value": "Baroness"
},
{
"value": "Brigadier"
},
{
"value": "Canon"
},
{
"value": "Captain"
},
{
"value": "Duchess"
},
{
"value": "Duke"
},
{
"value": "Esq"
},
{
"value": "Father"
},
{
"value": "Hon"
},
{
"value": "Inspector"
},
{
"value": "Lady"
},
{
"value": "Lord"
},
{
"value": "LtCol"
},
{
"value": "Major"
},
{
"value": "MostRever"
},
{
"value": "Pastor"
},
{
"value": "Rabbi"
},
{
"value": "RevDr"
},
{
"value": "Reverend"
},
{
"value": "RtReveren"
},
{
"value": "Sir"
},
{
"value": "Sister"
},
{
"value": "SquadronL"
},
{
"value": "WgCdr"
}
]
}

Order Statuses

You can get the status of an order with

GET /orders/{orderId}/status

The order status will be returned in OrderState.StateDescription and will be one of the following values.

Status	Open or Closed
Awaiting Candidate Entry	Open
Application	Open
Information required	Open
Processing	Open
Quality checking	Open
Completed	Closed
Cancelled	Closed

Orders will generally move through these statuses in the order shown, but it is possible for an order to move back to a previous status depending on the situation.

Validation

You can optionally use these methods to validate your JSON body before attempting to create an order.

POST /orders/candidateentry/validate

Example Request - Candidate entry

Example Response - Candidate entry

Or for client-entry

POST /orders/cliententry/validate

Example Request - Client entry

Example Response - Client entry

POST /orders/cliententry/validate

If the JSON is malformed then you get HTTP 400 (bad request).

If the JSON is a well-formed and valid the response will be HTTP 200 (OK) and contain isValid:true in the response body.

If the JSON is well formed but invalid then you will get HTTP 200 (OK) and contain isValid:false along with validation error messages.

Packages

A package is a preselected collection of checks, identified by an Id. Packages must be configured by your account manager.

You can get a list of packages available for your account with

GET /metadata/packages

The response will contain an array of objects which have an Id, name and the checks that the package contains. If no packages are available then an empty list will be returned.

If an ID of a package is known, then passing the ID as a parameter will show just details of that package.

GET /metadata/packages/{{package id}}

Packages apply only for candidate-entry orders.

Attachments

POST /attachments

Certain checks require a supporting document or documents to be uploaded with the order. This could be a signed form or proof of identification. See the check specific documentation to find out which document is required for each check, if any. During the processing of an order, Verifile might upload documents to support the final report as evidence.

Note that it is possible to upload files to an order using the Verifile Web Application, aside from using the API. This can be done by both candidate and client users.

Upload attachment

POST /attachments

To upload an attachment to an order, you need to provide the following parameters:

Fields

Field	Type	Description
fileToken	String (UUID)	Uniquely identifies the file.It is not possible to upload more than one file with the same fileToken Field Validation This field is mandatory
orderId	String	The Id of the order to associate with the file Field Validation This field is mandatory
fileName	String	The name of the file including the file extension Field Validation This field is mandatory
description	String	An optional field you can use to provide context for the uploaded file

The body will contain the byte string of the file.

If the upload is successful, the same values are returned in the response along with a Checksum, which is a MD5 hash of the file.

Attachment restrictions

We accept a limited number of file types and sizes. This endpoint lists these restrictions.

An example response from this endpoint

Get Attachment Info

GET /attachments?orderId={{id}}

If the order has any attachments, then they will be listed as an array containing:

fileToken
fileName
fileDescription
orderId
checksum

Downloading an attachment

To download an attachment, provide the unique fileToken of the file as a parameter:

GET /attachments/download?fileToken={{token}}

The response body will be a byte string of the file requested.

Check Types

GET /metadata/checktypes

Lists all the types of checks you can order.

The response will include

Id (the CheckType)
Name of the check
The maximum number that may be ordered in a single order

You can limit results to only Client-entry or only Candidate-entry with the optional query string argument isCandidateEntry=False or isCandidateEntry=True.

You can also limit results to one specific check type with for example

GET /metadata/checktypes/UKCreditCheckEquifax

Sample response

{
"checkTypes": [
{
"name": "UK Credit Check (Equifax)",
"id": "UKCreditCheckEquifax",
"parameters": {
"number": "1"
}
},
{
"name": "UK Credit Check (Experian)",
"id": "UKCreditCheckExperian",
"parameters": {
"number": "1"
}
},
{
"name": "UK ID/AML Check (UK AML)",
"id": "UKIDAMLCheckUKAML",
"parameters": {
"number": "1"
}
},
{
"name": "UK ID/AML Check (UK ID)",
"id": "UKIDAMLCheckUKID",
"parameters": {
"number": "1"
}
},
{
"name": "UK Criminal Record (Basic, Scotland)",
"id": "UKCriminalRecordBasicScotland",
"parameters": {
"number": "1"
}
},
{
"name": "UK Criminal Record (Basic, England & Wales)",
"id": "UKCriminalRecordBasicEnglandWales",
"parameters": {
"number": "1"
}
},
{
"name": "UK Criminal Record (Standard, England & Wales)",
"id": "UKCriminalRecordStandardEnglandWales",
"parameters": {
"number": "1"
}
},
{
"name": "UK Criminal Record (Enhanced, England & Wales)",
"id": "UKCriminalRecordEnhancedEnglandWales",
"parameters": {
"number": "1"
}
},
{
"name": "MOT and Insurance (UK)",
"id": "MOTandInsuranceUK",
"parameters": {
"number": "10"
}
}
]
}

DBS Document Helper

The document helper endpoint is designed to make it easier for you to

Comply with DBS standard when carrying out the in-person (face to face) meeting with the candidate.
Choose which documents to view to confirm the candidate's identity.
Let us know which documents you have seen when confirming the candidate's identity.

The document helper endpoint takes 3 arguments depending on what DBS check you have selected.

The response will be 4 lists/groups of documents that the candidate can use to prove their identity.

GET /metadata/valuesets/dbsacceptabledocuments/values?nationality=GB&PurposeOfCheck=Paid Work in UK

Basic criminal checks require you to provide the candidate's nationality (2 letter ISO code) and the purpose of check.

For basic criminal checks you must supply at least two different identity documents.

At least one document must be from one of the lists of primary documents. The other can be from any other group.

If the candidate cannot supply a document from the primary group, at least three documents must be supplied with at least one document coming from the secondary group.

The documents selected must confirm the candidate's name, address and date of birth.

Sample response

{
    "primary": [
        {
            "id": "Current_Valid_Passport",
            "description": "Current and valid passport (any country)"
        },
        {
            "id": "Biometric_Residence_Permit",
            "description": "Biometric residence permit (UK only)"
        },
        {
            "id": "Current_Driving_Licence",
            "description": "Current driving licence photocard (UK, Isle of Man, Channel Islands and EEA only, Full or provision)"
        },
        {
            "id": "Birth_Certificate_At_Birth",
            "description": "Birth certificate – issued within 12 months of birth (UK, Isle of Man and Channel Islands)"
        },
        {
            "id": "Adoption_Certificate",
            "description": "Adoption certificate (UK and Channel Islands)"
        }
    ],
    "primary1a": null,
    "secondary": [
        {
            "id": "Current_Driving_Licence_NonUk",
            "description": "Current and valid driving licence photocard - (any country outside the EEA, excluding Isle of Man and Channel Islands, Full or provisional)"
        },
        {
            "id": "Current_Driving_Licence_Old_Style",
            "description": "Current and valid driving licence (Old style paper version issued before 1998) - (UK, Isle of Man, Channel Islands and EEA only, Full or provisional)"
        },
        {
            "id": "Birth_Certificate_After_Birth",
            "description": "Birth Certificate - issued after the time of birth (UK, Isle of Man and Channel Islands only)"
        },
        {
            "id": "Marriage_Civil_Partnership_Certificate",
            "description": "Marriage / Civil Partnership Certificate (UK and Channel Islands only)"
        },
        {
            "id": "Immigration_Document_Visa_WorkPermit",
            "description": "Immigration document, visa or work permit. (Issued by a country outside the EEA. Valid only for roles where the applicant is living and working outside of the UK). This must be issued by the country where the role is based."
        },
        {
            "id": "HM_Forces_ID_Card",
            "description": "HM Forces ID Card (UK only)"
        },
        {
            "id": "Fire_Arms_Licence",
            "description": "Fire Arms Licence (UK, Channel Islands and Isle of Man only)"
        }
    ],
    "financial": [
        {
            "id": "Morgage_Statement",
            "description": "Mortgage Statement (UK or EEA only) issued within the past 12 months"
        },
        {
            "id": "Bank_Building_Society_Statement_UkOrEea",
            "description": "Bank/Building Society Statement (UK and Channel Islands or EEA only) less than 3 months old"
        },
        {
            "id": "Bank_Building_Society_Statement_NonEea",
            "description": "Bank/Building Society Statement (Non-EEA – branch must be in the country where the applicant lives and works) less than 3 months old"
        },
        {
            "id": "Bank_Building_Society_Opening_Letter",
            "description": "Bank/Building Society account opening confirmation letter (UK only) less than 3 months old"
        },
        {
            "id": "Credit_Card_Statement",
            "description": "Credit Card Statement (UK or EEA only) less than 3 months old"
        },
        {
            "id": "Financial_Statement",
            "description": "Financial Statement (e.g. Pension, Endowment; UK only) issued within the past 12 months"
        },
        {
            "id": "P45_P60_Statement",
            "description": "P45/P60 Statement (UK and Channel Islands) issued within the past 12 months"
        },
        {
            "id": "Council_Tax_Statement",
            "description": "Council Tax Statement (UK and Channel Islands) issued within the past 12 months"
        },
        {
            "id": "Utility_Bill",
            "description": "Utility Bill (UK only) (Not Mobile Telephone) less than 3 months old"
        },
        {
            "id": "Benefit_Statement",
            "description": "Benefit statement (e.g. Child Allowance, Pension; UK only) less than 3 months old"
        },
        {
            "id": "Government_Document",
            "description": "A document from central or local government / government agency / local authority giving entitlement (UK and Channel Islands only) less than 3 months olds"
        },
        {
            "id": "PASS_Card",
            "description": "Cards carrying the PASS accreditation logo (UK, Isle of Man and Channel Islands only)"
        },
        {
            "id": "Letter_From_Head_Teacher",
            "description": "Letter from Head Teacher or College Principal (Under 20 years old, UK only)"
        }
    ]
}

PurposeOfCheck must be a value selected from the dbscheckpurpose value set.

GET /metadata/valuesets/dbscheckpurpose/values

Sample response

{
    "valuesInSet": [
        {
            "value": "Paid Work in UK"
        },
        {
            "value": "Paid Work Elsewhere"
        },
        {
            "value": "Unpaid Work"
        }
    ]
}

Webhooks

Checks are completed or cancelled
Orders are completed or cancelled
The candidate has submitted their data, enabling checks to be processed
The candidate's identity has been confirmed for criminal record checks

The webhook object

The webhook object is used to send and receive information for most of the webhook endpoints.

Fields

Field	Type	Description
webhookKey	String (UUID)	A unique reference for the webhook
events	String Array	The triggers for which a notification will be sent Field Validation Values for this field must be from the webhookevents value set. This field is mandatory
authorisationToken	String	A string that will be transformed to a SHA1 hash and sent with every webhook.
callbackUri	String (Url)	The receiving endpoint. Must start with HTTPS. Field Validation This field is mandatory

Manage webhooks in the Verifile portal

You can manage your webhook subscriptions in the Verifile portal. After you log in, click My Account and then select the nofifications tab.

From this page, you can view your subscribed webhooks and your webhook history for the last 30 days, you can edit webhooks and add new ones.

Register for a webhook notification

POST webhooks/webhook

{
"webhookKey": "0DD8416A-BF8E-4598-BC3A-E1F1D4D65E0A",
"events": [
{
"eventType": "OrderComplete",
"eventSubscribed": true
}
],
"authorisationToken": "a super secret token that only I know",
"callbackUri": "https://hookb.in/dmD3nr9OQRfdKdzOXB1X"
}

Update a Webhook

PUT /webhooks/webhook

Update an existing webhook

This endpoint requires a Webhook object where the webhookKey matches an existing webhook.

This endpoint returns a Webhook object.

View a Webhook

GET /webhooks/webhook/{WebhookKey}

Returns an existing webhook via the API

This request URL requires a WebhookKey parameter that matches an existing webhook.

This endpoint returns a Webhook object.

View all Webhooks

GET webhooks/webhook/list

Returns all existing webhooks via the API.

This endpoint returns an array of Webhook objects.

Delete a Webhook

DELETE /api/v1/webhooks/webhook

Deletes an existing webhook via the API

This endpoint requires a WebhookKey that matches an existing webhook.

View Webhook activity history

GET /webhooks/webhook/history

Returns details of all of the webhooks sent over the last 30 days.

This endpoint returns an array of WebhookHistory objects.

Webhook History Object

Fields

Field	Type	Description
orderId	Integer	Reference to the Verifile order that triggered the webhook
eventType	String	The action that triggered the webhook
callbackUri	String (Url)	The endpoint the webhook notification was sent to
authorisationToken	String	The hashed security token sent with the request
webhookSentDate	String (yyyy-mm-dd)	The date the webhook was triggered

Check Reference

Verifile has a product catalog with many hundreds of check types.

Many of these can be ordered with what is essentially the same request Json, with
only CheckType differing depending on what is required in the order.

You can find checks available to your account via /metadata/checktypes.

This section describes check types that require check-specific information.

Academic Qualification Check

This documentation is under review and is subject to change at any time

This check will confirm whether the candidate has gained the Academic Qualifications stated.

Verifile will check:

The establishment attended
Dates attended
Level of qualification obtained
Title of course
Classification of qualification

The check can be for a qualification obtained within the UK, or outside the UK.

For a UK qualification use AcademicQualificationUK

For a qualification obtained outside the UK use AcademicQualificationWorldwide

For a Worldwide check, you must provide the name of the relevant country in CheckAcademicCountry.

CheckType (UK)

AcademicQualificationUK

CheckType (Worldwide)

AcademicQualificationWorldwide

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Fields

Field	Type	Description
CheckAcademicCountry	String	The country for which the check applies Field Validation Values for this field must be from the country value set. This field is optional Mandatory for 'AcademicQualificationWorldwide', disallowed for 'AcademicQualificationUK'
CheckAcademicInstitution	String	The name of the institution where the candidate obtained the qualification. Field Validation The minimum length of this field is 2 characters The maximum length of this field is 500 characters This field is mandatory
CheckAcademicQualification	String	The course name of the qualification. Field Validation The minimum length of this field is 2 characters The maximum length of this field is 500 characters This field is mandatory
CheckAcademicLevelOfQualification	String	The name of level of qualification, for example 'BSc' or 'NVQ'. Field Validation The minimum length of this field is 2 characters The maximum length of this field is 500 characters This field is mandatory
CheckAcademicGraduationDate	String (yyyy[-mm-dd])	This is the date that the candidate graduated, which may not be the date the course finished. Field Validation This field is mandatory
CheckAcademicStudentNumber	String	The number assigned to the candidate while they attended the institution. Field Validation The maximum length of this field is 50 characters This field is optional
CheckAcademicCampus	String	The name of campus candidate attended, if appropriate. Max 500 characters.
CheckAcademicDepartment	String	The name of the department the candidate attended, if appropriate. Field Validation The maximum length of this field is 500 characters This field is optional
CheckAcademicClassification	String	The classification of the qualification. Field Validation The maximum length of this field is 500 characters This field is optional
CheckAcademicNotes	String	Any additional useful information not covered by other fields. Field Validation The maximum length of this field is 500 characters This field is optional
CheckAcademicContactTelephoneNumber	String (telephone number)	The telephone number to be used to contact the institution. Field Validation The minimum length of this field is 2 characters The maximum length of this field is 30 characters This field is optional
CheckAcademicContactFaxNumber	String (telephone number)	The fax number to be used to contact the institution. Field Validation The minimum length of this field is 2 characters The maximum length of this field is 30 characters This field is optional
CheckAcademicContactEmail	String (Email address)	The email address to be used to contact the institution. Field Validation The minimum length of this field is 5 characters The maximum length of this field is 50 characters This field is optional
CheckAcademicContactWeb	String	The website to be used to contact the institution.
CheckAcademicContactName	String (name)	A contact name for the academic institutions reference/human resource team.
CheckAcademicInstitutionAddress	String (Address)	The postal address to be used to contact the institution Field Validation This field is optional Mandatory if Address provided
CheckAcademicInstitutionAddress.StreetName	String	The address street Field Validation The minimum length of this field is 2 characters The maximum length of this field is 60 characters This field is optional Mandatory if Address provided
CheckAcademicInstitutionAddress.Town	String	The address town Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional Mandatory if Address provided
CheckAcademicInstitutionAddress.Country	String	The address country Field Validation Values for this field must be from the country value set. This field is optional Mandatory for a World-wide check.
CheckAcademicUKAttendant	String (Academic Date Range)	The dates of attendance, from and to, for a UK check. Field Validation This field is optional Mandatory for a UK check.
CheckAcademicWorldwideAttendant	String (Academic Date Range)	The dates of attendance, from and to, for a World-wide check. Field Validation This field is optional Mandatory for a World-wide check.
CheckAcademicAttendantFrom	String (yyyy[-mm-dd])	The date from which the candidate attended the institution.
CheckAcademicAttendantTo	String (yyyy[-mm-dd])	The date the course finished, empty if not finished.

Request


"Checks": 
[
    {
        "CheckAcademicInstitution": "Bedford University",
        "CheckAcademicQualification": "Computer Science",
        "CheckAcademicLevelOfQualification": "BSc",
        "CheckAcademicGraduationDate": "2007-08-01",
        "CheckAcademicStudentNumber": "111357",
        "CheckAcademicCampus": "Bedford Central",
        "CheckAcademicDepartment": "IT",
        "CheckAcademicClassification": "2/1",
        "CheckAcademicNotes": "Additional information...",
        "CheckAcademicContactTelephoneNumber": "01234555555",
        "CheckAcademicContactFaxNumber": "01234555556",
        "CheckAcademicContactEmail": "demo@example.com",
        "CheckAcademicContactWeb": "www.verifile.co.uk",
        "CheckAcademicContactName": {
        "Title": "Mr",
        "FirstName": "John",
        "MiddleNames": null,
        "LastName": "Smith"
    },
    "CheckAcademicUKAttendant": 
    {
             "CheckAcademicAttendantFrom": "2014-09-01",
            "CheckAcademicAttendantTo": "2007-06-01"
    },
    "CheckAcademicInstitutionAddress": 
    {
        "BusinessName": "Bedford University",
        "HouseName": "Main Building",
        "StreetName": "University Road",
        "Town": "Bedford",
        "County": "Bedfordshire",
        "State": "England",
        "Postcode": "MK1 0MU"
    },
    "CheckType": "AcademicQualificationUK"
]

Response


"Checks": [
{
"CheckAcademicInstitution": "Bedford University",
"CheckAcademicQualification": "Computer Science",
"CheckAcademicLevelOfQualification": "BSc",
"CheckAcademicGraduationDate": "2007-08-01",
"CheckAcademicStudentNumber": "111357",
"CheckAcademicCampus": "Bedford Central",
"CheckAcademicDepartment": "IT",
"CheckAcademicClassification": "2/1",
"CheckAcademicNotes": "Additional information...",
"CheckAcademicContactTelephoneNumber": "01234555555",
"CheckAcademicContactFaxNumber": "01234555556",
"CheckAcademicContactEmail": "demo@example.com",
"CheckAcademicContactWeb": "www.verifile.co.uk",
"CheckAcademicContactName": {
"FullName": "Mr John Smith"
},
"CheckAcademicUKAttendant": {
"CheckAcademicAttendantFrom": "2014-09-01",
"CheckAcademicAttendantTo": "2007-06-01"
},
"CheckAcademicInstitutionAddress": {
"AddressString": "Bedford University Main Building University Road Bedford Bedfordshire England MK1 0MU"
},
"CheckType": "AcademicQualificationUK",
"CheckState": {
"StateDescription": "Application"
},
"Id": "10001",
"Comment": ""
}
]

Activity Check

This documentation is under review and is subject to change at any time

An activity check can be run for a candidate when the candidate’s history is not known in advance.

CheckType

Activity

Supported Order Types

Client Entry	Candidate Entry
No	Yes

When creating an order with an Activity check, you can request a number of years activity to cover. When the candidate inputs their details in the Verifile system, they will be prompted to add details of their:

Employment History
Academic Qualification(s)
Gap(s) in Activity

Activity checks are ordered in the same way as other candidate-entry checks, but the value placed in the quantity field is the number of years activity you require from the candidate.

Once the candidate has entered the specified number of years/activities (via Verifile's portal) the order will be fulfilled by Verifile's operations team.

Candidate-entry request

"CheckGroups": [
  {
    "Quantity": 2,
    "CheckTypeId": "Activity"
  }
]

Candidate-entry response

"CheckGroups": [
  {
    "Quantity": 2,
    "CheckTypeId": "Activity"
  }
]

Character/Professional Reference Checks

This documentation is under review and is subject to change at any time

This check will provide you with feedback from people who have known the candidate personally or professionally. Verifile will request the following information from referees:

What is your relationship to the applicant?
How long have you known the applicant?
How did you come to know the applicant and how well do you think you know them?
What were the main duties and responsibilities of the applicant (if relevant)?
Please comment on the applicant's honesty and integrity.
What do you think are the applicant's main strengths and areas for development?
Why do you think the applicant is suited to this position?
Is there anything else you can think of that might affect the applicant's ability to carry out the role?
Additional comments

There are two versions of this check:

CharacterProfessionalReferenceUK
CharacterProfessionalReferenceWorldwide

Both checks are fundamentally the same, Both are fundamentally the same, with the UK check having the CheckReferenceContactAddress.Country field automatically set as GB.

CheckType (UK)

CharacterProfessionalReferenceUK

CheckType (Worldwide)

CharacterProfessionalReferenceWorldwide

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Client-entry request

"Checks": [
  {
    "CheckReferenceEMail": "demo@example.com",
    "CheckReferenceDaytimePhone": "07777777777",
    "CheckReferenceEveningPhone": "07777777776",
    "CheckReferenceFax": "01444444444",
    "CheckReferenceDoNotContactReason": "He is very busy",
    "CheckReferenceRefereeRelationship": "Friend",
    "CheckReferenceContactName": {
      "Title": "Mr",
      "FirstName": "John",
      "MiddleNames": "Alan",
      "LastName": "Smith"
    },
    "CheckReferenceContactAddress": {
      "FlatNumber": "6b",
      "StreetName": "Station Road",
      "Town": "Bedford",
      "County": "Bedfordshire",
      "State": "England",
      "Postcode": "MK1 0AA",
      "Country": "GB"
    },
    "CheckType": "CharacterProfessionalReferenceWorldwide"
  }

Client-entry response

                
"Checks": [
  {
    "CheckReferenceEMail": "demo@example.com",
    "CheckReferenceDaytimePhone": "07777777777",
    "CheckReferenceEveningPhone": "07777777776",
    "CheckReferenceFax": "01444444444",
    "CheckReferenceDoNotContactReason": "He is very busy",
    "CheckReferenceRefereeRelationship": "Friend",
    "CheckReferenceContactName": {
      "FullName": "Mr John Alan Smith" 
    },
    "CheckReferenceContactAddress": {
      "AddressString": "6b Station Road Bedford Bedfordshire England MK1 0AA GB"
    },
    "CheckType": "CharacterProfessionalReferenceUK",
    "CheckState": {
      "StateDescription": "Application" 
    },
    "Id": "10001",
    "Comment": ""
  }
]

Candidate-entry request

"CheckGroups": [
  {
    "Quantity": 1,
    "CheckTypeId": "CharacterProfessionalReferenceUK"
  }
]

Candidate-entry response

"Checks": [
  {
    "CheckState": {
      "StateDescription": "Awaiting candidate entry"
    },
    "Id": "10001",
    "Comment": "",
    "CheckType": "CharacterProfessionalReferenceUK"
  }
]

Criminal Record (Basic, England and Wales)

This documentation is under review and is subject to change at any time

The Criminal Record (Basic, England and Wales) check searches the Police National Computer and discloses all convictions which are considered unspent under the Rehabilitation of Offenders Act. If there are no applicable convictions, the results will state this.

No more than one criminal record check is allowed per order.

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Supporting Documents

To process a DBS check we need to know the documents that were used to confirm the candidate's identity in the face to face meeting.

If the order is client-entry, you must provide a list of documents that were seen at the face to face meeting.

If the order is candidate-entry, you must use Verifile's web portal to provide this information.

You do not need to upload the documents in either case.

The dbsacceptabledocuments valuesets endpoint can be used to identify suitable documents.

Candidate-Entry Notes

For candidate entry orders, a maximum of one Criminal Record check per order is allowed, therefore the quantity field isn't required.

DBS require 4 fields to be provided when submitting this check which you need to provide as the client. All these values are passed to DBS. They are:

CheckCriminalPurposeOfCheck: This is purpose of the criminal check. Must be one of from the list supplied by DBS. You can get the options by using the dbscheckpurpose in the valuesets endpoint.
CheckCriminalEmploymentSector: This is industry of company that requires this check. Must be one of from the list supplied by DBS. You can get the options by using the dbsemploymentsector in the valuesets endpoint.
CheckCriminalPositionAppliedFor: This is position the candidate will hold for which criminal check is for. Can be different than the value provided in the field PositionAppliedFor in the Personal Details section.
CheckCriminalEmployerName: Name of the company that the candidate will work for.

These are mandatory whether the order is created via check groups or package.

Client-Entry Notes

You must supply the following fields in the candidate section of your request body.

Personal Information
Identity
List of Addresses covering at least 5 years history (including current address) with no gaps greater than 1 day

CheckType

UKCriminalRecordBasicEnglandWales

Candidate Entry

Field	Type	Description
CheckType	String	UKCriminalRecordBasicEnglandWales Field Validation This field is mandatory
CheckCriminalPurposeOfCheck	String	This is purpose of the criminal check. It must be one of the values specified by the DBS. Field Validation Values for this field must be from the dbscheckpurpose value set. This field is mandatory
CheckCriminalEmploymentSector	String	The DBS has defined This is industry of company that requires this check. Must be one of from the list supplied by DBS. Field Validation Values for this field must be from the dbsemploymentsector value set. This field is mandatory
CheckCriminalPositionAppliedFor	String	The position the candidate is applying for. Field Validation The maximum length of this field is 60 characters This field is mandatory
CheckCriminalEmployerName	String	The name of the company that the candidate will work for. Field Validation The maximum length of this field is 60 characters This field is mandatory

Client Entry

Field	Type	Description
CheckType	String	UKCriminalRecordBasicEnglandWales
CheckCriminalPurposeOfCheck	String	The purpose for the check Field Validation Values for this field must be from the dbscheckpurpose value set. This field is optional
CheckCriminalIdentityDocumentIds	String Array	The documents used to confirm the candidate's identity. Refer to DBS Document Helper endpoint. Field Validation Values for this field must be from the dbsidentitydocuments value set. This field is mandatory
CheckCriminalPositionAppliedFor	String	The position the candidate is applying for (max 60 characters) Field Validation This field is mandatory
CheckCriminalEmploymentSector	String	The sector in which the candidate will be working Field Validation Values for this field must be from the dbsemploymentsector value set. This field is mandatory
CheckCriminalEmployerName	String	The name of the candidate's prospective employer (max 60 characters) Field Validation This field is mandatory
CheckCriminalElectronicCertificateAccess	String	Who the candidate is allowing access to view their online certificate Field Validation Values for this field must be from the dbscandidatesconsentforcertificateaccess value set. This field is mandatory
CheckCriminalPaperCertificateRequest	String	Indicates where the candidate would like the paper certificate posted Field Validation Values for this field must be from the dbspapercertificatedestination value set. This field is mandatory
CheckCriminalSmsProgressUpdate	Boolean	Indicates whether the candidate would like to be keep up to date with the application via SMS Field Validation This field is mandatory
CheckCriminalDateOfConsent	String (yyyy-mm-dd)	The date the candidate gave consent for the order to be placed Field Validation This field is mandatory
CheckCriminalIdentityCheckedBy	String	The name of the person who checked the candidates identity documents Field Validation This field is mandatory

In addition to check-specific fields, the following fields are required in the candidate section:

PersonalInfo
- DateOfBirth (The applicant must be 16 years old on the date the check is ordered)
- CountryOfBirth
- TownOfBirth
- PassportIssuingCountry OR CurrentNationality
Identity (if a driving licence, passport, foreign ID card or birth certificate are selected as Identity documents, the corresponding fields in the PersonalInfo and Identity sections become mandatory.
AddressList (At least 5 years history with no gaps greater than 1 day)

Example request Json (Client entry)

{
    "UniqueKey": "f9865bdb-5d7e-4057-b253-501e623109a7",
    "Checks": [
        {
            "CheckCriminalIdentityCheckedBy": {
                "Title": "Mr",
                "FirstName": "Alan",
                "MiddleNames": "John",
                "LastName": "Bean"
            },
            "CheckCriminalPurposeOfCheck": "Paid Work in UK",
            "CheckCriminalPositionAppliedFor": "Junior Associate",
            "CheckCriminalEmploymentSector": "RECRUITMENT AND HR",
            "CheckCriminalEmployerName": "Background Searches Ltd",
            "CheckCriminalElectronicCertificateAccess": "None",
            "CheckCriminalPaperCertificateAccess": "No Paper Cert Required",
            "CheckCriminalSmsProgressUpdates": false,
            "CheckCriminalDateOfConsent": "2018-11-20",
            "CheckCriminalIdentityDocumentIds": [
                "Current_Valid_Passport",
                "Credit_Card_Statement"
            ],
            "CheckType": "UKCriminalRecordBasicEnglandWales"
        }
    ],
    "Candidate": {
        "PreviousNames": [
            {
                "Title": "Miss",
                "FirstName": "Pauline",
                "LastName": "Jones",
                "IsFromBirth": true,
                "KnownToDate": "2017-01-01"
            }
        ],
        "AddressList": [
            {
                "DateMovedToThisAddress": "2000-09-28",
                "IsCurrentAddress": true,
                "Address": {
                    "HouseNumber": "109",
                    "StreetName": "High ",
                    "Town": "Westbury",
                    "County": "Wiltshire",
                    "Postcode": "BA13 3BN",
                    "Country": "GB"
                }
            }
        ],
        "CurrentName": {
            "Title": "Mrs",
            "FirstName": "Pauline",
            "LastName": "Smyth",
            "IsFromBirth": false,
            "KnownFromDate": "2017-01-01"
        },
        "PersonalInfo": {
            "Gender": "Female",
            "DateOfBirth": "1971-09-28",
            "PositionAppliedFor": "Engineer",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com",
            "NationalityAtBirth": "GB",
            "TownOfBirth": "Westbury",
            "CountryOfBirth": "GB"
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "GB",
                "PassportNumber": "123456789",
                "PassportIssueDate": "2014-01-01",
                "PassportExpiryDate": "2023-12-31",
                "PassportDateOfBirth": "1971-09-28"
            }
        }
    }
}

Example response (Client entry)

{
    "OrderState": {
        "StateDescription": "Processing"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Processing"
            },
            "CheckCriminalIdentityCheckedBy": {
                "FullName": "Mr Alan John Bean"
            },
            "CheckCriminalDbsInternalStatusUpdate": {
                "Stage1ApplicationReceivedDate": null,
                "Stage2PoliceNationalComputerSearchDate": null,
                "Stage3AssembleCertificateDate": null,
                "Stage4CertificateIssuedDate": null
            },
            "Id": 6264,
            "Comment": "",
            "CompletedDate": null,
            "CheckCriminalPurposeOfCheck": "Paid Work in UK",
            "CheckCriminalPositionAppliedFor": "Junior Associate",
            "CheckCriminalEmploymentSector": "RECRUITMENT AND HR",
            "CheckCriminalEmployerName": "Background Searches Ltd",
            "CheckCriminalElectronicCertificateAccess": "None",
            "CheckCriminalPaperCertificateAccess": "No Paper Cert Required",
            "CheckCriminalSmsProgressUpdates": false,
            "CheckCriminalDateOfConsent": "2018-11-20",
            "CheckCriminalIdentityDocumentIds": [
                "Current_Valid_Passport",
                "Credit_Card_Statement"
            ],
            "CheckCriminalApplicationReferenceNumber": "",
            "CheckCriminalCertificateNumber": "",
            "CheckCriminalDbsStatusUpdate": "",
            "CheckCriminalRoute": "Route1",
            "CheckCriminalCandidateIdentity": "Confirmed By Client",
            "CheckCriminalDbsResult": "",
            "CheckType": "UKCriminalRecordBasicEnglandWales"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mrs",
            "FirstName": "Pauline",
            "LastName": "Smyth",
            "MiddleNames": "",
            "FullName": "Mrs Pauline Smyth",
            "IsFromBirth": false,
            "KnownFromDate": "2017-01-01"
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Female",
            "DateOfBirth": "1971-09-28",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "Engineer",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "demo@example.com",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "GB",
            "CountryOfBirth": "GB",
            "TownOfBirth": "Westbury"
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "GB",
                "PassportNumber": "123456789",
                "PassportIssueDate": "2014-01-01",
                "PassportExpiryDate": "2023-12-31",
                "PassportDateOfBirth": "1971-09-28"
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [
            {
                "Title": "Miss",
                "FirstName": "Pauline",
                "LastName": "Jones",
                "MiddleNames": "",
                "FullName": "Miss Pauline Jones",
                "IsFromBirth": true,
                "KnownFromDate": null,
                "KnownToDate": "2017-01-01"
            }
        ],
        "AddressList": [
            {
                "Address": {
                    "BusinessName": "",
                    "FlatNumber": "",
                    "HouseNumber": "109",
                    "HouseName": "",
                    "StreetName": "High",
                    "Locality": "",
                    "Town": "Westbury",
                    "County": "Wiltshire",
                    "State": "",
                    "Postcode": "BA13 3BN",
                    "AddressString": "109 High Westbury Wiltshire BA13 3BN GB",
                    "Country": "GB"
                },
                "DateMovedToThisAddress": "2000-09-28",
                "DateLeftThisAddress": null,
                "IsCurrentAddress": true
            }
        ]
    },
    "Id": 8020,
    "UniqueKey": "7a955cc9-5612-4668-8267-af8a1b8adb41",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Example request Json (Candidate entry)

{
    "UniqueKey": "8f1e25fd-dac8-4b3c-9dfc-d26d7ebb91f3",
    "CheckGroups": [
        {
            "CheckTypeId": "UKCriminalRecordBasicEnglandWales",
            "Quantity": 1
        }
    ],
    "CheckSpecificData": {
        "CheckCriminalPurposeOfCheck": "Paid Work in UK",
        "CheckCriminalPositionAppliedFor": "Nurse",
        "CheckCriminalEmploymentSector": "NHS",
        "CheckCriminalEmployerName": "General Hospital"
    },
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth"
        },
        "PersonalInfo": {
            "Gender": "Male",
            "DateOfBirth": "1991-09-28",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com"
        }
    }
}

Example response (Candidate entry)

{
    "OrderState": {
        "StateDescription": "Awaiting candidate entry"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Awaiting candidate entry"
            },
            "CheckCriminalIdentityCheckedBy": {
                "FullName": ""
            },
            "CheckCriminalDbsInternalStatusUpdate": {
                "Stage1ApplicationReceivedDate": null,
                "Stage2PoliceNationalComputerSearchDate": null,
                "Stage3AssembleCertificateDate": null,
                "Stage4CertificateIssuedDate": null
            },
            "Id": 6265,
            "Comment": "",
            "CompletedDate": null,
            "CheckCriminalPurposeOfCheck": "Paid Work in UK",
            "CheckCriminalPositionAppliedFor": "Nurse",
            "CheckCriminalEmploymentSector": "NHS",
            "CheckCriminalEmployerName": "Verifile General Hospital",
            "CheckCriminalElectronicCertificateAccess": "None",
            "CheckCriminalPaperCertificateAccess": "No Paper Cert Required",
            "CheckCriminalSmsProgressUpdates": false,
            "CheckCriminalDateOfConsent": null,
            "CheckCriminalIdentityDocumentIds": [],
            "CheckCriminalApplicationReferenceNumber": "",
            "CheckCriminalCertificateNumber": "",
            "CheckCriminalDbsStatusUpdate": "",
            "CheckCriminalRoute": "",
            "CheckCriminalCandidateIdentity": "Unspecified",
            "CheckCriminalDbsResult": "",
            "CheckType": "UKCriminalRecordBasicEnglandWales"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth",
            "MiddleNames": "",
            "FullName": "Mr Paul Smyth",
            "IsFromBirth": false,
            "KnownFromDate": null
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "demo@example.com",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "",
            "CountryOfBirth": "",
            "TownOfBirth": ""
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "",
                "PassportNumber": "",
                "PassportIssueDate": null,
                "PassportExpiryDate": null,
                "PassportDateOfBirth": null
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [],
        "AddressList": []
    },
    "Id": 8021,
    "UniqueKey": "693a6bf2-808d-43a1-b24a-a31dc990b3ed",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Criminal Record (Basic, Scotland)

This documentation is under review and is subject to change at any time

The Criminal Record (Basic, Scotland) check searches the Police National Computer and discloses all convictions which are considered unspent under the Rehabilitation of Offenders Act. If there are no applicable convictions, the results will state this.

No more than one criminal record check is allowed per order.

Supporting Documents

To process a Basic Disclosure check we need proof of identity document and a proof of address document. The same document type can’t be used for both. For example, if Driving Licence is used for Proof of Identity, it can't also be used for proof of address.

If this is a candidate entry order, the candidate will upload the documents using Verifile's web portal.

If the check is a client-entry order then you must upload the documents through the API using the attachments endpoint.

Acceptable documents are available from the valuesets endpoint:

For proof of residential address use /metadata/valuesets/proofofresidentialaddress/values
For proof of identity use /metadata/valuesets/proofofidentity/values

CheckType

UKCriminalRecordBasicScotland

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Client Entry

Fields

Field	Type	Description
CheckType	String	UKCriminalRecordBasicScotland
HasUnspentConvictions	Boolean	An indication if the candidate has unspent convictions.
ProofOfIdentity.IdentityProofDocuments	String Array	Values indicating which documents are being used as proof of identity. Field Validation Values for this field must be from the proofofidentity value set. This field is optional
ProofOfResidentialAddress.AddressProofDocuments	String Array	Documents which the applicant has supplied as proof of their address. Field Validation Values for this field must be from the proofofresidentialaddress value set. This field is optional
PayslipDate	String (yyyy-mm-dd)	The date of the payslip (if used as proof of address)

For client-entry orders, the following fields are required in the candidate section:

- PersonalInfo
    - DateOfBirth
    - CountryOfBirth
    - TownOfBirth
    - VisaNationality (mandatory if Visa is selected as proof of identity)
    - BirthCertificateCountry (mandatory if birth certificate is selected as proof of identity)
    - EUNationalIdCardCountry (mandatory if EU ID card is selected as proof of identity)
    - MotherMaidenName
- Identity
    - PassportDocument (mandatory if passport is selected as proof of identity)
    - NationalInsuranceNumberDocument (mandatory if NI is selected as proof of identity)
    - DrivingDocument (mandatory if driving licence is selected as proof of identity)
- AddressList

Example request (Client entry)

{
    "UniqueKey": "a2f1b4d2-bc66-42af-be15-b784089ffe2a",
    "Checks": [
        {
            "HasUnspentConvictions": false,
            "ProofOfIdentity": {
                "IdentityProofDocuments": [
                    "Passport"
                ]
            },
            "ProofOfResidentialAddress": {
                "AddressProofDocuments": [
                    "Water",
                    "Payslip"
                ],
                "PayslipDate": "2018-09-01"
            },
            "CheckCriminalApplicantConsentDate": "2017-09-01",
            "CheckType": "UKCriminalRecordBasicScotland"
        }
    ],
    "Candidate": {
        "PreviousNames": [],
        "AddressList": [
            {
                "DateMovedToThisAddress": "2000-09-28",
                "IsCurrentAddress": true,
                "Address": {
                    "HouseNumber": "109",
                    "StreetName": "High ",
                    "Town": "Westbury",
                    "County": "Wiltshire",
                    "Postcode": "BA13 3BN",
                    "Country": "GB"
                }
            }
        ],
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth",
            "IsFromBirth": true
        },
        "PersonalInfo": {
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "PositionAppliedFor": "Engineer",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com",
            "NationalityAtBirth": "GB",
            "TownOfBirth": "Westbury",
            "CountryOfBirth": "GB",
            "MotherMaidenName": "Ruffolo"
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "GB",
                "PassportNumber": "123456789",
                "PassportIssueDate": "2014-01-01",
                "PassportExpiryDate": "2023-12-31"
            }
        }
    }
}

Example response (Client entry)

"Checks": [
  {
    "HasUnspentConvictions": false,
    "ProofOfIdentity": {
      "IdentityProofDocuments": [ "Passport" ] 
    },
    "ProofOfResidentialAddress": {
      "PayslipDate": null,
      "AddressProofDocuments": [ "Water" ]
    },
    "CheckCriminalApplicantConsentDate": "2017-09-01",
    "CheckCriminalDisclosureApplicationNumber": "",
    "CheckCriminalCaseNumber": "",
    "CheckCriminalCertificateNumber": null,
    "CheckType": "UKCriminalRecordBasicScotland",
    "CheckState": {
      "StateDescription": "Information required - Proof of identity and proof of address"
    },
    "Id": "10001",
    "Comment": ""
  }
]

Example request (Candidate entry)

"CheckGroups": [
  {
    "CheckTypeId": "UKCriminalRecordBasicScotland"
  }
]

Example response (Candidate entry)

"Checks": [
  {
    "CheckState": {
      "StateDescription": "Awaiting candidate entry"
    },
    "Id": "10001",
    "Comment": "",
    "CheckType": "UKCriminalRecordBasicScotland"
  }
]

Criminal Record (Standard and Enhanced, England and Wales)

This documentation is under review and is subject to change at any time

The Criminal Record (Standard and Enhanced, England and Wales) check searches the Police National Computer and discloses all convictions which are considered unspent under the Rehabilitation of Offenders Act. If there are no applicable convictions, the results will state this.

Standard Disclosure: Searches the Police National Computer and discloses all spent and unspent convictions, cautions, reprimands and warnings. Standard Disclosure can only be ordered for positions that meet certain eligibility criteria. The typical turnaround time for a Standard Disclosure is 5-10 working days.

Enhanced Disclosure: Searches the Police National Computer and discloses all spent and unspent convictions, cautions, reprimands and warnings. In addition, an Enhanced Disclosure may contain non-conviction information from local police forces. Enhanced Disclosure can also check the relevant ISA barred lists to ensure the individual is not barred from working with children and/or vulnerable adults. Enhanced Disclosure can only be ordered for positions that meet certain eligibility criteria. Typical positions available for this level are those working in regulated positions (eg. training, supervising etc.) or regulated places (eg. schools, hospitals, care homes etc.). The typical turnaround time for a Enhanced Disclosure is 2-4 weeks.

No more than one criminal record check is allowed per order.

Supporting Documents

To process a DBS check we need to know the documents that were used to confirm the candidate's identity in the face to face meeting.

If the order is client-entry, you must provide a list of documents that were seen at the face to face meeting.

If the order is candidate-entry, you must use Verifile's web portal to provide this information.

You do not need to upload the documents in either case.

The dbsacceptabledocuments valuesets endpoint can be used to identify suitable documents.

CheckType (Standard)

UKCriminalRecordStandardEnglandWales

CheckType (Enhanced)

UKCriminalRecordEnhancedEnglandWales

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Candidate Entry

sequenceDiagram participant Cl as Client participant Ca as Candidate participant V as Verifile participant DBS as Disclosure and
Barring Service Cl->>V: Candidate contact details and Job Role V->>Ca: Invitation to select ID docs Ca->>V: Selection of ID docs Ca->>Cl: Shows ID docs in person V->>Cl: Request to confirm ID Cl->>V: Confirms ID V->>DBS: Submits Application V->>Cl: Application Number DBS->>V: Record Found or No Record V->>Cl: Result Green or Amber Ca->>Cl: Optional Disclosure

Fields

Field	Type	Description
CheckSpecificData.CheckCriminalJobRoleId	Integer	The job role the candidate is applying for Field Validation Values for this field must be from the dbsjobroles value set. This field is optional

Example request for an Enhanced Criminal Check (candidate entry)

{
    "UniqueKey": "73b0a350-0db7-4dae-86c4-7cc820b99857",
    "CheckGroups": [
        {
            "CheckTypeId": "UKCriminalRecordEnhancedEnglandWales",
            "Quantity": 1
        }
    ],
    "CheckSpecificData": {
        "CheckCriminalJobRoleId": 66
    },
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth"
        },
        "PersonalInfo": {
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com"
        }
    }
}

Client Entry

sequenceDiagram participant Cl as Client participant V as Verifile participant Ca as Candidate participant DBS as Disclosure and
Barring Service Cl->>V: Candidate details Cl->>V: Job Role and ID Doc Selection Cl->>V: Confirmation of Identity and Consent V->>DBS: Submits Application V->>Cl: Application Number DBS->>V: Record Found or No Record V->>Cl: Result Green or Amber Ca->>Cl: Optional Disclosure

Fields

Field	Type	Description
CheckType	String	UKCriminalRecordStandardEnglandWales (Standard) or UKCriminalRecordEnhancedEnglandWales (Enhanced)
CheckCriminalHasUnspentConvictions	Boolean	Indicates whether the candidate has disclosed previous convictions.
CheckCriminalJobRoleId	Integer	The job role the candidate is applying for. Field Validation Values for this field must be from the dbsjobroles value set. This field is optional
CheckCriminalIdentityDocumentIds	String Array	The documents used to confirm the candidate's identity. Refer to DBS Document Helper endpoint. Field Validation Values for this field must be from the dbsidentitydocuments value set. This field is optional
CheckCriminalDateOfConsent	String (yyyy-mm-dd)	The date the candidate gave consent for the order to be placed
CheckCriminalIdentityCheckedBy	String	The name of the person who checked the candidates identity documents

Example request for a Standard Criminal Check (client entry)

{
    "UniqueKey": "caa1e740-9504-4fd5-b401-2fcf5ed4bfc4",
    "Checks": [
        {
            "CheckCriminalHasUnspentConvictions": false,
            "CheckCriminalJobRoleId": 57,
            "CheckCriminalIdentityDocumentIds": [
                "Current_Valid_Passport",
                "HM_Forces_ID_Card",
                "Morgage_Statement"
            ],
            "CheckCriminalIdentityCheckedBy": {
                "Title": "Mr",
                "FirstName": "Alan",
                "MiddleNames": "John",
                "LastName": "Bean"
            },
            "CheckCriminalDateOfConsent": "2018-01-29",
            "CheckType": "UKCriminalRecordStandardEnglandWales"
        }
    ],
    "Candidate": {
        "PreviousNames": [
            {
                "Title": "Miss",
                "FirstName": "Pauline",
                "LastName": "Jones",
                "IsFromBirth": true,
                "KnownToDate": "2017-01-01"
            }
        ],
        "AddressList": [
            {
                "DateMovedToThisAddress": "2000-09-28",
                "IsCurrentAddress": true,
                "Address": {
                    "HouseNumber": "109",
                    "StreetName": "High ",
                    "Town": "Westbury",
                    "County": "Wiltshire",
                    "Postcode": "BA13 3BN",
                    "Country": "GB"
                }
            }
        ],
        "CurrentName": {
            "Title": "Mrs",
            "FirstName": "Pauline",
            "LastName": "Smyth",
            "IsFromBirth": false,
            "KnownFromDate": "2017-01-01"
        },
        "PersonalInfo": {
            "Gender": "Female",
            "DateOfBirth": "1971-09-28",
            "PositionAppliedFor": "Engineer",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com",
            "NationalityAtBirth": "GB",
            "TownOfBirth": "Westbury",
            "CountryOfBirth": "GB",
            "MotherMaidenName": "Maiden"
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "GB",
                "PassportNumber": "123456789",
                "PassportIssueDate": "2014-01-01",
                "PassportExpiryDate": "2023-12-31",
                "PassportDateOfBirth": "1971-09-28"
            }
        }
    }
}

Driving Licence (DVLA UK)

This documentation is under review and is subject to change at any time

The Driving Licence (DVLA UK) check will confirm whether the candidate has any driving offences/endorsements. Using the data provided by either the client or the candidate, DVLA report will provide:

Type of offence with offence code
Amount of fines
Number of points
Date of offence
How long the offence will stay on the licence
Validity of Light Goods Vehicles (LGV) and Passenger Carrying Vehicle (PCV) driving entitlements
Personal details such as name, address and even photograph as held by the DVLA
If the driver does not hold a UK driving licence, the check will confirm if they have received any endorsements or disqualifications whilst driving in the UK using their international licence.

Note The DVLA won’t complete the request until an OCR formatted PDF form they provide is completed. This will be provided to you before signing up to the API and is also available to download here.

CheckType

DrivingLicenceDVLAUK

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Client entry request

"Checks": [
  {
    "CheckType": "DrivingLicenceDVLAUK"
  } 
]

Client entry response

"Checks": [
  {
    "CheckType": "DrivingLicenceDVLAUK",
    "CheckState": {
      "StateDescription": "Application" 
    },
    "Id": "10001",
    "Comment": ""
  }
]

Candidate entry order

"CheckGroups": [
  {
    "CheckTypeId": "DrivingLicenceDVLAUK"
  }
]

Candidate entry response

"Checks": [
  {
    "CheckState": {
      "StateDescription": "Awaiting candidate entry"
    },
    "Id": "10001",
    "Comment": "",
    "CheckType": "DrivingLicenceDVLAUK"
  }
]

Employment History

This documentation is under review and is subject to change at any time

This check will confirm whether the candidate has worked for the stated organisation.

CheckType

EmploymentHistoryUK

EmploymentHistoryWorldwide

Both have the same data requirements but Worldwide requires CheckEmploymentCountry.

Note that the data requirements for this check type also depend on the value supplied for CheckEmploymentStatus.

You can check the list of possible values for CheckEmploymentStatus with

GET /metadata/valuesets/employmentstatus/values

This list may change but current values are:

Employed_directly
Employed_agency
Self_employed_directly
Self_employed_agency
Voluntary_role
Internship

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Client Entry Fields

Field	Type	Description
CheckType	String	EmploymentHistoryUK or EmploymentHistoryWorldwide Field Validation This field is mandatory
CheckEmploymentCountry	String	The country for which the check applies Field Validation Values for this field must be from the country value set. This field is optional Mandatory for Worldwide
CheckEmploymentStartDate	String	The date the applicant started their employment Field Validation This field is mandatory
CheckEmploymentFinishDate	String (yyyy-mm-dd)	Field Validation This field is optional If left blank implies employment is ongoing
CheckEmploymentRecentPosition	String	The candidate's previous job role Field Validation The maximum length of this field is 100 characters This field is mandatory
CheckEmploymentSalary	String	The candidate’s salary Field Validation The maximum length of this field is 50 characters This field is optional
CheckEmploymentLocation	String	The area of the business the candidate worked Field Validation The maximum length of this field is 100 characters This field is optional
CheckEmploymentPayrollNumber	String	The payroll number within their employment Field Validation The maximum length of this field is 100 characters This field is optional
CheckEmploymentNotes	String	Any pertinent data not covered by the other fields Field Validation The maximum length of this field is 500 characters This field is optional
CheckEmploymentContactEmployer	String	Establishes if and when Verifile can contact the employer Field Validation Values for this field must be from the employmentcontactemployer value set. This field is mandatory
CheckEmploymentContactEmployerContactDate	String (yyyy-mm-dd)	A date from which Verifile may contact the employer Field Validation This field is mandatory
CheckEmploymentDoNotContactReason	String	The reason the applicant doesn't want their employer to be contacted Field Validation The minimum length of this field is 2 characters The maximum length of this field is 256 characters This field is optional Mandatory if CheckEmploymentContactEmployer is set to No_do_not_contact or Contact_from
CheckEmploymentCandidateReasonForLeaving	String	The candidates reason for leaving this employment Field Validation Values for this field must be from the employmentreasonforleaving value set. This field is optional Mandatory if CheckEmploymentFinishDate is supplied
CheckEmploymentCandidateReasonForLeavingOther	String	The candidates reason for leaving this employment Field Validation The minimum length of this field is 2 characters The maximum length of this field is 512 characters This field is optional Mandatory if CheckEmploymentCandidateReasonForLeaving is 'Other'
CheckEmploymentStatus	String	The kind of employment to be checked Field Validation Values for this field must be from the employmentstatus value set. This field is mandatory
CheckEmploymentSelfEmployedStatus	String	The type of self-employment for self-employed applicants Field Validation The maximum length of this field is 0 characters Values for this field must be from the selfemploymentstatus value set. This field is optional Mandatory if CheckEmploymentStatus is 'Self_employed_directly'
CheckEmploymentSelfEmployedCompanyRegistrationNo	String	To help identify the company in question Field Validation The minimum length of this field is 2 characters The maximum length of this field is 32 characters This field is optional Mandatory if CheckEmploymentSelfEmployedStatus is 'own_company'
CheckEmploymentSelfEmployedCompanyCountry	String	To identify the country in which the company was registered Field Validation Values for this field must be from the country value set. This field is optional Mandatory if CheckEmploymentSelfEmployedStatus is 'own_company'
CheckEmploymentEmployer	String	Employers or Agents name or the Company name Field Validation The minimum length of this field is 2 characters The maximum length of this field is 100 characters This field is optional Mandatory unless CheckEmploymentStatus is 'Self_employed_agency' or ('Self_employed_directly' with CheckEmploymentSelfEmployedStatus of 'not_specified' or 'self_empl_ind')
ContactDetails	ContactDetails Object (see below)	Contact details for the employer Field Validation This field is optional Mandatory if CheckEmploymentEmployer is 'Employed_directly', 'Voluntary_role' or 'Internship'
EmployedDirectlyForClient	EmployedDirectlyForClient Object (see below)	The client that employed the candidate Field Validation This field is optional Mandatory if CheckEmploymentEmployer is 'Self_employed_directly'

ContactDetails Object

Field	Type	Description
CheckEmploymentContactName	Name Object
CheckEmploymentContactEmail	String (Email address)	The contact email address of the organisation Field Validation The minimum length of this field is 7 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactWebsite	String	Website address of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactTelephoneNumber	String (telephone number)	The contact telephone of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactFaxNumber	String (telephone number)	The contact fax of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactAddress	Address Object	The contact address of the organisation
CheckEmploymentContactCompanyName	String	The contact address of the organisation Field Validation The maximum length of this field is 500 characters This field is optional

EmployedDirectlyForClient Object

This object consists of three mandatory objects, each described in the following tables

Field	Type	Description
Client	EmployedDirectlyForClient.Client Object	The client that employed the candidate
Management	EmployedDirectlyForClient.Management Object	The candidate's management company Field Validation This field is mandatory
Accountant	EmployedDirectlyForClient.Accountant Object	The candidate's company accountant Field Validation This field is mandatory

EmployedDirectlyForClient.Client Object

Field	Type	Description
CheckEmploymentContactClientCompany	String	The name of the organisation Field Validation The maximum length of this field is 100 characters This field is optional
CheckEmploymentContactClientName	Name Object	The contact name of the person at the organisation
CheckEmploymentContactClientEmail	String (Email address)	The contact email address of the organisation Field Validation The minimum length of this field is 7 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactClientWeb	String	The contact website address of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactClientTel	String (telephone number)	The contact telephone number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactClientFax	String (telephone number)	The contact fax number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactClientAddress	Address Object	The contact address of the organisation

EmployedDirectlyForClient.Management Object

Field	Type	Description
CheckEmploymentContactManagementCompany	String	The name of the management organisation Field Validation The maximum length of this field is 100 characters This field is optional
CheckEmploymentContactManagementName	Name Object	The contact name of the person at the organisation
CheckEmploymentContactManagementEmail	String (Email address)	The contact email address of the organisation Field Validation The minimum length of this field is 7 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactManagementWebsite	String	The contact website address of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactManagementTel	String (telephone number)	The contact telephone number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactManagementFax	String (telephone number)	The contact fax number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactManagementAddress	Address Object	The contact address of the organisation

EmployedDirectlyForClient.Accountant Object

Field	Type	Description
CheckEmploymentContactAccountantFirm	String	The name of the accountancy firm Field Validation The maximum length of this field is 100 characters This field is optional
CheckEmploymentContactAccountantName	Name Object	The contact name of the person at the organisation
CheckEmploymentContactAccountantEmail	String (Email address)	The contact email address of the organisation Field Validation The minimum length of this field is 7 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactAccountantWeb	String	The contact website address of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactAccountantTel	String (telephone number)	The contact telephone number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactAccountantFax	String (telephone number)	The contact fax number of the organisation Field Validation The minimum length of this field is 2 characters The maximum length of this field is 50 characters This field is optional
CheckEmploymentContactAccountantAddress	Address Object	The contact address of the organisation

Client-entry request

An example of a client entry order for an Employment History check, where the checkEmploymentStatus is Employed_directly.

{
  "UniqueKey": "f7a30f74-8f2a-4421-a354-54db67579515",
  "Checks": [
    {
      "ContactDetails": {
        "CheckEmploymentContactName": {
          "Title": "Mr",
          "FirstName": "John",
          "MiddleNames": "Alan",
          "LastName": "Smith"
        },
        "CheckEmploymentContactAddress": {
          "BusinessName": "The Company",
          "HouseNumber": "400",
          "StreetName": "Station Road",
          "Town": "Bedford",
          "County": "Bedfordshire",
          "State": "England",
          "Postcode": "MK1 0AA",
          "Country": "GB"
        },
        "CheckEmploymentContactTelephoneNumber": "0123456789",
        "CheckEmploymentContactFaxNumber": "023456789",
        "CheckEmploymentContactEmail": "demo@example.com",
        "CheckEmploymentContactWebsite": "www.verifile.co.uk"
      },
      "CheckEmploymentStatus": "Employed_directly",
      "CheckEmploymentRecentPosition": "Account Executive",
      "CheckEmploymentContactEmployer": "Contact_from",
      "CheckEmploymentContactEmployerContactDate": "2017-12-01",
      "CheckEmploymentDoNotContactReason": "Candidate has not yet informed employer",
      "CheckEmploymentPayrollNumber": "11145896",
      "CheckEmploymentSalary": "25000",
      "CheckEmploymentNotes": null,
      "CheckEmploymentStartDate": "2010-01-02",
      "CheckType": "EmploymentHistoryUK",
      "CheckEmploymentEmployer": "Acme Supplies Ltd"
    }
  ],
  "Candidate": {
    "CurrentName": {
      "Title": "Mr",
      "FirstName": "Billy",
      "LastName": "Willaker",
      "IsFromBirth": true
    },
    "AddressList": [
      {
        "Address": {
          "HouseNumber": "999",
          "StreetName": "Gold Furlong",
          "Locality": "Marston Moretaine",
          "Town": "Bedford",
          "County": "Bedfordshire",
          "State": "England",
          "Postcode": "MK44 3JZ",
          "Country": "GB"
        },
        "DateMovedToThisAddress": "2000-09-28",
        "IsCurrentAddress": true
      }
    ],
    "PersonalInfo": {
      "Gender": "Male",
      "DateOfBirth": "1946-06-14",
      "ApplicantType": "Candidate"
    }
  }
}

Client-entry response

{
    "OrderState": {
        "StateDescription": "Application"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Application"
            },
            "ContactDetails": {
                "CheckEmploymentContactName": {
                    "FullName": "Mr John Alan Smith"
                },
                "CheckEmploymentContactAddress": {
                    "AddressString": "The Company 400 Station Road Bedford Bedfordshire England MK1 0AA GB"
                },
                "CheckEmploymentContactTelephoneNumber": "0123456789",
                "CheckEmploymentContactFaxNumber": "023456789",
                "CheckEmploymentContactEmail": "demo@example.com",
                "CheckEmploymentContactWebsite": "www.verifile.co.uk",
                "CheckEmploymentContactCompanyName": ""
            },
            "EmployedDirectlyForClient": {
                "Accountant": {
                    "CheckEmploymentContactAccountantName": {
                        "FullName": ""
                    },
                    "CheckEmploymentContactAccountantAddress": {
                        "AddressString": ""
                    },
                    "CheckEmploymentContactAccountantFirm": "",
                    "CheckEmploymentContactAccountantTel": "",
                    "CheckEmploymentContactAccountantFax": "",
                    "CheckEmploymentContactAccountantEmail": "",
                    "CheckEmploymentContactAccountantWeb": ""
                },
                "Management": {
                    "CheckEmploymentContactManagementName": {
                        "FullName": ""
                    },
                    "CheckEmploymentContactManagementAddress": {
                        "AddressString": ""
                    },
                    "CheckEmploymentContactManagementCompany": "",
                    "CheckEmploymentContactManagementTel": "",
                    "CheckEmploymentContactManagementFax": "",
                    "CheckEmploymentContactManagementEmail": "",
                    "CheckEmploymentContactManagementWeb": ""
                },
                "Client": {
                    "CheckEmploymentContactClientName": {
                        "FullName": ""
                    },
                    "CheckEmploymentContactClientAddress": {
                        "AddressString": ""
                    },
                    "CheckEmploymentContactClientCompany": "",
                    "CheckEmploymentContactClientTel": "",
                    "CheckEmploymentContactClientFax": "",
                    "CheckEmploymentContactClientEmail": "",
                    "CheckEmploymentContactClientWeb": ""
                }
            },
            "Id": 6654,
            "Comment": "",
            "CompletedDate": null,
            "CheckEmploymentStatus": "Employed_directly",
            "CheckEmploymentSelfEmployedStatus": "",
            "CheckEmploymentSelfEmployedCompanyRegistrationNo": "",
            "CheckEmploymentSelfEmployedCompanyCountry": "",
            "CheckEmploymentEmployer": "Acme Supplies Ltd",
            "CheckEmploymentRecentPosition": "Account Executive",
            "CheckEmploymentContactEmployer": "Contact_from",
            "CheckEmploymentContactEmployerContactDate": "2017-12-01",
            "CheckEmploymentDoNotContactReason": "Candidate has not yet informed employer",
            "CheckEmploymentLocation": "",
            "CheckEmploymentPayrollNumber": "11145896",
            "CheckEmploymentCandidateReasonForLeaving": "",
            "CheckEmploymentCandidateReasonForLeavingOther": "",
            "CheckEmploymentSalary": "25000",
            "CheckEmploymentNotes": "",
            "CheckEmploymentStartDate": "2010-01-02",
            "CheckEmploymentFinishDate": null,
            "CheckType": "EmploymentHistoryUK"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Billy",
            "LastName": "Willaker",
            "MiddleNames": "",
            "FullName": "Mr Billy Willaker",
            "IsFromBirth": true,
            "KnownFromDate": null
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Male",
            "DateOfBirth": "1946-06-14",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "",
            "CountryOfBirth": "",
            "TownOfBirth": ""
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "",
                "PassportNumber": "",
                "PassportIssueDate": null,
                "PassportExpiryDate": null,
                "PassportDateOfBirth": null
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [],
        "AddressList": [
            {
                "Address": {
                    "BusinessName": "",
                    "FlatNumber": "",
                    "HouseNumber": "999",
                    "HouseName": "",
                    "StreetName": "Gold Furlong",
                    "Locality": "Marston Moretaine",
                    "Town": "Bedford",
                    "County": "Bedfordshire",
                    "State": "England",
                    "Postcode": "MK44 3JZ",
                    "AddressString": "999 Gold Furlong Marston Moretaine Bedford Bedfordshire England MK44 3JZ GB",
                    "Country": "GB"
                },
                "DateMovedToThisAddress": "2000-09-28",
                "DateLeftThisAddress": null,
                "IsCurrentAddress": true
            }
        ]
    },
    "Id": 8407,
    "UniqueKey": "f799d876-64a3-474d-986e-c5d62b7c4d27",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Client-entry request

An example of a client entry order for an Employment History check, where the checkEmploymentStatus is Employed_agency.

"Checks": [
  {
    "ContactDetails": {
      "CheckEmploymentContactName": {
        "Title": "Mr",
        "FirstName": "John",
        "MiddleNames": "Alan",
        "LastName": "Smith"
      },
      "CheckEmploymentContactAddress": {
        "BusinessName": "The Agency",
        "HouseNumber": "1",
        "StreetName": "Station Road",
        "Town": "Bedford",
        "County": "Bedfordshire",
        "State": "England",
        "Postcode": "MK1 0AA",
        "Country": "GB"
      },
      "CheckEmploymentContactTelephoneNumber": "0123456789",
      "CheckEmploymentContactFaxNumber": "023456789",
      "CheckEmploymentContactEmail": "demo@example.com",
      "CheckEmploymentContactWebsite": "www.verifile.co.uk",
    },
    "CheckEmploymentStatus": "Employed_agency",
    "CheckEmploymentEmployer": "The Agency",
    "CheckEmploymentRecentPosition": "Architect",
    "CheckEmploymentContactEmployer": "Contact_from",
    "CheckEmploymentContactEmployerContactDate": "2017-12-30",
    "CheckEmploymentDoNotContactReason": "Closed over Christmas",
    "CheckEmploymentPayrollNumber": "11123589",
    "CheckEmploymentSalary": "88000",
    "CheckEmploymentNotes": null,
    "CheckEmploymentStartDate": "2017-01-02",
    "CheckEmploymentFinishDate": "2017-12-02",
    "CheckType": "EmploymentHistoryUK"
  }
]

Client-entry request

An example of a client entry order for an Employment History check, where the checkEmploymentStatus is Self_employed_directly.

"Checks": [
  {
    "EmployedDirectlyForClient": {
      "Accountant": {
        "CheckEmploymentContactAccountantName": {
          "Title": "Mr",
          "FirstName": "John",
          "MiddleNames": "Alan",
          "LastName": "Smith"
        },
        "CheckEmploymentContactAccountantAddress": {
          "HouseNumber": "11",
          "StreetName": "Zala iela",
          "Town": "Bauska",
          "State": "Bauskas novads",
          "Postcode": "3901",
          "Country": "LV"
        },
        "CheckEmploymentContactAccountantFirm": "Prime Accounts",
        "CheckEmploymentContactAccountantTel": "0123234234",
        "CheckEmploymentContactAccountantFax": "023434565464",
        "CheckEmploymentContactAccountantEmail": "demo@example.com",
        "CheckEmploymentContactAccountantWeb": "www.verifile.co.uk"
      },
      "Management": {
        "CheckEmploymentContactManagementName": {
          "Title": "Mrs",
          "FirstName": "Joanne",
          "LastName": "Steinberg"
        },
        "CheckEmploymentContactManagementAddress": {
          "HouseNumber": "20906",
          "StreetName": "Harvest Hill Ln",
          "Town": "Houston",
          "County": "Harris",
          "State": "Texas",
          "Postcode": "77073-3127",
          "Country": "US"
        },
        "CheckEmploymentContactManagementCompany": "Managers 'R' US",
        "CheckEmploymentContactManagementTel": "0123453453453",
        "CheckEmploymentContactManagementFax": "02334634634",
        "CheckEmploymentContactManagementEmail": "demo@example.com",
        "CheckEmploymentContactManagementWeb": "werifile.co.uk"
      },
      "Client": {
        "CheckEmploymentContactClientName": {
          "Title": "Ms",
          "FirstName": "Emma",
          "LastName": "Happen"
        },
        "CheckEmploymentContactClientAddress": {
          "HouseNumber": "222",
          "StreetName": "Station Road",
          "Town": "Bedford",
          "County": "Bedfordshire",
          "State": "England",
          "Postcode": "MK1 0AA",
          "Country": "GB"
        },
        "CheckEmploymentContactClientCompany": "Make It Happen",
        "CheckEmploymentContactClientTel": "012345678",
        "CheckEmploymentContactClientFax": "0234346456",
        "CheckEmploymentContactClientEmail": "demo@example.com",
        "CheckEmploymentContactClientWeb": "www.verifile.co.uk"
      }
    },
    "CheckEmploymentStatus": "Self_employed_directly",
    "CheckEmploymentSelfEmployedStatus": "own_company",
    "CheckEmploymentSelfEmployedCompanyRegistrationNo": "12345",
    "CheckEmploymentSelfEmployedCompanyCountry": "GB",
    "CheckEmploymentRecentPosition": "Designer",
    "CheckEmploymentContactEmployer": "immediate",
    "CheckEmploymentLocation": "GB",
    "CheckEmploymentPayrollNumber": "111114",
    "CheckEmploymentSalary": "994500",
    "CheckEmploymentStartDate": "2017-01-04",
    "CheckType": "EmploymentHistoryWorldwide"
  }
]

Candidate-entry request

{
    "UniqueKey": "20109cef-bd50-4ed0-a2e2-4b64389b4b08",
    "CheckGroups": [
        {
            "CheckTypeId": "EmploymentHistoryUK",
            "Quantity": 1
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth"
        },
        "PersonalInfo": {
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com"
        }
    }
}

Candidate-entry response

{
    "OrderState": {
        "StateDescription": "Awaiting candidate entry"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Awaiting candidate entry"
            },
            "Id": 6655,
            "Comment": "",
            "CompletedDate": null,
            "CheckType": "EmploymentHistoryUK"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth",
            "MiddleNames": "",
            "FullName": "Mr Paul Smyth",
            "IsFromBirth": false,
            "KnownFromDate": null
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "demo@example.com",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "",
            "CountryOfBirth": "",
            "TownOfBirth": ""
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "",
                "PassportNumber": "",
                "PassportIssueDate": null,
                "PassportExpiryDate": null,
                "PassportDateOfBirth": null
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [],
        "AddressList": []
    },
    "Id": 8408,
    "UniqueKey": "ba4940cc-0102-4352-a5b6-7566ffe388df",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Post Office Document Validation

This documentation is under review and is subject to change at any time

The Verifile Post Office Document Validation check is used to request Post Office in-branch verification of a candidate's identity documents.

Requests placed via the Verifile API will be passed immediately to the Post Office, and, if successful, the response will contain the Post Office order details and a barcode. This barcode must be presented at the post office, by the candidate, in order to complete the check and link their verification with the Post Office order.

CheckType

PostOfficeDocumentValidation

Supported Order Types

Client Entry	Candidate Entry
Yes	No

Fields

Field	Type	Description
Configuration	Integer	The Post Office offers different ways of processing checks, e.g. notification of verification only, notification of verification and failure. These are available for selection on a check-by-check basis by specifying the configuration code here. If not specified a client-specific default can be used. Field Validation Values for this field must be from the postofficeconfigurations value set. This field is optional
DocumentTypes	String Array	An array containing the list of documents to be taken by the candidate to the Post Office branch for verification.
DocumentType	Integer	An integer indicating the type of document. Field Validation Values for this field must be from the postofficedocumenttypes value set. This field is optional
Attributes	Integer Array	An array of document attributes to be verified for each document type. Field Validation Values for this field must be from the TBC value set. This field is optional
Attribute.Id	Integer	An integer indicating the attribute to be validated for the given document type. Field Validation Values for this field must be from the TBC value set. This field is optional
Attribute.Value	String	The value to be validated. E.g. if the attribute is “Last 4 digits of passport number” the four digits should be supplied here.

Request example

{
  "UniqueKey": "faa6065e-de80-41c6-8e6b-3b26bd399b39",
  "Checks": [
   {
    "CheckType": "PostOfficeDocumentValidation",
    "Configuration": "VERIFICATION ONLY",
    "DocumentTypes": [
     {
      "DocumentType": 177,
      "Attributes": [
       {
        "Id" : 261,
        "Value": "1234"
       },
       {
        "Id": 262,
        "Value": "2030-06-23"
       }
      ]
     }
    ]
   }
  ],
  "Candidate": {
    "CurrentName": {
      "Title": "Mr",
      "FirstName": "Billy",
      "LastName": "Willaker",
      "IsFromBirth": true
    },
    "AddressList": [ 
     {
        "Address": {
          "HouseNumber": "999",
          "StreetName": "Gold Furlong",
          "Locality": "Marston Moretaine",
          "Town": "Bedford",
          "County": "Bedfordshire",
          "State": "England",
          "Postcode": "MK43 0EG",
          "Country": "GB"
        },
        "DateMovedToThisAddress": "2000-09-28",
        "IsCurrentAddress": true
      }
    ],
    "PersonalInfo": {
      "DateOfBirth": "1946-06-14",
      "ApplicantType": "Candidate"
    }
  }
}

Response Fields

Field	Type	Description
OrderId	String	The Post Office order Id, supplied for reference. For further status queries, use the “Id” field returned in the Verifile order response.
Barcode	String	A Base 64-Encoded string representation of the barcode image that can be saved out to a file (as a jpg) and supplied to the candidate in print or electronic form.
Configuration	String	As per request
DocumentTypes	Array	As per request

Response example

Get Order

Once the order has completed, a webhook will be sent to alert subscribed clients that the status has changed. The status can then be queried using the order status endpoint.

This endpoint can also be used to re-download the check barcode in instances where it is lost or corrupted.

Completed checks will show the overall status of the check and a breakdown by document

Example result

Get Document Types

This is used to query the list of valid document types supported by the post office check and the corresponding attributes that can be verified.

Example Response

Get Configurations

This is used to query the list of valid Post Office configurations that can be used for the check.

Example response

Professional Membership

This documentation is under review and is subject to change at any time

The Professional Membership check will confirm whether the candidate is a member of the organisation stated.

Verifile will research:

Institution Name
Institutions contact details
Period of membership
Membership details

There are two versions of this check:

ProfessionalMembershipQualificationUK
ProfessionalMembershipQualificationWorldwide

Both are fundamentally the same, with the Worldwide version requiring a CheckAssociationCountry field.

CheckType (UK)

ProfessionalMembershipQualificationUK

CheckType (Worldwide)

ProfessionalMembershipQualificationWorldwide

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Fields

Field	Type	Description
CheckAssociationCountry	String	The country for which the check applies. Mandatory for ProfessionalMembershipQualificationWorldwide. Field Validation Values for this field must be from the country value set. This field is mandatory
CheckAssociationName	String	The name of the institution in question Field Validation The minimum length of this field is 1 characters The maximum length of this field is 100 characters This field is mandatory
CheckAssociationMembershipLevel	String	To help identify level of membership Field Validation The minimum length of this field is 1 characters The maximum length of this field is 100 characters This field is optional
CheckAssociationMembershipNumber	String	The candidate's membership number Field Validation The minimum length of this field is 1 characters The maximum length of this field is 100 characters This field is optional
CheckAssociationQualification	String	Any qualifications issued by the institution Field Validation The minimum length of this field is 1 characters The maximum length of this field is 100 characters This field is optional
CheckAssociationMembershipStatus	String	The status of the membership Field Validation The minimum length of this field is 1 characters The maximum length of this field is 50 characters This field is optional
CheckAssociationMembershipHeldDateFrom	String (yyyy[-mm-dd])	The start date of the membership
CheckAssociationMembershipHeldDateTo	String (yyyy[-mm-dd])	The end date of the membership
CheckAssociationMembershipContactName	String	The contact's name
CheckAssociationMembershipContactAddress	String	The contact's address Field Validation The maximum length of this field is 500 characters This field is optional
CheckAssociationMembershipContactTel	String (telephone number)
CheckAssociationMembershipContactFax	String (telephone number)
CheckAssociationMembershipContactEmail	String (Email address)
CheckAssociationMembershipContactWeb	String (Email address)	Field Validation The maximum length of this field is 50 characters This field is optional

Client-entry request

{
    "UniqueKey": "7a477a55-a37c-4817-8f6a-2dbf247a6d4c",
    "Checks": [
        {
            "CheckAssociationName": "Associations R Us",
            "CheckAssociationMembershipLevel": "Level 10",
            "CheckAssociationMembershipNumber": "1234",
            "CheckAssociationQualification": "Qualification",
            "CheckAssociationMembershipStatus": "Current",
            "CheckAssociationMembershipHeldDateFrom": "2010-09",
            "CheckAssociationMembershipHeldDateTo": "2010-09",
            "CheckAssociationMembershipContactTel": "0123456778",
            "CheckAssociationMembershipContactFax": "023456789",
            "CheckAssociationMembershipContactEmail": "demo@example.com",
            "CheckAssociationMembershipContactWeb": "www.verifile.co.uk",
            "CheckAssociationNotes": "notes",
            "CheckAssociationMembershipContactName": {
                "Title": "Mr",
                "FirstName": "con",
                "MiddleNames": "tact",
                "LastName": "contact name"
            },
            "CheckAssociationMembershipContactAddress": {
                "HouseNumber": "999",
                "HouseName": "My House",
                "StreetName": "Gold Furlong",
                "Locality": "Marston Moretaine",
                "Town": "Bedford",
                "County": "Bedfordshire",
                "State": "England",
                "Postcode": "MK44 3JZ",
                "Country": "GB"
            },
            "CheckType": "ProfessionalMembershipQualificationUK"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Billy",
            "LastName": "Willaker",
            "IsFromBirth": true
        },
        "AddressList": [
            {
                "Address": {
                    "HouseNumber": "999",
                    "StreetName": "Gold Furlong",
                    "Locality": "Marston Moretaine",
                    "Town": "Bedford",
                    "County": "Bedfordshire",
                    "State": "England",
                    "Postcode": "MK44 3JZ",
                    "Country": "GB"
                },
                "DateMovedToThisAddress": "2000-09-28",
                "IsCurrentAddress": true
            }
        ],
        "PersonalInfo": {
            "Gender" : "Male",
            "DateOfBirth": "1946-06-14",
            "ApplicantType": "Candidate"
        }
    }
}

Client-entry response

{
    "OrderState": {
        "StateDescription": "Application"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Application"
            },
            "CheckAssociationMembershipContactName": {
                "FullName": "Mr con tact contact name"
            },
            "CheckAssociationMembershipContactAddress": {
                "AddressString": "999 My House Gold Furlong Marston Moretaine Bedford Bedfordshire England MK44 3JZ GB"
            },
            "Id": 6644,
            "Comment": "",
            "CompletedDate": null,
            "CheckAssociationName": "Associations R Us",
            "CheckAssociationMembershipLevel": "Level 10",
            "CheckAssociationMembershipNumber": "1234",
            "CheckAssociationQualification": "Qualification",
            "CheckAssociationMembershipStatus": "Current",
            "CheckAssociationMembershipHeldDateFrom": "2010-09",
            "CheckAssociationMembershipHeldDateTo": "2010-09",
            "CheckAssociationMembershipContactTel": "0123456778",
            "CheckAssociationMembershipContactFax": "023456789",
            "CheckAssociationMembershipContactEmail": "demo@example.com",
            "CheckAssociationMembershipContactWeb": "www.verifile.co.uk",
            "CheckAssociationNotes": "notes",
            "CheckType": "ProfessionalMembershipQualificationUK"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Billy",
            "LastName": "Willaker",
            "MiddleNames": "",
            "FullName": "Mr Billy Willaker",
            "IsFromBirth": true,
            "KnownFromDate": null
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Male",
            "DateOfBirth": "1946-06-14",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "",
            "CountryOfBirth": "",
            "TownOfBirth": ""
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "",
                "PassportNumber": "",
                "PassportIssueDate": null,
                "PassportExpiryDate": null,
                "PassportDateOfBirth": null
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [],
        "AddressList": [
            {
                "Address": {
                    "BusinessName": "",
                    "FlatNumber": "",
                    "HouseNumber": "999",
                    "HouseName": "",
                    "StreetName": "Gold Furlong",
                    "Locality": "Marston Moretaine",
                    "Town": "Bedford",
                    "County": "Bedfordshire",
                    "State": "England",
                    "Postcode": "MK44 3JZ",
                    "AddressString": "999 Gold Furlong Marston Moretaine Bedford Bedfordshire England MK44 3JZ GB",
                    "Country": "GB"
                },
                "DateMovedToThisAddress": "2000-09-28",
                "DateLeftThisAddress": null,
                "IsCurrentAddress": true
            }
        ]
    },
    "Id": 8397,
    "UniqueKey": "7ca0dac1-692e-47a2-9f01-44b4b1424dae",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Candidate-entry request

{
    "UniqueKey": "1503b7bd-db5c-4a5b-afe2-af4d483e0fe6",
    "CheckGroups": [
        {
            "CheckTypeId": "ProfessionalMembershipQualificationUK",
            "Quantity": 1
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth"
        },
        "PersonalInfo": {
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "ApplicantType": "Candidate",
            "CandidateEmail": "demo@example.com"
        }
    }
}

Candidate-entry response

{
    "OrderState": {
        "StateDescription": "Awaiting candidate entry"
    },
    "Checks": [
        {
            "CheckState": {
                "StateDescription": "Awaiting candidate entry"
            },
            "CheckAssociationMembershipContactName": {
                "FullName": ""
            },
            "CheckAssociationMembershipContactAddress": {
                "AddressString": ""
            },
            "Id": 6645,
            "Comment": "",
            "CompletedDate": null,
            "CheckAssociationName": "",
            "CheckAssociationMembershipLevel": "",
            "CheckAssociationMembershipNumber": "",
            "CheckAssociationQualification": "",
            "CheckAssociationMembershipStatus": "",
            "CheckAssociationMembershipHeldDateFrom": null,
            "CheckAssociationMembershipHeldDateTo": null,
            "CheckAssociationMembershipContactTel": "",
            "CheckAssociationMembershipContactFax": "",
            "CheckAssociationMembershipContactEmail": "",
            "CheckAssociationMembershipContactWeb": "",
            "CheckAssociationNotes": "",
            "CheckType": "ProfessionalMembershipQualificationUK"
        }
    ],
    "Candidate": {
        "CurrentName": {
            "Title": "Mr",
            "FirstName": "Paul",
            "LastName": "Smyth",
            "MiddleNames": "",
            "FullName": "Mr Paul Smyth",
            "IsFromBirth": false,
            "KnownFromDate": null
        },
        "PersonalInfo": {
            "MobilePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "HomePhone": {
                "PhoneNumber": "",
                "CountryCode": ""
            },
            "Gender": "Male",
            "DateOfBirth": "1971-09-28",
            "PurchaseOrderNumber": "",
            "OtherReference": "",
            "PositionAppliedFor": "",
            "ApplicantNotes": "",
            "FSAApproved": false,
            "HasValidDrivingLicense": false,
            "ApplicantType": "Candidate",
            "CurrentNationality": "",
            "CandidateEmail": "demo@example.com",
            "BirthCertificationNumber": "",
            "MotherMaidenName": "",
            "NationalityAtBirth": "",
            "CountryOfBirth": "",
            "TownOfBirth": ""
        },
        "Identity": {
            "PassportDocument": {
                "PassportIssuingCountry": "",
                "PassportNumber": "",
                "PassportIssueDate": null,
                "PassportExpiryDate": null,
                "PassportDateOfBirth": null
            },
            "DrivingDocument": {
                "DriverLicenseType": "Unknown",
                "DriverLicenseIssuingCountry": "",
                "DriverLicenseNumber": "",
                "DriverLicenseDate": null,
                "DriverLicenseDateOfBirth": null
            },
            "NationalInsuranceNumberDocument": {
                "OverseasIdentityNumber": {
                    "IssuingCountry": "",
                    "IdentityNumber": ""
                },
                "NationalInsuranceNumber": ""
            }
        },
        "PreviousNames": [],
        "AddressList": []
    },
    "Id": 8398,
    "UniqueKey": "780b92dc-dd4f-4573-8d6b-77e0406052d8",
    "CandidateLinkKey": null,
    "CompletedDate": null,
    "Package": ""
}

Right to Work (UK)

This documentation is under review and is subject to change at any time

Verifile will use its knowledge of Home Office rules to check an individual's documents to verify their right to work in the UK (requires viewing of original documents by the client).

CheckType

RightToWorkUK

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

For a client-entry order a list of documents must be provided.

Fields

Field	Type	Description
Documents	Array of Document	The documents used as proof of right to work in the UK Field Validation This field is mandatory

Each Document in this list must have the following fields.

Fields

Field	Type	Description
DocumentType	Integer	The Id of the type of identity document Field Validation Values for this field must be from the dynamicidentitydocuments value set. This field is mandatory
DocumentSide	String	Usually front or back Field Validation Values for this field must be from the documentsides value set. This field is mandatory
FileType	Integer	The file extension Field Validation Values for this field must be from the filetypes value set. This field is mandatory
FileToken	String (UUID)	A unique token, used to avoid duplication of files Field Validation This field is mandatory
Document	String	Base64 encoded bytes of the file Field Validation This field is mandatory

Client-entry request

{
"UniqueKey": "48f5d066-5318-42d0-8375-1345c6dd25dc",
"Checks": [
{
"CheckType": "RightToWorkUK",
"Documents" : [
{
"DocumentType": 1,
"DocumentSide": "front",
"FileType": "pdf",
"FileToken": "592b3dd9-cdaf-4be2-b59d-d6ed8a56b5ef",
"Document":"JVBERi0xLjQ...ZgoxNzY0NzIKJSVFT0Y="
}
]
}
],
"Candidate": {
"PreviousNames": [ ],
"AddressList": [
{
"DateMovedToThisAddress": "2010-09-28",
"IsCurrentAddress": true,
"Address": {
"HouseNumber": "28",
"StreetName": "Gold Furlong",
"Locality": "Marston Moretaine",
"Town": "Bedford",
"County": "Bedfordshire",
"Postcode": "MK43 0EG",
"Country": "GB"
}
}
],
"CurrentName": {
"Title": "Mr",
"FirstName": "Arnold",
"LastName": "Khan",
"IsFromBirth": true
},
"PersonalInfo": {
"Gender": "Male",
"DateOfBirth": "1970-03-01",
"ApplicantType": "Candidate",
"CandidateEmail": "demo@example.com"
},
"Identity": { }
}
}

Candidate-entry request

{
"UniqueKey": "61d5e4af-1b73-4750-a6b8-ebd79cc93def",
"CheckGroups": [
{
"CheckTypeId": "RightToWorkUK",
"Quantity": 1
}
],
"Candidate": {
"CurrentName": {
"Title": "Mr",
"FirstName": "Paul",
"LastName": "Furlong"
},
"PersonalInfo": {
"Gender": "Male",
"DateOfBirth": "1971-09-12",
"ApplicantType": "Candidate",
"CandidateEmail": "demo@example.com"
}
}
}

UK Credit Check

This documentation is under review and is subject to change at any time

The UK Credit Check includes a check of

The Electoral Roll to verify a candidate's current and previous addresses.
Publicly available data covering the last 6 years to reveal adverse information, including County Court Judgments, Bankruptcies and Voluntary Arrangements.
Checks for adverse records at addresses that are linked to the candidate and may have not been disclosed by the candidate.
Finds any aliases linked to the candidate.

The check is undertaken using one set of forenames (first and middle), up to two surnames (current and previous) and up to three UK addresses.

Results will produce any CCJs (County court judgements), Bankruptcy Orders or Voluntary Arrangements the candidate has. It will also display any outstanding correction notices.

There are no check-specific fields required for this check, but for client-entry a minimum of six years address history is required, including at least one address in the UK.

CheckType

UKCreditCheckEquifax

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

Client-entry request

"Checks": [
  {
    "CheckType": "UKCreditCheckEquifax"
  }
]

Client-entry response

  "Checks": [
      {
          "CheckState": {
              "StateDescription": "Completed - Red"
          },
          "Id": 1667,
          "Comment": "",
          "CheckCreditEquifaxTotalChecksIncluded": 1,
          "CheckCreditEquifaxTotalAdverseRecords": 1,
          "CheckCreditEquifaxTotalValueOfCCJs": 1438500.0,
          "CheckCreditEquifaxLatestCCJDate": "2019-06-18",
          "CheckCreditEquifaxTotalBankruptcyOrders": 0,
          "CheckCreditEquifaxTotalVoluntaryArrangements": 0,
          "CheckCreditEquifaxTotalNoticesOfCorrection": 1,
          "CheckCreditEquifaxTotalPreviousSearches": 0,
          "CheckCreditEquifaxCurrentAddressVarified": "No",
          "CheckCreditRollingRegister": [],
          "CheckCreditCountyCourtJudgements": [
              {
                  "CheckCreditRegisterName": {
                      "Title": "",
                      "FirstName": "Jeremey",
                      "LastName": "Jones",
                      "MiddleNames": ""
                  },
                  "CheckCreditCcjDateOfBirth": "1971-09-28",
                  "CheckCreditCcjCourtDate": "2019-06-18",
                  "CheckCreditCcjValue": 1438500,
                  "CheckCreditCcjType": "County Court Judgement (England, Wales and Northern Ireland)",
                  "CheckCreditCcjSatisfiedDate": null,
                  "CheckCreditCcjCourtName": "Verifile Court",
                  "CheckCreditCcjCaseNumber": "1BDDAAA3",
                  "CheckCreditCcjCourtCode": "999",
                  "CheckCreditAddressMatchedId": 577
              }
          ],
          "CheckCreditAllSearches": [],
          "CheckCreditAliases": [],
          "CheckCreditElectoralRole": [],
          "CheckCreditMatchedAddresses": [
              {
                  "CheckCreditEquifaxAddress": {
                      "HouseNumber": "5",
                      "HouseName": null,
                      "StreetName": "Stannard Way",
                      "Locality": "",
                      "Town": "Bedford",
                      "County": "Bedfordshire",
                      "State": "",
                      "Postcode": "MK44 3JZ"
                  },
                  "CheckCreditAddressMatchedId": 577,
                  "CheckCreditAddressIsCurrent": null
              }
          ],
          "CheckCreditNoticeOfCorrection": [
              {
                  "CheckCreditCorrectionName": {
                      "Title": "",
                      "FirstName": "Jeremey",
                      "LastName": "Jones",
                      "MiddleNames": ""
                  },
                  "CheckCreditCorrectionDateCreated": "2019-06-24",
                  "CheckCreditCorrectionText": "NOTICE OF DISPUTE - THE INDIVIDUAL CONCERNED HAS DISPUTED THE ACCURACY OF THE INFORMATION REGISTERED AT THIS ADDRESS AND WE HAVE NOW CONTACTED THE SUBSCRIBER CONCERNED. CARE SHOULD THEREFORE BE TAKEN WHEN USING THE DATA AT THIS ADDRESS TO ASSESS THE CREDITWORTHINESS OF THE INDIVIDUAL CONCERNED.",
                  "CheckCreditCorrectionContinuationIndicator": "N",
                  "CheckCreditAddressMatchedId": 577,
                  "CheckCreditCorrectionDateOfBirth": "1971-09-28"
              }
          ],
          "CheckType": "UKCreditCheckEquifax"
      }
  ]

Candidate-entry request

  "CheckGroups": [
      {
          "CheckTypeId": "UKCreditCheckExperian"
      }
  ]

Candidate-entry response

  "Checks": [
      {
          "CheckState": {
          "StateDescription": "Awaiting candidate entry"
      },
      "Id": "10001",
      "Comment": "",
      "CheckType": "UKCreditCheckExperian"
      }
  ]

UK ID/AML Check

This documentation is under review and is subject to change at any time

The UK ID/AML checks establish a candidate’s identity by cross referencing personal information against a variety of sources including the UK Electoral Roll, telephone database and date of birth data held by credit providers.

There are two versions of this check:

UKIDAMLCheckUKID (Identity)
UKIDAMLCheckUKAML (AML)

Both checks are fundamentally the same, with the AML version having a larger scope of search performed against the candidate. This is mostly used by UK financial institutions to fulfil their AML (Anti Money Laundering) obligations.

When ordering either of the checks, no additional fields are required as part of the check section. However, the candidate must provide:

1 set of forenames (first and middle)
Up to 2 surnames (current and previous)
A current address

You can only order a single instance of one of these checks, therefore you need not supply the quantity field in a candidate-entry order.

Supported Order Types

Client Entry	Candidate Entry
Yes	Yes

CheckType (Identity)

UKIDAMLCheckUKID

CheckType (AML)

UKIDAMLCheckUKAML

Client-entry request

  {
    "UniqueKey": "4237a7b0-c9bf-4e5d-8c42-3bcc53c8a9ed",
    "Checks": [
      {
    "CheckType": "UKIDAMLCheckUKID"
     }
    ],
    "Candidate": {
      "PreviousNames": [ ],
      "AddressList": [
        {
                  "DateMovedToThisAddress": "2000-09-28",
                  "DateLeftThisAddress": "2017-01-01",
                  "IsCurrentAddress": false,
                  "Address": {
                      "HouseNumber": "109",
                      "StreetName": "High ",
                      "Town": "Westbury",
                      "County": "Wiltshire",
                      "Postcode": "BA13 3BN",
                      "Country": "GB"
                  }
              },
              {
                  "DateMovedToThisAddress": "2017-01-01",
                  "IsCurrentAddress": true,
                  "Address": {
                      "HouseNumber": "107",
                      "StreetName": "High ",
                      "Town": "Westbury",
                      "County": "Wiltshire",
                      "Postcode": "BA13 3BN",
                      "Country": "GB"
                  }
              }
      ],
      "CurrentName": {
        "Title": "Mr",
        "FirstName": "Jeremey",
        "LastName": "Smith-ccj-ccj-ccj",
        "IsFromBirth": true
      },
      "PersonalInfo": {
    "Gender": "Male",
    "DateOfBirth": "1971-09-28",
    "ApplicantType": "Candidate",
    "CandidateEmail": "demo@example.com"
   },
      "Identity": { }
    }
  }

Client-entry response

  {
      "OrderState": {
          "StateDescription": "Application"
      },
      "Checks": [
          {
              "CheckState": {
                  "StateDescription": "Application"
              },
              "Id": 6651,
              "Comment": "",
              "CompletedDate": null,
              "CheckType": "UKIDAMLCheckUKID"
          }
      ],
      "Candidate": {
          "CurrentName": {
              "Title": "Mr",
              "FirstName": "Jeremey",
              "LastName": "Smith-ccj-ccj-ccj",
              "MiddleNames": "",
              "FullName": "Mr Jeremey Smith-ccj-ccj-ccj",
              "IsFromBirth": true,
              "KnownFromDate": null
          },
          "PersonalInfo": {
              "MobilePhone": {
                  "PhoneNumber": "",
                  "CountryCode": ""
              },
              "HomePhone": {
                  "PhoneNumber": "",
                  "CountryCode": ""
              },
              "Gender": "Male",
              "DateOfBirth": "1971-09-28",
              "PurchaseOrderNumber": "",
              "OtherReference": "",
              "PositionAppliedFor": "",
              "ApplicantNotes": "",
              "FSAApproved": false,
              "HasValidDrivingLicense": false,
              "ApplicantType": "Candidate",
              "CurrentNationality": "",
              "CandidateEmail": "demo@example.com",
              "BirthCertificationNumber": "",
              "MotherMaidenName": "",
              "NationalityAtBirth": "",
              "CountryOfBirth": "",
              "TownOfBirth": ""
          },
          "Identity": {
              "PassportDocument": {
                  "PassportIssuingCountry": "",
                  "PassportNumber": "",
                  "PassportIssueDate": null,
                  "PassportExpiryDate": null,
                  "PassportDateOfBirth": null
              },
              "DrivingDocument": {
                  "DriverLicenseType": "Unknown",
                  "DriverLicenseIssuingCountry": "",
                  "DriverLicenseNumber": "",
                  "DriverLicenseDate": null,
                  "DriverLicenseDateOfBirth": null
              },
              "NationalInsuranceNumberDocument": {
                  "OverseasIdentityNumber": {
                      "IssuingCountry": "",
                      "IdentityNumber": ""
                  },
                  "NationalInsuranceNumber": ""
              }
          },
          "PreviousNames": [],
          "AddressList": [
              {
                  "Address": {
                      "BusinessName": "",
                      "FlatNumber": "",
                      "HouseNumber": "107",
                      "HouseName": "",
                      "StreetName": "High",
                      "Locality": "",
                      "Town": "Westbury",
                      "County": "Wiltshire",
                      "State": "",
                      "Postcode": "BA13 3BN",
                      "AddressString": "107 High Westbury Wiltshire BA13 3BN GB",
                      "Country": "GB"
                  },
                  "DateMovedToThisAddress": "2017-01-01",
                  "DateLeftThisAddress": null,
                  "IsCurrentAddress": true
              },
              {
                  "Address": {
                      "BusinessName": "",
                      "FlatNumber": "",
                      "HouseNumber": "109",
                      "HouseName": "",
                      "StreetName": "High",
                      "Locality": "",
                      "Town": "Westbury",
                      "County": "Wiltshire",
                      "State": "",
                      "Postcode": "BA13 3BN",
                      "AddressString": "109 High Westbury Wiltshire BA13 3BN GB",
                      "Country": "GB"
                  },
                  "DateMovedToThisAddress": "2000-09-28",
                  "DateLeftThisAddress": "2017-01-01",
                  "IsCurrentAddress": false
              }
          ]
      },
      "Id": 8404,
      "UniqueKey": "64d78a6b-7524-47fa-a174-419de6e8905a",
      "CandidateLinkKey": null,
      "CompletedDate": null,
      "Package": ""
  }

Candidate-entry request

{
  "UniqueKey": "f670cfe8-ef12-45de-b487-6f3e9a84079c",
  "CheckGroups": [
        {
            "CheckTypeId": "UKIDAMLCheckUKAML",
            "Quantity": 1
        }
  ],
  "Candidate": {
    "CurrentName": {
      "Title": "Mr",
      "FirstName": "Paul",
      "LastName": "Smyth"
    },
    "PersonalInfo": {
  "Gender": "Male",
  "DateOfBirth": "1971-09-28",
  "ApplicantType": "Candidate",
  "CandidateEmail": "demo@example.com"
 }
  }
}

Candidate-entry response

  {
      "OrderState": {
          "StateDescription": "Awaiting candidate entry"
      },
      "Checks": [
          {
              "CheckState": {
                  "StateDescription": "Awaiting candidate entry"
              },
              "Id": 6649,
              "Comment": "",
              "CompletedDate": null,
              "CheckType": "UKIDAMLCheckUKAML"
          }
      ],
      "Candidate": {
          "CurrentName": {
              "Title": "Mr",
              "FirstName": "Paul",
              "LastName": "Smyth",
              "MiddleNames": "",
              "FullName": "Mr Paul Smyth",
              "IsFromBirth": false,
              "KnownFromDate": null
          },
          "PersonalInfo": {
              "MobilePhone": {
                  "PhoneNumber": "",
                  "CountryCode": ""
              },
              "HomePhone": {
                  "PhoneNumber": "",
                  "CountryCode": ""
              },
              "Gender": "Male",
              "DateOfBirth": "1971-09-28",
              "PurchaseOrderNumber": "",
              "OtherReference": "",
              "PositionAppliedFor": "",
              "ApplicantNotes": "",
              "FSAApproved": false,
              "HasValidDrivingLicense": false,
              "ApplicantType": "Candidate",
              "CurrentNationality": "",
              "CandidateEmail": "demo@example.com",
              "BirthCertificationNumber": "",
              "MotherMaidenName": "",
              "NationalityAtBirth": "",
              "CountryOfBirth": "",
              "TownOfBirth": ""
          },
          "Identity": {
              "PassportDocument": {
                  "PassportIssuingCountry": "",
                  "PassportNumber": "",
                  "PassportIssueDate": null,
                  "PassportExpiryDate": null,
                  "PassportDateOfBirth": null
              },
              "DrivingDocument": {
                  "DriverLicenseType": "Unknown",
                  "DriverLicenseIssuingCountry": "",
                  "DriverLicenseNumber": "",
                  "DriverLicenseDate": null,
                  "DriverLicenseDateOfBirth": null
              },
              "NationalInsuranceNumberDocument": {
                  "OverseasIdentityNumber": {
                      "IssuingCountry": "",
                      "IdentityNumber": ""
                  },
                  "NationalInsuranceNumber": ""
              }
          },
          "PreviousNames": [],
          "AddressList": []
      },
      "Id": 8402,
      "UniqueKey": "0eae11f2-ae5a-407a-8142-4361cad81c86",
      "CandidateLinkKey": null,
      "CompletedDate": null,
      "Package": ""
  }

Verifile API Documentation

Quick start

Place an order

Request body

Complete example in C#

A few things to note -

About

Sandbox

Authentication

Authentication headers

Account Setup

How to...

How to create an order

Candidate-entry order

Client-entry order

How to order a package

Package Order, full JSON body

How to get the status of an order

How to retrieve a Final Report

How to register a webhook to be notified of status changes

How to get a list of all open orders

How to place an order under a subsidiary account

How to get a list of packages that may be ordered

Concepts

Checks and Packages

Client-entry and Candidate-entry Orders

Final Report

Interim Report

API Reference

Field Types

Candidate Object

Current Name Object

Example of a CurrentName for a client-entry order

Example of a CurrentName for a candidate-entry order

Previous Names Object

Example of PreviousNames Object

Generic Name Object

Example

Generic Address Object

Example address

Personal Information Object

Additional notes

Example of personal information supplied for a candidate-entry order

Example of personal information supplied for a client-entry order

Telephone Object

Examples

Address List Object

Example

Identity Object

Example of an Identity Object

Passport Document Object

Example of a Passport Document Object

Driving Document Object

Example of a Driving Document Object

National Insurance Number Document Object

Example of a National Insurance Number Document Object

Overseas Identity Number Object

Example of an Overseas Identity Number Object

Value Sets

Sample Response

Get values for a valueset

Sample response for valueset title

Order Statuses

Validation

Packages

Attachments

Upload attachment

Fields

Attachment restrictions

Get Attachment Info

Downloading an attachment

Check Types

Sample response

DBS Document Helper

Sample response

Sample response

Webhooks

The webhook object

Fields

Manage webhooks in the Verifile portal

Sample response for valueset `title`