Cases Endpoints

Use these endpoints to manage your Cases. We recommend you read this page first to learn what Cases are before looking at these endpoints.

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:

Url	API Version
https://api.w2globaldata.com/Cases	1.2+

Request

This endpoint takes a JSON body. See the Cases page to see the full list of the case properties available.

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",
    "Nationalities": [
        "GBR"
    ],
    "Tags": [
        "Person"
    ]
}

Example Response

The W2 CaseId will be provided if successfully created.

json

{
    "caseId": "cd35f8a0-f30c-4cfc-9bcb-12bf58d44876"
}

Create Business Case

The section below describes how to create business cases.

How to use

To call the endpoint you will need to perform a HTTP POST request to the URL:

Url	API Version
https://api.w2globaldata.com/cases/business	2.1+

Request

This endpoint takes a JSON body. The following are the accepted fields:

Property Name	Type	Optional/Mandatory	Notes
ClientReference	String	Mandatory	Use this property to link cases back to entities in your own systems.
RegistrationNumber	String	Optional*	The registration number of the business. Such as a Companies House company number.
LookupId	String	Optional*	This id can be found using our business search API endpoint and is used for businesses outside of the UK.
CountryCode	String	Mandatory	The Country of the business. We require this to be a standard 3 letter ISO code to ensure compatibility with all our services.

Notes

*This endpoint uses the Registration Number or the LookupId to auto populate fields during the business case creation, therefore for the creation of UK business cases the RegistrationNumber field is required, for businesses outside of the UK, the LookupId or the RegistrationNumber field is required.

Example Request

json

{
    "ClientReference" : "your-client-reference",
    "LookupId" : "DE-1-DEXXXXXX",
    "CountryCode" : "DEU",
    "RegistrationNumber" : "E0XXXXXXXX-5"
}

Example Create Business Case Response

Updating a case returns a Case Id for the updated case.

json

{
    "name": "adidas Originals Store",
    "country": "DEU",
    "id": "xxxxxx-fe89-46eb-871c-8234e43c54b4",
    "type": "Business",
    "clientReference": "your-client-reference",
    "ongoingMonitoring": false,
    "creationDate": "2024-02-28T11:35:05.9217713Z",
    "lastUpdatedDate": "2024-02-28T11:35:05.9217713Z",
    "externalIds": [
        {
            "name": "KYBLookupId",
            "value": "DE-1-DEXXXXXX"
        }
    ]
}

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 to include in the case.

How to use

To call the endpoint you will need to perform a HTTP PUT request to the URL:

Url	API Version
https://api.w2globaldata.com/cases/	1.3+

Request

WARNING

Please note that this is a PUT endpoint. Updates to a case via this endpoint by replace its attributes entirely. Any missing or empty properties from your request will wipe the corresponding case property.

Creation or Deletion of Tags is not available through this endpoint, see Create Tag or Delete Tag for more information on creating and deleting tags on a case.

This endpoint takes a JSON body. See the Cases page to see the full list of the case properties available.

Example Update Case Request

json

{
          "Forename": "TEST_FORENAME_NEW",
          "Surname": "TEST_SURNAME_NEW",
          "DayOfBirth": 2,
          "MonthOfBirth": 2,
          "YearOfBirth": 2002,
          "ClientReference": "REST_TEST_NEW",
          "Id": "cd35f8a0-f30c-4cfc-9bcb-12bf58d44876",
          "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",
          "Nationalities": [
              "GBR"
          ]
}

Example Update Case Response

Updating a case returns a Case Id for the updated case.

json

{
    "caseId": "cd35f8a0-f30c-4cfc-9bcb-12bf58d44876"
}

Get

Retrieves a Case by its Id.

How to use

To call the endpoint you will need to perform a HTTP GET request with the CaseId in the URL:

Url	API Version
https://api.w2globaldata.com/Cases/	1.4+

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",
    "Nationalities": [
        "GBR"
    ],
    "Tags": [
        "Person"
    ]
}

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:

Url	API Version
https://api.w2globaldata.com/Cases?RiskGroup=low&PageNumber=0&PageSize=1	1.5+

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

Type
Forename
Surname
Client Reference
Day of Birth
Month of Birth
Year of Birth
Postcode
Case Group
Email
Tags

When searching using a case group name, a full name must be given i.e. 'low' or 'high'. Case 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",
            "type":"Person",
            "forename": "John",
            "surname": "Preston",
            "dayOfBirth": 1,
            "monthOfBirth": 3,
            "yearOfBirth": 2010,
            "clientReference": "efg",
            "riskGroup": "low",
            "lastUpdatedDate": "2021-08-06T14:19:28.7628906Z",
            "email": "[email protected]",
            "tags": [
                "test"
            ]
        }
    ],
    "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:

Url	API Version
https://api.w2globaldata.com/Cases/{caseId}/results	1.4+

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:

Url	API Version
https://api.w2globaldata.com/Cases/{caseId}/audits	1.4+

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 Case Group

A Case 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 case 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 case group.

How to use

To call the endpoint you will need to perform a HTTP PUT request to the URL:

Url	API Version	Notes
~~https://api.w2globaldata.com/Cases/{caseId}/riskgroup~~	1.5 - 2.9	Deprecated
https://api.w2globaldata.com/Cases/{caseId}/casegroup	3.0+	Current

Example Request

json

{
	"CaseGroupId": "id of a case group"
}

Unassigning Case Group

The section below describes how to call the Unassign Case Group endpoint.

This endpoint will unassign a case from a case group.

How to use

To call the endpoint you will need to perform a HTTP DELETE request to the URL:

