API Response

The response from the API is equivilent to making a GET Order request in that the full schema of the JSON is returned.


Response codes

The following are repsonse codes you can expect to recieve from the API throught it's use.

Code Description
200 (OK) Any operation that succeeds but does not create an order or upload a file, e.g. Get Order. The response body may include the item requested.
201 (Created) Order placed, file uploaded. This response is used even if the request is a duplicate of an already processed request, i.e. has the same order GUID.
400 (Bad Request) An error has prevented the operation completing, e.g. a validation error. The body should include error information that identifies the item in error and the error that occurred.
401 (Unauthorized) The VerifileUserId request header that was supplied is not valid.
403 (Forbidden) The VerifileUserId request header that was supplied does not have sufficient permissions to complete the request.
404 (Not Found) The item referenced doesn’t exist, e.g. request for non-existent order or attachment.
405 (Method Not Allowed) The HTTP request method, e.g. GET, is not allowed on the endpoint.
413 (Payload too large) Attempting to upload a file that is too large.

Client/Candiate order response

In an order response you get some additional fields that are not available when placing an order, such as full name in the Current Name or Previous Names section. In addition, if you have not supplied a a string value field it will be returned as an empty sting as default, with the exeception of ddate fields which are returned as NULL values.

See the below breakdown of each section.

OrderState

The order state object gives you the overall state of the order in a human readable format.

                
{
  "OrderState": {
    "StateDescription": "Application" 
  },   
                
            

Checks

The checks section is returned for both client and candidate order and contains the orders checks. For client entry orders, all of the fields in the check are returned contianing the input values and the default values where none were supplied.

The checks section also contain a state of each check and a unique ID for the check.

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

Candidate

The full candidate object is returned for client and candidate entry order.

                
  "Candidate": {
                
            

Current Name

The current name section additional contains a full name field. This is a concatenation of the title, first name middle names and last name. Where no middle names are supplied, it is completely omitted. This there is only 1 space between first and last name.

                
    "CurrentName": {
      "IsFromBirth": false,
      "KnownFromDate": "2005-01-01",
      "Title": "Mr",
      "FirstName": "John",
      "MiddleNames": "Alan",
      "LastName": "Smith",
      "FullName": "Mr John Alan Smith"
    },                    
                
            

Previous Names

Like the current name section, the previous name section additionally contains a full name field.

                
    "PreviousNames": [
      {
        "IsFromBirth": true,
        "KnownFromDate": null,
        "KnownToDate": "2005-01-01",
        "Title": "Mr",
        "FirstName": "John",
        "MiddleNames": "Alan",
        "LastName": "Smith-Jones",
        "FullName": "Mr John Alan Smith-Jones"
      }
    ],               
                
            

Personal Info

The personal info section returns all infomation, including defaults where no values were supplied.

                
    "PersonalInfo": {
      "MobilePhone": {
        "PhoneNumber": "",
        "CountryCode": ""
      },
      "HomePhone": {
        "PhoneNumber": "",
        "CountryCode": ""
      },
      "Gender": "Male",
      "DateOfBirth": "1961-08-29",
      "PurchaseOrderNumber": "",
      "OtherReference": "",
      "PositionAppliedFor": "",
      "ApplicantNotes": "",
      "FSAApproved": false,
      "HasValidDrivingLicense": false,
      "ApplicantType": "Candidate",
      "CurrentNationality": "GB",
      "CandidateEmail": "",
      "BirthCertificationNumber": "",
      "MotherMaidenName": "",
      "NationalityAtBirth": "",
      "CountryOfBirth": "",
      "TownOfBirth": ""
    },             
                
            

Address List

Within the address list section, the address section returns an AddressString field which is a concatenation of all the supplied address fields.

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

Identity

The identity section returns all infomation, including defaults where no values were supplied.

                
    "Identity": {
      "PassportDocument": {
        "PassportIssuingCountry": "",
        "PassportNumber": "",
        "PassportIssueDate": null,
        "PassportExpiryDate": null
      },
      "DrivingDocument": {
        "DriverLicenseType": "Unknown",
        "DriverLicenseIssuingCountry": "",
        "DriverLicenseNumber": "",
        "DriverLicenseDate": null
      },
      "NationalInsuranceNumberDocument": {
        "OverseasIdentityNumber": {
          "IssuingCountry": "",
          "IdentityNumber": ""
        },
        "NationalInsuranceNumber": "JR123456A"
      }
    }
  },        
                
            

Id

The Id is the unique order ID which can be used to upload attachments, get the status, final report and get the full detail of orders.

                
  "Id": "100001"
}