World-Check One API
- World-Check One Overview
- World-Check One API Overview
- Key terminology
- Make your first request to WC1 API
- Create your first case and review results via WC1 API
- Getting Started with Postman
- Sample code
- Troubleshooting and support
- Stay informed
World-Check One Overview
World-Check One (hereafter referred as WC1) is a screening platform that enables you to harness the power of World-check Risk Intelligence data through its next generation screening capabilities which are delivered via a UI portal and an API that can be accessed over the internet, provided you have been entitled with the appropriate product access.
While WC1 UI and WC1 API are considered as two different products, they share same screening capabilities of the WC1 platform. Pure WC1 UI clients are not given access to the API, but WC1 API clients are given a complimentary access to the UI especially for the client administration purposes. Although a pure WC1 UI client can always request their account team for an upgrade to WC1 API based on their needs.
Assuming you are a client administrator and already have necessary access, you can login to WC1 UI to manage your admin settings. You may refer this administration quick start guide to setup your account and group configurations, create new groups, manage your users, check admin audit. You may also refer our detailed administration user guide for more details.
World-Check One API Overview
This WC1 API developer portal provides you with all the necessary information that you need to test and integrate WC1 API into your internal systems and existing workflows. WC1 API is delivered as a REST/JSON webservice in Swagger 2.0 format, accessible exclusively over HTTPS.
While WC1 API v2 is the primary WC1 API, the platform currently supports previous version (v1) as well. We recommend that all users start with v2 as this is where all the enhancements are usually released. Although it is worth noting that we are currently working on a new version (v3) that is due for release in early 2024. In this developer portal, we will consider only WC1 API v2 for all the examples.
Key terminology
Groups
The concept of “Groups” was designed originally for clients to be able to group multiple related cases under one umbrella. Among other considerations, group configurations may vary for the following reasons:
a) As per screening needs - You can create a group with stricter settings for high-risk clients, and another group for low-risk clients.
b) Organizational hierarchy- Different business units within the same organization can have separate groups and group settings in line with your organization’s risk appetite.
Case
A “case” is created upon submitting a screening request to screen customer details such as name and secondary identifiers against selected provider types such as World-Check Risk Intelligence data, Media-check (negative news), Client watchlist (internal lists), and Passport check. All the matched results and audit along with submitted screening data are tagged to a case. Users can perform various actions on the case such as resolve a match, assign a case to another user, archive a case, delete a case, generate case report, etc.
Each case has a unique “caseId” which identifies one case from another across a client’s WC1 account. The user can populate this field with a unique identifier; if not, the system will by default assign a “caseId” when creating the case. The user can use this “caseId” to search for the case details on WC1 UI and perform necessary actions on the case.
Each case also has a unique “caseSystemId” which is by default assigned by the system to identify one case from another across a client’s WC1 account. The user can use this “caseSystemId” to search for the case details or perform an action via WC1 API.
Note: With regards to the “case”, most of the actions on WC1 API require “caseSystemId” and any action on WC1 UI require “caseId”.
Make your first request to WC1 API
Assuming you have received your API keys and setup your environment, you can follow below steps to make your first request to WC1 API.
Step 1: Select an endpoint
The WC1 API has a collection of various endpoints to perform different operations that you might usually be able to perform on the WC1 UI. You can find the complete list of endpoints that are available via WC1 API within our API Schema Reference, but we commend using below endpoint for the purpose of making your first request to WC1 API.
Get all the top-level groups with their immediate descendants
Endpoint: “GET /groups”
Endpoint name in Postman collection: “SEQ-pre-groups: Get my top-level groups”
Step 2: Choose a tool to make your request
While there may be several different tools, code examples, and libraries that you can use to make a request to WC1 API, we are going to use the Postman tool here to simplify the process. Postman is a visual tool that you can use to make requests to REST endpoints. We recommend you read through our Getting Started with Postman guide below to import WC1 API Postman collection and setup your Postman environment. This is necessary to make your first request to WC1 API.
If you are using your own tool or code for sending requests to WC1 API, then refer to sample code section for more details.
Make sure below key environment variables are properly set along with “api-key” and “api-secret” in whichever tool you use.
content-type: application/json
protocol: https://
gateway-host: api-worldcheck.refinitiv.com
gateway-url: /v2/
Note: You may receive error 415 – unsupported media type – if you do not use correct content-type.
Step 3: Send your request and review your response
Select “GET /groups” endpoint within the imported Postman collection and click on “Send”. If everything is setup properly, you should receive a response similar to below with a successful response code “200”.
Note: You may get an error “401” as the response code if you use invalid keys or incorrect authorization within your tool or code, refer sample code section for correct implementation.
Create your first case and review results via WC1 API
Assuming you have successfully made your first request to WC1 API, you can follow below steps to create your first case using Postman by submitting a screening request and review the matched results via WC1 API.
NOTE: Below steps are just to get you started and do not cover every step required for screening. Refer our tutorials on screening and other workflows for further details.
Step 1: Choose a screening endpoint
While you can create and screen a case either synchronously or asynchronously via WC1 API based on your use case, we usually recommend using synchronous screening for faster remediation since you will get the matched results within the response of screening request endpoint. If you choose to use asynchronous screening request, it may take a while before you can retrieve the matched results since all asynchronous screening requests are added to a queue.
For the purpose of this guide, you can use below endpoint for creating a case by submitting a synchronous screening request.
Endpoint: “POST /cases/screeningRequest”
Endpoint names in Postman collection (each one have their own sample requests for “cases/screeningRequest” endpoint):
1. SEQ-screen-sync-simple: Perform Synchronous Screening: Simple
2. SEQ-screen-sync-simple-MC: Perform Synchronous Screening: Media Check
3. SEQ-screen-sync-individual: Perform Synchronous Screening: Individual
4. SEQ-screen-sync-passport: Perform Synchronous Screening: Individual with Passport
5. SEQ-screen-sync-organisation: Perform Synchronous Screening – Organisation
6. SEQ-screen-sync-vessel: Perform Synchronous Screening – Vessel
Step 2: Choose your screening data
The request body of the screening request (or create a case) must have the data to be screened such as name, secondary identifiers, etc. along with other key information such as groupId, entityType, etc. While there are sample requests within the Postman collection for all screening endpoints, you can refer to the full case template by making a request to below endpoint.
Endpoint: “GET /reference/caseTemplate”
Endpoint name in Postman collection: “SEQ-pre-group-case-template: Get the case template for a group”
The response of this endpoint will give you all the applicable secondary identifiers and custom fields that you can use within your screening request for the necessary group. Refer How to interpret Case Template tutorial for more information.
Step 3: Create and screen a case
Assuming you are using Postman, you can search for “SEQ-screen-sync-simple: Perform Synchronous Screening: Simple” within the Postman collection to send a simple synchronous screening request to WC1 API. You may refer to other sample screening requests as well that are available within the collection. Refer How to perform synchronous screening request tutorial for more information.
Once you send the synchronous screening request, you should see a response similar to below with all the matched results within the response under “results” object and a successful response code of “200”.
Note: You can refer our matching engine quick reference guide and user guide if you have any questions about how matching works.
World-Check One Portal (UI) equivalent of screening request and results:
Step 4: Retrieve matched record details
You can use the “referenceId” (unique for every record – this would be World-Check ID in case of a world-check record) from one of the matched results to get the full record details by using below endpoints. Refer How to interpret World-Check record data tutorial for more information.
Note: If you are using Postman, you must set “referenceId” as a value for the environment varable “worldcheck-record-id-encoded” within your WC1 API Postman environment.
Endpoint: “GET /reference/records/{id}
Endpoint name in Postman collection: “SEQ-world-check-record: Retrieve a World-Check record”
Retrieve PEP details by the given record ID (only for PEP Role Details)
Endpoint: “POST /reference/records/{id}/pep”
Endpoint name in Postman collection: “SEQ-pep-role-details: Retrieve the PEP details of a World-Check record”
World-Check One Portal (UI) equivalent of World-Check record view:
Getting Started with Postman
There may be several different tools, code examples, and libraries that you can use to make a request to WC1 API, but we are going to use the Postman tool here to simplify the process. Postman is a desktop and web application that allows you to make HTTP requests to a REST API from a graphical user interface. We recommend using Postman with the WC1 API endpoints when exploring the APIs functionality, as well as when you are troubleshooting issues with your application.
Note: This is by no means an endorsement of Postman, it is just an example to get you started. Feel free to use any other tool or REST client that you may prefer.
Prerequisites:
Before you get started with Postman, you will need to make sure you have proper access and credentials along with appropriate product entitlements enabled in the WC1 UI Admin portal for each group. Once you have access, you will be able to find or generate the following keys to access WC1 API.
API Key |
This is essentially an API equivalent of username which will be in the below format. <8 chars>-<4 chars>-<4 chars>-<4 chars>-<12 chars> Example: d6b5xxxx-b9xx-4axx-85xx-819c61xxxxxx |
API Secret |
This is essentially an API equivalent of password which will be in below format. <88 chars> |
You will usually be given one Pilot account and Production account, unless you are a “Partner Client” (client who uses one of the WC1 API partners to integrate with WC1 API) – in which case you will be given only Production account. The API keys will be different for both the accounts. You may use your Pilot account for your development and testing purposes.
If you do not have access or API keys, contact your LSEG account team.
Step 1: Import WC1 API Postman collection and environment into your Postman application
While you could build out the specific endpoints that you’d like to use within Postman, we did all the heavy lifting for you and built out a ready to use Postman collection and Postman environment of WC1 API. Just download and import both collection and environment (.json) files into your Postman app and all the endpoints associated with WC1 API will be added to your Postman app. Each endpoint will automatically include sample requests and responses, so you just need to add your credentials to the environment you just imported to start exploring the functionality.
Step 2: Add your API keys to your Postman environment
Once you have imported your Postman environment, you can add your API keys by following below steps.
Click on “Environments” and select the WC1 API environment that you just imported.
Add your API Key and API Secret to the respective variables under “CURRENT VALUE” and click on “Save”.
Sample code
If you are using your own tool or code for sending requests, then note WC1 API uses HMAC for authorization purposes. You can refer our documentation and download sample code in various languages to learn more about how to implement authorization in your request headers to make a successful call to WC1 API.
Below is a quick snippet of the sample authorization code.
If the request does not have any body:
function generateAuthHeader(dataToSign){
var hash = CryptoJS.HmacSHA256(dataToSign,environment["api-secret"]);
return hash.toString(CryptoJS.enc.Base64);
}
var date = new Date().toGMTString();
var requestMethod = request.method.toLowerCase();
var requestUrlPart = replaceRequestValuesWithEnvValues(request.url.split('?')[0].replace('{{protocol}}{{gateway-host}}{{gateway-url}}', ''));
var dataToSign = "(request-target): ${requestMethod} " + environment["gateway-url"] + requestUrlPart + “\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);
If the request has a body:
function generateAuthHeader(dataToSign){
var hash = CryptoJS.HmacSHA256(dataToSign,environment["api-secret"]);
return hash.toString(CryptoJS.enc.Base64);
}
var date = new Date().toGMTString();
var requestMethod = request.method.toLowerCase();
var requestUrlPart = replaceRequestValuesWithEnvValues(request.url.split('?')[0].replace('{{protocol}}{{gateway-host}}{{gateway-url}}', ''));
var dataToSign = "(request-target): ${requestMethod} " + environment["gateway-url"] + requestUrlPart + "\n" +
"host: " + environment["gateway-host"] + "\n" +
"date: " + date + "\n" +
"content_type: " + environment["content-type"] + "\n" +
"content_length: " + environment["content-length"];
var hmac = generateAuthHeader(dataToSign);
var authorisation = "Signature keyId=\"" + environment["api-key"] + "\",algorithm=\"hmac-sha256\",headers=\"(request-target) host date content_type content_length\",signature=\"" + hmac + "\"";
postman.setEnvironmentVariable("authorisation",authorisation);
postman.setEnvironmentVariable("currentDate",date);
Note: You may refer to “README.md” file included within the sample code for invoking request to WC1 API for each HTTP method in various programming languages.
Troubleshooting and support
Useful links:
- Documentation
- Tutorials
- API Schema Reference
- UML Diagrams and Workflows
- Authentication and authorization
- Sample Code
- Downloads
- Changelog
- Release Notes
- FAQs
- World-Check One User Guides
More useful links:
Debugging an error? Head over to our developer community to search for questions raised by other developers and find useful troubleshooting tips.
Have a question? Post it in our Q&A forum by selecting Forum as “World-Check One”, Tags as “world-check-one-api” and one of our API consultants will attend to it.
Need more help? Raise your concern via MyRefinitiv Support tool and one of our specialists will reach out asap.
Want to share an idea or general feedback? Keep them coming our way via MyRefinitiv Feedback tool and we will prioritize our roadmaps accordingly.
Stay informed
WC1 API is updated frequently with new functionality and system changes to better suit your needs. All the changes are usually documented and available in the documentation under Changelog section.
Ensure you’re aware of upcoming system changes and/or new functionality that may affect your workflows or require action on your part by subscribing to Product Change Notifications (PCNs).
You can also view and subscribe to PCNs, Data Notifications, and Service Alerts on the Notifications & Alerts page in MyRefinitiv.