World-Check Verify
Key terminology
Groups
The Groups feature allows clients to organise and manage screening configurations based on business needs or organisational structure. A group enables tailored screening settings that can be applied dynamically during screening requests.
Risk-Based Segmentation: Apply stricter screening rules for high-risk segments and lighter configurations for low-risk segments.
Organisational Alignment: Assign different business units or regions their own group with custom screening policies.
Policy Control: Each group can have its own screening configuration, including match thresholds, data sources, and auto-resolution settings.
Screen
Screening is the process of matching a name against official or proprietary watchlists to identify potential risks. World-Check Verify allows you to perform real-time screening of individuals, organisations, or vessels against selected risk data sources such as Sanctions, Law & Regulatory enforcement lists, PEPs, adverse media, and client watchlists. The API accepts a name and optional secondary identifiers (e.g., date of birth, nationality, identity document number, etc.) and returns potential matches based on the selected screening configuration.
Getting Started with Postman
There may be several different tools, code examples, and libraries that you can use to make a request to World-Check Verify. We are going to use the Postman tool in this developer portal for all the examples. 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 to explore the API’s functionality, and when you are troubleshooting issues.
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.
Prerequisite: Before you get started with Postman, you will need to make sure you have appropriate product access and credentials.
If you have the necessary access, you will be able to find the following API keys which are required to access World-Check Verify.
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 one Production account, unless you are using one of our World-Check Verify partner solutions – in which case you will be given direct access to Production account considering our partner already has a valid integration with our API.
Note: The API keys will be different for both the accounts. You may use your Pilot account for your development and basic testing purposes before you go-live with your production account.
If you do not have necessary access or credentials, contact your LSEG Account team.
Step 1: Import World-Check Verify Postman collection and Postman environment files 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 with sample requests and Postman environment for all the necessary variables. Download and import both collection and environment (.json) files into your Postman app to add all the World-Check Verify endpoints.
Step 2: Add your API keys to your Postman environment
Once you have imported your Postman environment, you can add your credentials to the environment file to start exploring the API functionality.
Click on “Environments” and select the World-Check Verify environment that you just imported. Add your API Key and API Secret to the respective variables under “Current value” and click on “Save”.
Make your first API request
Now that you have setup your Postman with valid credentials, you can follow below steps to make your first API request to World-Check Verify.
Step 1: Select an endpoint
You can find the complete list of endpoints that are available in World-Check Verify within our API Schema Reference, but we recommend using below endpoint for the purpose of making your first API request to World-Check Verify.
Endpoint: “GET /groups”
Endpoint name in Postman collection: “Get groups”
Step 2: Choose a tool to make your request
As mentioned above, there may be several different tools, code examples, and libraries that you can use to make an API request to World-Check Verify, but we are going to use the Postman tool in this developer portal for all the examples. We recommend checking out Getting Started with Postman section if you haven’t setup your Postman yet. This is necessary to make your first API request to World-Check Verify using this quick start guide.
If you are using your own tool or code for sending requests to World-Check Verify, then refer to sample code section for useful 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.ap.risk.lseg.com
gateway-url: /zfs/v1/
Note: You may receive error 401 (unauthorized access) if you do not use correct URL or credentials, and 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”.
Screen a name and review the screening results
Assuming you have successfully made your first API request, you can follow below steps to screen a name using World-Check Verify through your Postman by submitting a screening request and review the screening results within the response.
Note: Below steps are just to get you started and do not cover every step required for screening. Refer our tutorials for further details.
Step 1: Screen a name
In a screening request, atleast one primary name is mandatory for screening purposes. You can send one or more secondary identifiers such as gender, date of birth, etc. (see "secondary.Fields"->"type" and "secondary.Fields"->"details"->"type" dropdown for supported secondary identifiers and expected values) as part of the screening request body to reduce false positives along with other key information such as groupId, entityType, etc. There are examples within the Postman collection for all the entity types for your reference.
Endpoint: “POST /screen”
Endpoint name in Postman Collection: "Screen"
Once you send the screening request, you should get a response code “200” and must be able to see all the matched screening results within the response under “results” object.
Note: You can refer our matching engine quick reference guide and user guide if you have any questions about how the name matching works.
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 screening results to get the full record details in the below endpoint. 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 variable “watchlist-record-id” within your World-Check Verify Postman environment.
Endpoint: “GET /references/records/{id}
Endpoint name in Postman collection: "Get watchlist record”
Sample code
If you are using your own tool or code for sending requests, then note World-Check Verify 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 World-Check Verify.
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 an API request to World-Check Verify for each HTTP method in various programming languages.