W2 DocsCase Management
What is a case?
A case is a collection of data attributes on a individual or entity on which the verification will be performed. To trigger a service you will need to create a case containing the attributes you want to return.
Create
The section below describes how to create Cases.
How to use
To call the endpoint you will need to perform a HTTP POST request to the URL:
Request
The following properties pertain for a creation of a case.
| Property Name | Type | Optional/Mandatory | Notes |
|---|---|---|---|
| ClientReference | String | Mandatory | While mandatory the client reference does not have to be unique. You can use this property to link Cases back to entities in your own systems. |
| Forename | String | Optional | The Forename of the individual. |
| MiddleNames | String | Optional | The MiddleNames of the individual. |
| Surname | String | Optional | The Surname of the individual. |
| DayOfBirth | Integer | Optional | The DayOfBirth of the individual. |
| MonthOfBirth | Integer | Optional | The MonthOfBirth of the individual. |
| YearOfBirth | Integer | Optional | The YearOfBirth of the individual. |
| Title | String | Optional | The Title of the individual. |
| HouseName | String | Optional | The HouseName of the individual. |
| HouseNumber | String | Optional | The HouseNumber of the individual. |
| Street | String | Optional | The Street of the individual. |
| TownCity | String | Optional | The Town/City of the individual. |
| County | String | Optional | The County of the individual. |
| Country | String | Optional | THe Country of the individual. |
| Postcode | String | Optional | The Postcode of the individual. |
| Type | String | Optional | The Type of case. If blank the case type will default to an individual case type. |
| OngoingMonitoring | Boolean | Optional | Set OngoingMonitoring. |
| String | Optional | The Email of the individual. | |
| Region | String | Optional | The Region of the individual. |
| TaxCode | String | Optional | The TaxCode of the individual. |
| PlaceOfBirth | String | Optional | The PlaceOfBirth of the individual. |
| DrivingLicenceNumber | String | Optional | The DrivingLicenceNumber of the individual. |
| MRZ | String | Optional | The MRZ of the individual. |
| Gender | String | Optional | The Gender of the individual. |
Example Request
json
{
"Forename": "TEST_FORENAME",
"Surname": "TEST_SURNAME",
"DayOfBirth": 1,
"MonthOfBirth": 1,
"YearOfBirth": 2001,
"ClientReference": "REST_TEST",
"HouseNumber": "20",
"Country": "GBR",
"Postcode": "CF3 3CA",
"Type": "Person",
"OngoingMonitoring":true,
"Email": "[email protected]",
"Region":"South East",
"TaxCode":"123",
"PlaceOfBirth":"London, United Kingdom",
"DrivingLicenceNumber":"RUSSF802087TG9EV11",
"MRZ":"P<CZESPECIMIN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<99003853<1CZE1101018M120704611010111<<<<<<94",
"Gender":"M"
}
Example Response
The W2 CaseId will be provided if successfully created.
json
{
"caseId": "cd35f8a0-f30c-4cfc-9bcb-12bf58d44876"
}
Update
Situations where you may need to update a case include:
- If an individual gets married and their surname changes.
- If a subject moved house.
- If there was a error in the original case creation.
- If you get additional information you want included in the case.
How to use
To call the endpoint you will need to perform a HTTP PUT request to the URL:
Request
The following properties pertain for updating a case.
WARNING
Please note that updates to a case via this endpoint by replace it's attributes entirely, therefore any missing or empty properties below will clear the relevant case attribute
| Property Name | Type | Optional/Mandatory | Notes |
|---|---|---|---|
| ClientReference | String | Mandatory | Your ClientReference. |
| Forename | String | Optional | The Forename of the individual. |
| MiddleNames | String | Optional | The MiddleNames of the individual. |
| Surname | String | Optional | The Surname of the individual. |
| DayOfBirth | Integer | Optional | The DayOfBirth of the individual. |
| MonthOfBirth | Integer | Optional | The MonthOfBirth of the individual. |
| YearOfBirth | Integer | Optional | The YearOfBirth of the individual. |
| Title | String | Optional | The Title of the individual. |
| HouseName | String | Optional | The HouseName of the individual. |
| HouseNumber | String | Optional | The HouseNumber of the individual. |
| Street | String | Optional | The Street of the individual. |
| TownCity | String | Optional | The Town/City of the individual. |
| County | String | Optional | The County of the individual. |
| Country | String | Optional | THe Country of the individual. |
| Postcode | String | Optional | The Postcode of the individual. |
| Type | String | Optional | The Type of case. If blank the case type will default to an individual case type. |
| OngoingMonitoring | Boolean | Optional | Set OngoingMonitoring. |
| String | Optional | The Email of the individual. | |
| Region | String | Optional | The Region of the individual. |
| TaxCode | String | Optional | The TaxCode of the individual. |
| PlaceOfBirth | String | Optional | The PlaceOfBirth of the individual. |
| DrivingLicenceNumber | String | Optional | The DrivingLicenceNumber of the individual. |
| MRZ | String | Optional | The passport MRZ of the individual. |
| Gender | String | Optional | The Gender of the individual. |
Example Update Case Request
json
{
"Forename": "TEST_FORENAME_NEW",
"Surname": "TEST_SURNAME_NEW",
"DayOfBirth": 2,
"MonthOfBirth": 2,
"YearOfBirth": 2002,
"ClientReference": "REST_TEST_NEW",
"HouseNumber": "22",
"Country": "GBR",
"Postcode": "CF3 3CA",
"Type": "Person",
"OngoingMonitoring":false,
"Email": "[email protected]",
"Region":"South West",
"TaxCode":"124",
"PlaceOfBirth":"Cardiff, United Kingdom",
"DrivingLicenceNumber":"RUSSF802087TG9EV12",
"MRZ":"P<CZESPECIMIN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<99003853<1CZE1101018M120704611010111<<<<<<94",
"Gender":"M"
}
Example Update Case Response
Updating a case returns a Case Id for the updated case.
json
{
"Your Case has been updated succesfully",
"caseId": "cd35f8a0-f30c-4cfc-9bcb-12bf58d44876"
}
Get
Retrieves a Case by it's Id
How to use
To call the endpoint you will need to perform a HTTP GET request to the URL:
| API Version | Url |
|---|---|
| 1.4 | https://api.w2globaldata.com/Cases/{caseId}?api-version=1.4 |
| 1.5 | https://api.w2globaldata.com/Cases/{caseId}?api-version=1.5 Latest |
The W2 Case will be returned, if found.
Example Response
Example Successful Get Cases Response
json
{
"id": "4dbbbc65-e20e-4317-b395-5525405a4955",
"companyId": 1,
"type": "Person",
"forename": "Kev",
"middleNames": "",
"surname": "Flemming",
"dayOfBirth": 0,
"monthOfBirth": 0,
"yearOfBirth": 0,
"clientReference": "some ref",
"title": "something",
"houseName": "number zero",
"houseNumber": "0a",
"street": "string",
"townCity": "something else",
"county": "string",
"country": "string",
"postcode": "string",
"email": "string",
"ongoingMonitoring": true,
"creationDate": "2021-02-08T16:31:46.9916806Z",
"lastUpdatedDate": "2021-05-11T09:33:50.4035756Z",
"Region":"South East",
"TaxCode":"123",
"PlaceOfBirth":"London, United Kingdom",
"DrivingLicenceNumber":"RUSSF802087TG9EV11",
"MRZ":"P<CZESPECIMIN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<99003853<1CZE1101018M120704611010111<<<<<<94",
"Gender":"M"
}
Search
The section below describes how to call the Search Case endpoint. If no search criteria is entered, the endpoint will retrieve the top 100 cases.
How to use
To call the endpoint you will need to perform a HTTP GET request to the URL:
| API Version | Url |
|---|---|
| 1.5 | https://api.w2globaldata.com/Cases?RiskGroup=low&PageNumber=0&PageSize=1&api-version=1.5 Latest |
Pagination Options
There are two required pagination options that need to be provided in the query string.
- PageNumber
- PageSize
The page size is the number of results we wish to return per page. The page size has a range of 1-1000. The page number is the zero-based index of the page we wish to return.
Searchable fields
- Forename
- Surname
- Client Reference
- Day of Birth
- Month of Birth
- Year of Birth
- Postcode
- Risk Group
- Email
When searching using a risk group name, a full name must be given i.e. 'low' or 'high'. Risk group names are case sensitive.
Example Search Response
The W2 Case(s) will be returned, if found.
json
{
"count": 1,
"caseSummarys": [
{
"id": "ce04915e-4baa-4b1a-a964-da90e1c6306f",
"forename": "John",
"surname": "Preston",
"dayOfBirth": 1,
"monthOfBirth": 3,
"yearOfBirth": 2010,
"clientReference": "efg",
"riskGroup": "low",
"lastUpdatedDate": "2021-08-06T14:19:28.7628906Z",
"email": "[email protected]"
}
],
"stats": {
"totalCount": 3,
"pageCount": 3
}
}
Get Results
The section below describes how to call the Get Case Results endpoint. This endpoint retrieves the latest 100 results.
How to use
To call the endpoint you will need to perform a HTTP GET request to the URL:
| API Version | Url |
|---|---|
| 1.4 | https://api.w2globaldata.com/Cases/{caseId}/results?api-version=1.4 |
| 1.5 | https://api.w2globaldata.com/Cases/{caseId}/results?api-version=1.5 Latest |
The W2 Case Results will be returned, if found.
Example Get Results Response
json
{
"caseId": "437fb3e1-4430-4265-84da-cc22aa1fde19",
"results": [
{
"id": "e73f75a2-6160-46b9-b1e2-2753e9fbcbb8",
"caseId": "437fb3e1-4430-4265-84da-cc22aa1fde19",
"type": "monitoring",
"reference": "My monitoring reference",
"resultDate": "2021-02-15T10:03:39.3691603+00:00",
"numberOfAlerts": 0
},
{
"id": "6cb53ec0-14d2-4579-9b3a-92e29ca63369",
"caseId": "437fb3e1-4430-4265-84da-cc22aa1fde19",
"type": "monitoring",
"reference": "My monitoring reference",
"resultDate": "2021-02-15T09:44:29.547256+00:00",
"numberOfAlerts": 26
}]
}
Get Audit History
The section below describes how to call the Getting Case Audit History endpoint.
How to use
To call the endpoint you will need to perform a HTTP GET request to the URL:
| API Version | Url |
|---|---|
| 1.4 | https://api.w2globaldata.com/Cases/{caseId}/audits?api-version=1.4 |
| 1.5 | https://api.w2globaldata.com/Cases/{caseId}/audits?api-version=1.5 Latest |
The 100 most recent W2 Audits for the provided case id will be returned in descending date order, if the case exists.
Example Get Audit History Response
json
{
"audits": [
{
"caseId": "4257206f-18d1-43cd-9388-f7359963c5e0",
"id": "a63a2fda-ade7-4ccc-ab68-0474f3784709",
"actionDate": "2021-05-28T12:57:55.3665984Z",
"action": "Updated",
"propertiesChanged": [
{
"name": "forename",
"old": "dean",
"new": "kev"
},
{
"name": "surname",
"old": "",
"new": "flemming"
},
{
"name": "ClientReference",
"old": "AAA-123/kent",
"new": "AAA-124/kent"
}
]
},
{
"caseId": "4257206f-18d1-43cd-9388-f7359963c5e0",
"id": "0dd2baaf-e64c-40cb-b82d-ac0232a53542",
"user": {
"id": "54616a62-8807-4145-ad6d-2ba36e5fe946",
"name": "bob"
},
"actionDate": "2021-05-28T12:57:55.297519Z",
"action": "Created",
"propertiesChanged": [
{
"name": "forename",
"new": "dean",
},
{
"name": "ClientReference",
"new": "AAA-123/kent",
}
]
}
]
}
Assign Risk Group
A risk Group represents a collection of cases that present a similar level of risk to the organisation, and therefore are monitoring on an ongoing basis to a similar standard. While there are certain risk groups set up by default (Low, High and ex-customer) the client will need to define in the portal the ongoing actions that are taken for the corresponding groups.
This endpoint will assign a case to a risk group.
How to use
To call the endpoint you will need to perform a HTTP PUT request to the URL:
| API Version | Url |
|---|---|
| 1.5 | https://api.w2globaldata.com/Cases/{caseId}/riskgroup?api-version=1.5 Latest |
Example Request
json
{
"RiskGroupId": "id of a risk group"
}
Unassigning Risk Group
The section below describes how to call the Unassign Risk Group endpoint.
This endpoint will unassign a case from a risk group.
How to use
To call the endpoint you will need to perform a HTTP DELETE request to the URL:
| API Version | Url |
|---|---|
| 1.5 | https://api.w2globaldata.com/Cases/{caseId}/riskgroup?api-version=1.5 Latest |
Trigger Bundle
This section describes how the Bundle/Workflow trigger API endpoint functions
How to use
To call the endpoint you will need to perform a HTTP POST request to the URL:
| API Version | Url |
|---|---|
| 1.4 | https://api.w2globaldata.com/case-kyc-check?api-version=1.4 |
| 1.5 | https://api.w2globaldata.com/case-kyc-check?api-version=1.5 Latest |
Example Request
Here is a full Bundle/Workflow trigger request and Response (SIS Plus service call) detailing every data option.
json
{
"caseId":"15b49d9c-ce55-4adb-a241-6e4020207219",
"bundle":"SPFPlusCheck",
"Options": {
"Sandbox": "False",
"Key": "Value",
"NameQueryMatchThreshold": "Accepted values: 80, 85, 90, 100",
"DateOfBirthMatchThreshold": "Accepted values: -100 to 100"
}
}
Request Breakdown
Use this table to find the meaning of each of the fields in the request.
| 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. |
| CaseId | The identifier of the case to be used for the bundle call. This field is mandatory. |
| 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. NameQueryMatchThreshold and DateOfBirthMatchThreshold options are explained further here: FAQs. These thresholds will only work with these services: SIS Plus, SPF Plus, PEPDesk, Watchlist Check, PEP and Sanction 006, W2-DATA-DISQUALIFIEDS-UK-008, W2 Data Ekyc SCANDI 025 |
Example Response
json
{
"clientReference": "CaseReference",
"results": {
"spfPlusCheckResult": {
"matchResults": [
{
"matchType": "Person",
"name": "Theresa Jones",
"nameMatchScore": 90,
"profileId": "SANC-d69d6314-4ab0-90db-efa3-735eb3f2a283"
},
{
"matchType": "Unknown",
"name": "Theresa Harrison",
"nameMatchScore": 80,
"profileId": "SANC-4edac9cc-3ee8-f7dc-4ec3-2fa7df3401bd"
}
]
}
},
"transaction": {
"interpretResult": "NotApplicable",
"serviceCallReference": "b3a13e17-1fbf-424a-81f9-1c1c38d43a1a",
"serviceTransactions": [
{
"haltTriggered": false,
"service": "SPFPlusCheck",
"serviceInterpretResult": "MultipleResults",
"serviceTransactionResult": "Success",
"validationResult": "Pass"
}
]
}
}
Response Breakdown
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. |
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 |