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.



    

Read more about authentication

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

Register a webhook URL to receive notification when

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

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

or

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": ""
  }