Getting Started
Developer Portal
The LSEG Developer Community portal provides information on all LSEG APIs, including documentation, sample code, and tutorials. The World-Check On Demand section of the portal aims to host all relevant information a developer, partner, or integrator requires to learn about the product. The portal also provides a Question & Answer forum for developers to interact, find answers, and post questions related to LSEG APIs. Users can set alerts, allowing the receipt of timely notifications for new Downloads, News & Events items, Notifications, or Alerts to specific APIs.
The Enhancements or Release Notes can also be found in the portal.
Developers may freely register for access to the Developer Community portal.
Quick Start
The fastest way to start exploring the APIs is to use our Postman Collection:
- Download and install Postman.
- Download and import the latest World-Check On Demand Postman Collection and Environment files. There are three files:
- collection file: contains the sample API calls and related scripts; can be used on both Production or Sandbox environments
- environment file (Production): contains the preset environmental values for sending requests to the Production environment
- environment file (Sandbox): contains the preset environmental values for sending requests to the Sandbox environment
- Once the environment file is imported, enter and save the Client ID and Client Secret that were provided by LSEG or that you have retrieved from the Platform Admin Application (PAA).
- Explore the many provided queries in the collection.
The provided collection is designed to automate the bearer token management so you don't have to manually do the work.
Environments
World-Check On Demand has two client-facing environments:
| Environment | Base URL | Description |
|---|---|---|
| Production | https://api.risk.lseg.com/data/world-check/{version}* | Returns real data |
| Sandbox | https://api.risk.lseg.com/data/world-check/sandbox/{version}* | Returns synthetic data |
*The current supported version is v1. Only major versions are supported in the path.
Getting Credentials
The Client ID and Client Secret will be provided by LSEG for organisations on the Pilot, Early-Access, and Trial arrangements.
For commercial clients and official partners, you will manage your credentials through the Platform Admin App (PAA). More details will be provided soon.
Authentication / Authorisation
World-Check On Demand requires that you exchange your credentials to get a JSON Web Token using OAuth2.0's client_credentials grant type.
| Token URL | Grant Type | Token Duration (default) |
|---|---|---|
https://login.ciam.refinitiv.com/as/token.oauth2 | client_credentials | 7200 seconds |
Once the token is received, it must be sent in the Authorization header with every API request. A short lifetime token can also be requested and is valid for 5 minutes. The token lifetimes are requested via the audience parameter, sent either via the token request payload or query string.
Please refer to the API Reference for the token request details.
First API Calls
The World-Check On Demand Postman files contains many ready-to-send request samples that gives you a view of the different possible filters and filter combinations best suited for your organisation. It will also show you how the record's JSON structure look like, along with being able to retrieve the rich reference information.
After the credentials are added to the environment variables, you can immediately make API calls without having to separately retrieve the bearer token, as the collection is doing this for you programmatically, including token re-use and refresh.
Next Steps
Filtering
Try out the different filters and pre-defined sample variations within the collection. This gives you a view of the possible ways to limit the data being retrieved to what is absolutely necessary for your business.
Here are some of the commonly used filters and their use cases:
- ALL records - typically used when bootstrapping your local database with World-Check data for the first time
- lastPublishedDate - used for retrieving delta (i.e., what's been added and updated) since a given timestamp
- keyword - returns records that are associated with the given list of keywords
- uid - returns records of specific World-Check UIDs
Pagination
Pagination in World-Check On Demand utilises cursors. If there are more records than can fit an API response page (which depends on your limit setting), the cursor value for the next page can be found in the meta object of the response body, as cursors.next. The cursors.previous is also available for retrieving the previous page.
The provided Postman collection automates most of the work to view the next or previous pages. Just send the POST Next Page request after getting a response with a non-zero cursors.next value. A value of zero ("0") on either cursor types means that there are no more records on the page.
Cursors are sent as a querystring parameter using the cursor key.
When paginating, the request body must remain exactly the same as the original request that generated the first page. This is to ensure that the responses on all subsequent pages are based on the same initial query. To enforce this requirement, all subsequent page requests must also send the meta.queryHash value in the request headers as queryHash. The meta.queryHash can only be found on the first page response.
Common Errors
These are the most common errors when starting out:
| Error Code | Error Message | Description |
|---|---|---|
| 400 | Bad Request | Probably the most common type of error. This usually means a syntax error on the request body, or one of the parameter values is incorrect or does not exist. The error message will usually provide a hint on the reason. |
| 401 | Unauthorized | This usually means that the credentials are missing or there is an typo in entering the values. |
| 403 | Forbidden | This can show up if the scopes are incorrect or a missing license assignment on the account. This can also happen if an opaque token was requested instead of a JSON Web Token. |
| 404 | Not Found | This typically means that the requested resource path is incorrect, commonly due to a typo. |
| 504 | Gateway Timeout | This can happen if the request is taking a long time to be processed, either due to query complexity or heavy loads on the backend. |
References API
World-Check On Demand provides all reference information via a set of APIs. References are the universe of controlled values that are used as primary keys in World-Check records, providing additional context and details to the record data. Examples of reference data:
| Reference Code | Name | Description |
|---|---|---|
| wcRecordType:IND | Individual | This code is assigned to records that are pertaining to individuals. |
| wcLocationType:BIRTH_LOCATION | Location of Birth | It provides context to the location information as the place of birth of the record subject. This location could be a country, state, or city, or a combination of these. |
| wcNameRole:LAST_NAME | Last Name | Refers to the last name or family name of the record subject. |
Reference codes have two parts separated by a semicolon: the first page is the scheme and the second part is the concept. In the first example above, the scheme is "wcRecordType" and the concept is "IND". Together, they form the immutable primary key for the individual record type.
References can be retrieved via the following endpoints:
| Reference Type | Resource |
|---|---|
| Schemes | /schemes |
| Concepts | /concepts |
API Rate Limits
World-Check On Demand API will be enforcing rate limits to effectively manage system performance, protect the service, and ensure an equitable distribution of resources among users. When a rate limit is breached, the requesting application will receive either HTTP codes, depending on the scenario:
| Error Code | Description |
|---|---|
| 429 | - Too Many Requests - This error code is provided when the account’s limit for the operation has been breached. |
| 503 | - Service Unavailable - This error code is provided when the global limit for the operation has been breached. |
The current rate limits are:
| Rate Limit | Type | Description |
|---|---|---|
| 1500 requests in 5 minutes | Token Request | Maximum number of token requests within 5 minutes. The IP will be blocked for 5 minutes if this is breached and no response will be provided. |
| 250 requests per second | Application | Maximum number of requests per second for each operation type. |
| 25 request burst | Application | Follows the token bucket algorithm, which limits the total number of in-flight requests per operation. |
These limits are for each operation type (i.e., POST /records, GET /schemes, GET /concepts, etc.) and are both active. Requests will be rejected when any of the policies are breached. Your application must be designed to gracefully handle these responses and should implement an exponential backoff mechanism.
API Versioning
The World-Check On Demand API will be versioned following the semantic versioning approach using a three-part version number separated by a dot:
- Major version – breaking changes
- Minor version – new, non-breaking features
- Patch number – all other non-breaking changes
API Management Process
Under continuous delivery, the World-Check On Demand API aims to be regularly updated with new functionality and enhancements, performance improvements, and bug fixes. New releases will eventually be announced via Product Change Notifications and posts in the Release Notes section.
Non-Breaking Changes
The following items constitutes a non-breaking change, alone or in combination:
- New endpoints
- New optional fields in the request body of existing endpoints
- New required fields in the request body with a default value
- New optional URL parameters of existing endpoints
- New fields in the response of existing endpoints
- New or updated error message descriptions
- New enumeration values in request fields
- Changes to patterns of string-type values in responses
Clients integrating with the API should ensure that the above items are taken into consideration in the application design and that the code will not fail given the above changes, without requiring any additional code change. By default, information about non-breaking changes will be provided in the Release Notes, just before or immediately after the release.
Breaking Changes
Breaking changes may cause integrated applications to break and will always be announced at least 6 months prior to release. Since World-Check On Demand API will support multiple major versions of the API, applications using any of the current major versions will not be affected by the release of a new major version.
- New required fields without a default value
- Making an existing field required without a default value
- Data type change on existing field values
- Change in existing field names
- Change or additional criteria for validating an existing input field
- Removal of an existing enumeration value except when associated with Metadata entries
- Removal of existing fields in the response
- Removal or name changes on existing URL parameters
- Moving existing fields to a different location in the response schema
Version Retirement Process
Retirement of an API version will happen in two phases: Deprecation and Sunset. The responses of all deprecated endpoints will contain the Deprecation IETF HTTP Response Header Field, which may contain the following:
- The deprecation date and time, which may be a future value when the version will be deprecated or in the past.
- Boolean value, indicating whether the version / endpoint had been deprecated.
While deprecated, the endpoint will still be functional.
Sunset marks the point in time when the endpoint will not return the expected response or elicit the expected behaviour. Along with the deprecation header, a new sunset header will be added to indicate the sunset date.
Examples:
Deprecation: Sun, 31 Dec 2028 23:59:59 UTC
Deprecation: true
Deprecation: Sun, 31 Dec 2028 23:59:59 UTC
Sunset: Mon, 31 Dec 2029 23:59:59 UTC