Url	API Version	Notes
~~https://api.w2globaldata.com/Cases/{caseId}/riskgroup~~	1.5 - 2.9	Deprecated
https://api.w2globaldata.com/Cases/{caseId}/casegroup	3.0+	Current

Create Tag

The section below describes how to create a tag for a case. This functionality can be directly used on creation of a case. See Case Creation.

How to use

To call the endpoint you will need to perform a HTTP POST request to the URL:

Url	API Version
https://api.w2globaldata.com/Cases/{caseId}/tag/{tagName}/	2.2+

Example Response

This is an example of what is returned from the create tag endpoint, simply put it will return all tags attatched to the case Id.

json

[
    "Business",
    "Manager",
    "Person"
]

Delete Tag

The section below describes how to delete a tag for a case.

How to use

To call the endpoint you will need to perform a HTTP DELETE request to the URL:

Url	API Version
https://api.w2globaldata.com/Cases/{caseId}/tag/{tagName}/	2.2+

Example Response

This is an example of what is returned from the delete tag endpoint, simply put it will return all tags attatched to the case Id.

json

[
    "Business",
    "Manager",
    "Person"
]

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:

Url	API Version	Notes
https://api.w2globaldata.com/case-kyc-check	1.4+
https://api.w2globaldata.com/case-kyc-check	3.1+	Document Bundle Checks

WARNING

Bundle checks with documents is exclusively accessible for the W2 Data IDV Check 013 service.

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

Note: For bundle checks with documents supported in version 3.1 or higher, refer to the Bundle checks with documents section.

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

Bundle Checks with Documents (Version 3.1+)

This section describes how to use bundle checks with documents available in version 3.1 or higher.

To utilize this endpoint, it is required that a document has already been uploaded, and the necessary details have been obtained from the Document Upload endpoint. This feature references the uploaded document but does not associate the document directly with the case.

Example Request

json

{
    "caseId": "69867a8b-5bef-40f2-8fe0-819c1aac936b",
    "Bundle": "W2_DATA_IDVCHECK_013",
    "Files": [
        {
            "DocumentReference": "Test-idv013",
            "DocumentUID": "1969d23a-270b-42aa-9272-42028de27a75",
            "Service": "W2_DATA_IDVCHECK_013"
        }
    ]
}

Note: Refer to Document Upload for what document types and sizes can be used.

Request Breakdown

Property	Description
Files	Array of objects containing document details for upload.
DocumentReference	Unique reference for the uploaded document.
DocumentUID	UID for the uploaded document.

Example Response

json

{
    "clientReference": "test-idv013",
    "results": {
        "w2DataIdvcheck013Result": {
            "errorCode": "0000",
            "errorDesc": "Successful",
            "callId": "WSCR6D70C630D2F140C6B73A7EABC3C020A4"
        }
    },
    "transaction": {
        "interpretResult": "Pass",
        "serviceCallReference": "6d70c630-d2f1-40c6-b73a-7eabc3c020a4",
        "serviceTransactions": [
            {
                "haltTriggered": false,
                "service": "W2_DATA_IDVCHECK_013",
                "serviceInterpretResult": "NotApplicable",
                "serviceTransactionResult": "Success",
                "serviceTransactionResultMessage": "Application Submitted Successfully.",
                "validationResult": "Pass"
            }
        ]
    },
    "caseId": "69867a8b-5bef-40f2-8fe0-819c1aac936b"
}

Response Breakdown

Property	Description
ErrorCode	Indicates the success or failure of the operation.
ErrorDesc	Describes the result of the operation.
CallId	Unique identifier for the service call related to document upload.

Cases Endpoints ​

Create ​

How to use ​

Request ​

Example Request ​

Example Response ​

Create Business Case ​

How to use ​

Request ​

Notes ​

Example Request ​

Example Create Business Case Response ​

Update ​

Situations where you may need to update a case include: ​

How to use ​

Request ​

Example Update Case Request ​

Example Update Case Response ​

Get ​

How to use ​

Example Response ​

Search ​

How to use ​

Pagination Options ​

Searchable fields ​

Example Search Response ​

Get Results ​

How to use ​

Example Get Results Response ​

Get Audit History ​

How to use ​

Example Get Audit History Response ​

Assign Case Group ​

How to use ​

Example Request ​

Unassigning Case Group ​

How to use ​

Create Tag ​

How to use ​

Example Response ​

Delete Tag ​

How to use ​

Example Response ​

Trigger Bundle ​

How to use ​

Example Request ​

Request Breakdown ​

Example Response ​

Response Breakdown ​

Client Provided Data ​

Transaction Information ​

Service Transaction Information ​

Bundle Checks with Documents (Version 3.1+) ​

Example Request ​

Request Breakdown ​

Example Response ​

Response Breakdown ​

Cases Endpoints

Create

How to use

Request

Example Request

Example Response

Create Business Case

How to use

Request

Notes

Example Request

Example Create Business Case Response

Update

Situations where you may need to update a case include:

How to use

Request

Example Update Case Request

Example Update Case Response

Get

How to use

Example Response

Search

How to use

Pagination Options

Searchable fields

Example Search Response

Get Results

How to use

Example Get Results Response

Get Audit History

How to use

Example Get Audit History Response

Assign Case Group

How to use

Example Request

Unassigning Case Group

How to use

Create Tag

How to use

Example Response

Delete Tag

How to use

Example Response

Trigger Bundle

How to use

Example Request

Request Breakdown

Example Response

Response Breakdown

Client Provided Data

Transaction Information

Service Transaction Information

Bundle Checks with Documents (Version 3.1+)

Example Request

Request Breakdown

Example Response

Response Breakdown