Request Structure
This guide details all the parameters required for a request to the Tiller Verifications API. The parameters are grouped into four sections: External Reference, Options, Checks, and Profile.
Introduction to the Request Structure
The Tiller Verifications API uses a well-defined request structure to ensure that all the required information is included to perform verification checks effectively. Each request is composed of several key sections. Understanding these sections is essential for building robust integrations and achieving reliable results.
The request is divided into the following components:
External Reference: This provides a unique identifier for tracking your request. It acts as a client-generated reference to link API responses to specific operations in your system.
Options: This section configures the behaviour of the request. Options such as asynchronous or synchronous processing and mock mode for testing.
Checks: This is the core of the verification request. It specifies what checks need to be performed. Multiple check types can be included in a single request, provided the necessary information for each check is supplied.
Profile: This section contains the personal and address details of the individual or entity being verified. Depending on the type of check, the profile must include specific fields such as names, date of birth, and addresses. Addresses can be provided in either structured or unstructured formats, though structured formats are recommended for higher match accuracy.
External Reference
The externalReferenceId parameter is used to uniquely identify a request.
externalReferenceId
string
Yes
A unique identifier for your request, provided by your system. This helps in tracking specific requests.
Example:
"externalReferenceId": "ABCDEFGHI123456789"Options
The options parameter defines how the request is processed.
runAsync
boolean
Yes
Determines whether the request is processed asynchronously or synchronously.
- true: Returns a correlation ID; the results must be fetched in a subsequent request.
- false: Returns the results directly.
mock
boolean
No
When set to true, the request is processed in a simulated environment for testing purposes.
Example:
"options": {
"runAsync": false,
"mock": true
}Checks
The checks array contains details about the verification checks to perform.
Available Check Types
The following checks are currently supported by the Verifications API:
Address Verification Verifies the subject’s address against trusted data sources.
Background Checks Performs PEP (Politically Exposed Persons) & Sanctions screening and Adverse Media checks.
UK Bank Account Check Verifies the subject's ownership of a UK bank account.
You can request one or more of these services in a single verifications request.
Check Type Fields
checkTypeId
1 (required)
2 (required)
3 (required)
externalCheckReferenceId
Required
Required
Required
maximumSources
Required (default: 3)
Required (default: 3)
Required (default: 3)
checkMethod
Required (default: 1)
Required (default: 1)
Required (default: 1)
matchesRequired
Required (default: 1)
N/A
N/A
checkTypeId: Identifies the type of verification being performed.
1= Address Verification2= Screening (PEP & Sanctions/Adverse Media)3= UK Bank Account Check
externalCheckReferenceId: A unique client-provided identifier for the check, useful for tracking.
maximumSources: Specifies the maximum number of sources to query for the check. The default value is 3 for most checks.
CheckMethod: Determines how the check is performed.
1= Sequentially (default)2= In parallel
matchesRequired: Specifies the minimum number of matches required for the check to pass. The default value is 1.
Example - one check in request:
"checks": [
{
"checkTypeId": 1,
"externalCheckReferenceId": "Check-12345",
"maximumSources": 3,
"CheckMethod": 1,
"matchesRequired": 1
}
]Example - multiple checks in request:
"checks": [
{
"checkTypeId": 1, // Address Verification
"externalCheckReferenceId": "AddressCheck-12345",
"maximumSources": 3, // Default value is 3
"CheckMethod": 1, // Sequential check
"matchesRequired": 1, // Default value is 1
},
{
"checkTypeId": 2, // Screening
"externalCheckReferenceId": "ScreeningCheck-67890"
"maximumSources": 3, // Default value is 3
"CheckMethod": 1, // Sequential check
},
{
"checkTypeId": 3, // UK Bank Account Check
"externalCheckReferenceId": "BankCheck-98765"
"maximumSources": 3, // Default value is 3
"CheckMethod": 1, // Sequential check
}
]Profile
The profile contains personal, address and bank details for the individual being verified.
Profile Requirements by Check Type
The table below outlines the specific profile fields required for each check type supported by the Tiller Verifications API. Each column specifies whether the field is required, optional, or not applicable (N/A) for the respective check type.
titleID
Optional
Optional
Optional
firstName
Required
Required
Required
lastName
Required
Required
Required
middleName
Optional
Optional
Optional
dateOfBirth
Optional
Optional (preferred)
Required
currentAddress.structured
Required (preferred)
N/A
N/A
currentAddress.unstructured
Required (if structured address unavailable)
N/A
N/A
bankDetails.accountNumber
N/A
N/A
Required
bankDetails.sortCode
N/A
N/A
Required
titleId: Optional, but useful for added clarity, especially in Screening checks, but optional for all check types.
firstName / lastName: The subject's first and last names are required across all check types to identify the individual.
middleName: Including the middle name can enhance the accuracy of checks but is optional for all check types.
dateOfBirth: While optional for Address Verification and Screening, it is needed for UK Bank Account checks to ensure accurate matches.
currentAddress.structured: A structured address is preferred for Address Verification, as it improves the likelihood of a positive match.
currentAddress.unstructured: If structured data is unavailable, an unstructured address may be used for Address Verification, though it reduces accuracy.
bankDetails.accountNumber / bankDetails.sortCode: These fields are mandatory for UK Bank Account checks to validate the account details.
Profile parameters
titleID
integer
- 1: Mr
- 2: Mrs
- 3: Ms
- 4: Miss
genderType
integer
The individual's gender.
- 1: Male
- 2: Female
firstName
string
The individual's first name.
middleName
string
The individual's middle name (if available).
lastName
string
The individual's last name.
dateOfBirth
string
The individual's date of birth in YYYY-MM-DD format.
Current Address
The currentAddress parameter provides the individual's current residence details.
Structured address fields
flatApartmentSubBuilding
string
No
Flat or apartment number (if applicable).
buildingNumber
string
No
Building number (if applicable).
buildingName
string
No
Name of the building (e.g., "Example House").
At least one of building number, building name , flat number or road street is required.
roadStreet
string
No
Street or road name (e.g., "Example Street").
district
string
No
Name of the town or city (e.g., "Exampleton").
townCity
string
No
District name (if applicable).
stateProvinceName
string
No
State or province name (e.g., "Exampleshire").
stateProvinceCode
string
No
State or province code (e.g., "FL" for US state Florida).
postZipCode
string
No
Postcode or ZIP code (e.g., "EX12AB").
countryCode
string
Yes
dateFrom
string
No
Date when the individual started living at this address (in YYYY-MM-DD format).
Example:
"profile": {
"titleId": 1, // Mr
"genderTypeId": 1, // Male
"firstName": "John",
"middleName": "Charles",
"lastName": "Smith",
"dateOfBirth": "1980-06-12",
"currentAddress": {
"structured": {
"flatApartmentSubBuilding": "10A",
"BuildingNumber": "50",
"BuildingName": "Example House",
"RoadStreet": "Example Street",
"townCity": "Exampleton",
"district": "Exampleshire",
"stateProvinceName": "Example",
"stateProvinceCode": "EG",
"postZipCode": "EX12AB",
"countryCode": "GB",
"dateFrom": "2020-01-03"
}
}
}
Unstructured Address
If you are unable to map a client’s address to the structured format, you can provide an unstructured address in the request.
Note that using an unstructured address decreases the likelihood of achieving a positive match since it may lack the precision of a structured format. Unstructured addresses should only be used as a fall-back when structured details are unavailable.
address1
string
Yes
address2
string
No
address3
string
No
address4
string
No
address5
string
No
townCity
string
No
stateCounty
string
No
postZipCode
string
No
countryCode
string
Yes
dateFrom
string
No
Example
"currentAddress": {
"unstructured": {
"address1": "10A",
"address2": "50",
"address3": "Example House",
"address4": "Example Street",
"address5": "",
"townCity": "Exampleton",
"stateCounty": "Exampleshire",
"postZipCode": "EX12AB",
"countryCode": "GB",
"dateFrom": "2013-01-22",
"dateTo": "2020-06-11"
}
}Bank Details
The bankDetails object in the profile section is required for performing a UK Bank Account Check (CheckTypeId: 3). It contains the necessary information to validate the ownership of a UK bank account against an individual.
Bank Account Fields
accountNumber
string
Yes
The 8-digit bank account number.
sortCode
string
Yes
The 6-digit bank sort code in the format XXXXXX.
openedDate
string
Optional
The date the bank account was opened, provided in format (YYYY-MM-DD). Optional but recommended for added precision.
Example:
"bankDetails": {
"accountNumber": "12345678",
"sortCode": "12-34-56",
"openedDate": "2015-03-10"
}Key Best Practices
Accuracy and Completeness: Always include all required fields for the checks you are performing to maximize the chances of successful verification.
Structured Data: Use structured addresses and complete profile details wherever possible to achieve higher match rates.
Traceability: Leverage unique identifiers such as
externalReferenceIdandexternalCheckReferenceIdfor efficient tracking and troubleshooting.Security: Ensure all requests are securely transmitted with the required JWT authentication token.
By following these guidelines, you can build robust integrations with the Tiller Verifications API, enabling efficient, secure, and accurate compliance and verification processes. If you need further assistance or guidance, please contact support@tillertech.com.
Last updated