The majority of the W2 APIs use the KYC Check endpoint.
How to use
To call the endpoint you will need to perform a HTTP POST request to the URL:
Request
A request typically contains of 5 properties:
| Property | Description |
|---|---|
| Bundle | The Bundle section states which bundle you are calling and is mandatory for every service call. A bundle is a collection of services which will be agreed with W2 Support. This is mandatory for every request |
| ClientReference | A reference identifying this call for your reference i.e. 'My Company Testing'. |
| Data | The Data object contains all the information about the individual or organisation you are querying. Which fields you need to include will be different for each service and many of them are only used for specific services. This is mandatory for every request |
| Files | This element is provided to supply the details of documents that are required for a service in the bundle to complete its work. For example, when using the IDDocumentCheck service, an image of the document must be associated with the call. This association is performed by adding the Unique ID of the document that was returned when it was uploaded to an item in this array. |
| Options | These are optional parameters for some extra fields not covered in the Data object. The whole section is optional. The most common use is to set Sandbox mode, where you can call the service and get standard responses. For further information, each service has examples of how to structure a call to the sandbox. |
Client provided data
This section simply reflects back information that was submitted in the API call.
| Property | Description |
|---|---|
| ClientReference | This reflects back the client reference that was supplied in the request. |
| ClientSubaccount | An optional reference to identify which of your client accounts this call was made for. |
| ClientUser | An optional reference to identify which individual user made this call. For future compatibility with W2 products we suggest this value should be the user's email address. |
| RefersToServiceCallReference | Links this call to a previous call by specifying the previous ServiceCallReference. |
Example Request
Here is a full KYC Check request (SIS Plus service call) detailing every data option. Not every data option is required when you call the endpoint. It is dependant on the service you are using.
{
"Bundle": "Bundle123",
"ClientReference": "MyReference123",
"Data": {
"AgeVerificationPassIf": 0,
"AgeVerificationThreshold": 0,
"City": "Newport",
"Country": "Wales",
"County": "Gwent",
"DateOfBirthMatchThreshold": 80,
"DayOfBirth": 10,
"DrivingLicenceNumber": "123",
"Email": "[email protected]",
"Flat": "12",
"Forename": "Tyrion",
"Gender": "Male",
"HouseName": "Casterly Rock",
"HouseNumber": "10",
"IP": "192.168.0.1",
"IdCardNumber": "123",
"MRZ": ">>123>>",
"Maiden": "???",
"MiddleNames": "James",
"MobileNumber": "001",
"MonthOfBirth": 10,
"NameQuery": "Tyrion Lannister",
"NameQueryMatchThreshold": 80,
"NationalId": "123",
"PassportNumber": "123",
"PersonalId": "123",
"PhoneNumber": "000123",
"PlaceOfBirth": "Lannisport",
"Postcode": "LANN1",
"ProfileId": "123-123-123-123",
"Region": "Westerlands",
"Street": "Lannisport Street",
"Surname": "Lannister",
"TaxCode": "123",
"Title": "Lord",
"TravelVisaNumber": "123",
"YearOfBirth": 273
},
"Files": [{
"Id": "123",
"Reference": "123-ref-321",
"Group": "group1",
"Index": 0,
"Service": "W2_DATA_IDVCHECK_013"
}
],
"Options": {
"Sandbox": "False",
"Key": "Value"
}
}
Response
The response received, will contain 3 properties
| Property | Description |
|---|---|
| clientReference | The reference sent in the request used for identifying this call i.e. 'My Company Testing'. |
| result | The contents within this field will differ based on the service called. See the service page for each service you are calling. |
| transaction | The transaction provides the interpret result for the Bundle See the Transaction Information section below for additional details |
Transaction Information
This section contains the interpret result for the whole bundle, the service call reference and a section of meta data for each service.
| Property | Description |
|---|---|
| interpretResult | The validation result of the Interpret function. 1. Pass - The information supplied to the bundle passed validation. 2. Fail- The information supplied to the bundle failed validation. 3. Inconclusive- It was not possible to generate a clear validation result from the information supplied. It may be necessary to refer this query for further investigation. 4. NoInterpretPerformed - No interpret was performed in this case. Check the other information returned by the services to determine why. 5. NotApplicable - Interpret is not enabled for this bundle. |
| serviceTransactions | A collection of ServiceTransactionInformation objects. See below |
| serviceCallReference | A unique reference for this service call. |
Service Transaction Information
Every service that is called will return one of these:
| Property | Description |
|---|---|
| service | The service that was invoked. |
| serviceInterpretResult | The validation result of the service interpret function. 1. Pass - The query data resulted in a pass. 2. Fail - The query data resulted in a failure. 3. Inconclusive - The query data resulted in an inconclusive outcome. 4. NoResults - The query data returned no results. 5. OneResult - The query data returned a single result. 6. MultipleResults - The query data returned multiple results. 7. NotApplicable - Interpret is not applicable to the call or wasn't enabled. 8. NotPerformed - An error prevented this result from being categorised. |
| serviceTransactionResult | The validation result for service transaction. 1. Success - The service executed successfully. 2. SuccessNoResults - The service executed successfully but no results were generated. 3. SuccessIncompleteResults - The service executed successfully but too many results were generated to return them all, so the results have been truncated. 4. MultipleChoices - The service could not continue as there are multiple choices available and one of them must be selected or the query must be submitted with more concise information in order to complete execution. 5. ClientErrorInsufficientInformation - There was insufficient information for the service to execute. Check that all of the required fields for the service were supplied. 6. NotExecutedDueToPreviousHalt - The service was not executed because a previous service in the bundle triggered a halt. 7. ServerErrorGeneralError - A general error occurred on the server trying to run the service. |
| serviceTransactionResultMessage | The message associated with the ServiceTransactionResult if applicable. The ServiceTransactionResultMessage is usually null, but in some cases may provide some insight into the ServiceTransactionResult. For example, if a service returns SuccessIncompleteResults the ServiceTransactionResultMessage may contain an explanation of why, such as there being a limit of 100 results per query. There is no standard across services for this field so it should not be relied upon, instead, it is better to use it for debugging or additional information and rely on the ServiceTransactionResult which has consistent behaviour. |
| validationResult | The validation result... 1. Pass - The information supplied to the service passed validation 2. Fail - The information supplied to the service failed validation. 3. Inconclusive - It was not possible to generate a clear validation result from the information supplied. It may be necessary to refer this query for further investigation. 4. NoValidationPerformed - No validation was performed in this case. Check the other information returned by the service to determine why. 5. NotApplicable - The service is not a service that performs validation and therefore validation is not applicable. |
| serviceValidationDetails | This field provides information about the pre-execution validation step and should be read in conjunction with the ValidationResult field. |
| haltTriggered | True if the service halted after this service |
Example Response
Here is a KYC Check Response Example from a SIS Plus Service Call:
{
"clientReference": "123-456-789",
"results": {
"sisPlusCheckResult": {
"matchResults": [
{
"matchType": "Person",
"name": "John Dave Smith",
"nameMatchScore": 85,
"profileId": "SANC-d28cdbbd-5c0e-1a1b-4c1c-88a6b5790e82"
},
{
"matchType": "Person",
"name": "John Dave Smith",
"nameMatchScore": 85,
"profileId": "SANC-081d73e2-b1cd-baeb-176b-cf1607b75381"
},
{
"matchType": "Person",
"name": "John Dave Smith",
"nameMatchScore": 85,
"profileId": "SANC-dac80327-376e-6784-e793-3d39904726f5"
},
{
"matchType": "Person",
"name": "Dave John Smith",
"nameMatchScore": 80,
"profileId": "SANC-9763b970-f325-77bc-5c7e-46d7c18b3f06"
}
]
}
},
"transaction": {
"interpretResult": "NotApplicable",
"serviceCallReference": "8bb44731-9103-47b2-979e-f27c69f9d68b",
"serviceTransactions": [
{
"haltTriggered": false,
"service": "SISPlusCheck",
"serviceInterpretResult": "MultipleResults",
"serviceTransactionResult": "Success",
"serviceTransactionResultMessage": "This call was generated using sandbox mode",
"validationResult": "Pass"
}
]
}
}