World-Check One API

UPDATED: Thursday, September 29, 2022 - 15:27

Quick Start

The purpose of this Quick Start is to setup and connect to World-Check One via the (WC1) REST/JSON API, understand the environment, variables and how to use them to make WC1 API requests. The goal is to start with just login information and build from Identifer information returned from the previous request(s),up to a name-screening request.

For a detailed Technical Overview of the World-Check One API, download the latest World-Check One API Documentation here and extract it locally on your computer.

The Quick Start provides the necessary documentation, methods and instructions that help developers to integrate the World-Check One API into an internal platform or CRM system.

Therefore, this example is very useful to all programmers and is not limited to any specific programming language.

Groups

Please note that it is recommended to review the group structure before implementing the World-Check One API. Cases are created using a group to which they belong to. The group membership defines several parameters such as screening settings and logic. If a user accesses World-Check One via the web browser, they require membership for the group(s) the cases belong to view the case(s).

Case assignment is possible between and to users. However, the group membership is retained. There is currently no possibility to change the group membership of the case.

Sync vs Async Screening

The sync screening capabilities enable the client to create and screen a case as well as get the screening results in the response payload, thus limiting the number of API requests to be performed. This endpoint can perform synchronous screening for a set of valid case details, The returned result collection contains the regular case result details plus identity documents and important events.

Integration / Testing Account

As a paying subscriber, you will be given a World-Check One Pilot account. It consists of the World-Check One application (accessible by the Client Admin from website https://worldcheck.refinitiv.com) and the World-Check One API. (https://api-worldcheck.refinitiv.com/vx/)

If you do not have the above details please contact the World-Check Admin Services: grc.wc.admin@refinitiv.com.

Prerequisites

World-Check One API requires an Internet connection to send requests to the World-Check One server.

The following are the prerequisites that are necessary to validate the request:

API Key	api-key, World-Check One API password in the form: <8 chars>-<4 chars>-<4 chars>-<4 chars>-<12 chars> Example: d6b5e5f0-b9c9-4ae4-8530-819c61b1ca6c
API Secret Key	api-secret, World-Check One API password in the form: <88 chars>
Group ID	The group-id is used to manage case assignment. This is an alphanumeric string.
Group Name	Name assigned to the group ID.
Case ID	The case-id is an external unique identifier that can be supplied by the user or assigned by the WC1 system. The system supplied case-id an alphanumeric string.
Case System ID	The case-system-id is an internal unique identifier (mapped to a case-id) used in most all the API requests that refer to a case. This is an alphanumeric string.

If you do not have the above details please contact our sales team https://www.refinitiv.com/en/contact-us.

To test the World-Check One API you also need a REST client. In the following we use one particular REST client, Postman, it is Free and available from Google. This is by no means an endorsement of Postman, it is just an example to get you started. Feel free to use any other REST client you might prefer.

Postman Collection and Environment

See the Downloads tab to download the latest collection.

Case Management and Audit – Vx.xx.postman_collection.json
WC1 Pilot environment.postman_environment.json

Now import the collection and environment json files.

Select Import on the main menu, use Import File to upload the json files.

Essential requirements to run the Postman collection:

Ensure that you have the following accesses:

API access
Watchlist enabled (If applicable)
Case delete enabled
3 custom fields
1 risk and reason associated with each Resolution state in the resolution toolkit configuration.

The remaining values in the environment file will be added automatically during the first collection run by extracting values from the API responses.

PLEASE NOTE: Use the instructions from the Postman “view in web” to get a brief description of the API calls. (See the below screenshot), note that you need to be signed into Postman to benefit from this functionality.

To run the collection

Click the Runner button (Check this link to know about Postman Runner).
Select the collection and environment.
Enter a delay value (2000ms should be sufficient for most environments).
Tick the "Persist Variables" box (this will set the environment values for use in future manual runs of individual endpoints).
Click Run.

Here is how the Postman Environment variables are used to build a WC1 request for the Web Service "groups".

{{protocol}}{{gateway-host}}{{gateway-url}}groups concatenated and expanded to https://api-worldcheck.refinitiv.com/vx/groups

Security Authorization Header

Security Authorization string is required every time you send a request to the World-Check One API server.

Bracketed strings are Postman Environment variables. Format: environment["variable-name"]

The Authorization Header is dependent on the type of request:

For GET request - Authorization:

Signature keyId="<8>-<4>-<4>-<4>-<12>",algorithm="hmac-sha256",headers="(request-target) host date",signature=”**”

For POST request - Authorization:

Signature keyId="<8>-<4>-<4>-<4>-<12>",algorithm="hmac-sha256",headers="(request-target) host date content-type content-length",signature=”**”

    	
            function generateAuthHeader(dataToSign){
    var hash = CryptoJS.HmacSHA256(dataToSign,environment["api-secret"]);
    return hash.toString(CryptoJS.enc.Base64); 
}
var date = new Date().toGMTString();
var dataToSign = "(request-target): get " + environment["gateway-url"] + "groups\n" +
        "host: " + environment["gateway-host"] + "\n" +
        "date: " + date;
var hmac = generateAuthHeader(dataToSign);
var authorisation = "Signature keyId=\"" + environment["api-key"] + "\",algorithm=\"hmac-sha256\",headers=\"(request-target) host date\",signature=\"" + hmac + "\"";
postman.setEnvironmentVariable("authorisation",authorisation);
postman.setEnvironmentVariable("currentDate",date);

ScreenRequest

Screen a Name - Sequence of WC1 API Requests

Now you can use the REST client to test the basic functionality of an initial name screening.

Request your Groups

Step 1) SEQ-1a - groups Web Service - "Get my top-level groups"

In the upper right corner, select WC1 pilot environment.
Open the Refinitiv World-Check One API collection in Postman.
Select SEQ-pre-groups: Get my top-level groups.
Click Send and view the Return Request below.

groups Return Request

Create a Simple Case (async)

Step 2) SEQ-case-create-simple: Save a very simple case

Edit the WC1 Pilot environment.
Edit the group-id and replace it with your group id from the last request (Note: group-id will remain same for the specific API Key/Secret).
Select SEQ-case-create-simple: Save a very simple case.
Select the Body and review the fields to create the new case.
Click Send and view the Return Request.
The Return Request shows the case-id and case-system-id.
Edit the WC1 Pilot environment and replace the case-id and case-system-id with the Return Request id's.

cases Return Request

Screen a Case

Step 3) SEQ-screen-async: “Screen a case”

Review the WC1 Pilot environment for your group-id, case-id, and case-system-id values returned from the previous requests.
Select SEQ-screen-async: Screen a case.
Click Send and view the screeningRequest Return Request below.

View the Results

Step 4) Log on to the World-Check One application

NOTE: The Client Admin will have received registration details for the User Interface. This is normally the Compliance Lead or main business contact at your company. Please contact them to gain access or contact grc.wc.admin@refinitiv.com if you do not know who this is.
After logging into World-Check One, you will be able to find the case (name) that you have submitted for screening.

Explore More Requests

Step 5) Now review the other Sequences in the Postman Collection

From here you can update a case, get screening results, set OGS (On-Going Screening), and retrieve an audit log, etc.
Notice that the case-system-id is the most used Identifier and needs to be changed to the case you want to run the Request for.

Create a Client Watchlist (New Provider Source)

Step 6) SEQ-watchlist-update-provider-source: Create or update provider sources

Review the WC1 Pilot environment for your provider-source-identifier, client_watchlist_name (Note: provider-source-identifier value should be alphanumeric, else you would get Status: 400 Bad request).
Input an abbreviation to identify the Client Watchlist.
Click Send and view a Status: 204 No Content confirm the Watchlist has been created / maintained.

Maintain Watchlist Data

Step 7) SEQ-watchlist-maintain-individual: Maintain Watchlist data: Individual

Review the "WC1 Pilot environment" for your entity-id, external-import-id, provider-source-identifier.
Input the abbreviation to identify the Client Watchlist.
Populate the entity details.
Click Send and view a Status: 204 No Content confirm the Watchlist has been created / maintained.