Ongoing Monitoring
Register names via API, get notifications from webhooks.
The Ongoing Monitoring API is a comprehensive solution that enables businesses to proactively monitor their customers against dilisense's sanction, PEP, and criminal watchlist databases. This API provides a convenient and efficient way to register names of individuals and entities and receive real-time notifications if there are changes to the risk profiles (e.g., a name was found, removed or any attributes associated with that name were updated).
This documentation provides an overview of the Ongoing Monitoring API, including how to use it, the available endpoints, and what data formats are accepted.
1. Authentication
All API calls to dilisense require an authentication via API key. Specifically we expect the x-api-key value to be set in the header of your API call. If the API key is not valid, the API call will return a 401 HTTP error code.
We will provide you with a private API key, which you can use for integrating with our API. The private API key is only intended for your own use, as we track the number of API calls with this key. The key has to be securely stored on your side to avoid any misuse by unauthorized parties.
2. registerIndividual (GET)
The registerIndividual endpoint allows clients to register an individual's name to be monitored against dilisense's database, and receive notifications if any matches are found from that point in time onwards.
Endpoint
https://api.dilisense.com/v1/registerIndividual
Request parameters
profile_id
The unique identifier of the search profile that you want to associate with this request.
names
Search string that is checked against sanction, PEP and criminal watchlists. Only name fields (e.g. 'name', 'alias_names' etc.) are considered. Cannot be combined with 'search_all' parameter.
search_all
Search string that is checked against sanction, PEP and criminal watchlists. All fields are considered. Cannot be combined with 'names' parameter.
dob (optional)
This parameter searches for a match in the date of birth. Possible variations are
- dd/mm/yyyy if the exact date is known (e.g. 01/05/1990).
- 00/00/yyyy if only the year is known (e.g. 00/00/1990).
- 00/mm/yyyy if only the month and the year are known (e.g. 00/05/1990).
- dd/00/yyyy if only the day and the year are known (e.g. 01/00/1990).
gender (optional)
This parameter searches for a match in gender. Possible values are
- ‘male’ - For searching for individuals that are “male” or that have the gender value not set.
- ‘female’ - For searching for individuals that are “female” or that have the gender value not set.
fuzzy_search (optional)
This parameter defines if spelling differences need to be considered for the search string.
- 1: Fuzzy search with distance 1 (e.g. Angela will also match for Angelo) for the "names" parameter.
- 2: Fuzzy search with distance 2 (e.g. Angela will also match for Angale) for the "names" parameter.
Example
- curl
- Python
- Java
- Javascript
curl --location --request GET 'https://api.dilisense.com/v1/registerIndividual?profile_id=abcdefg-1234&names=Boris%20Johnson&fuzzy_search=1&dob=19/06/1964&gender=male' \
--header 'x-api-key: <api_key>'
import requests
url = "https://api.dilisense.com/v1/registerIndividual?profile_id=abcdefg-1234&names=Boris Johnson&fuzzy_search=1&dob=19/06/1964&gender=male"
payload={}
headers = {
'x-api-key': '<api_key>'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dilisense.com/v1/registerIndividual?profile_id=abcdefg-1234&names=Boris Johnson&fuzzy_search=1&dob=19/06/1964&gender=male"))
.header("x-api-key", "<api_key>")
.build();
client.sendAsync(request, BodyHandlers.ofString())
.thenApply(HttpResponse::body)
.thenAccept(System.out::println)
.join();
var myHeaders = new Headers();
myHeaders.append("x-api-key", "<api_key>");
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch("https://api.dilisense.com/v1/registerIndividual?profile_id=abcdefg-1234&names=Boris Johnson&fuzzy_search=1&dob=19/06/1964&gender=male", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Response
A successful response has the HTTP code 200 and contains no payload.
Matches at the time of registration will not trigger a webhook. In order to identify existing matches the following endpoint is available: checkIndividual
3. registerEntity (GET)
The registerEntity endpoint allows clients to register an entity's name to be monitored against dilisense's database, and receive notifications if any matches are found from that point in time onwards.
Endpoint
https://api.dilisense.com/v1/registerEntity
Request parameters
profile_id
The unique identifier of the search profile that you want to associate with this request.
names
Search string that is checked against sanction, PEP and criminal watchlists. Only name fields (e.g. 'name', 'alias_names' etc.) are considered. Cannot be combined with 'search_all' parameter.
search_all
Search string that is checked against sanction, PEP and criminal watchlists. All fields are considered. Cannot be combined with 'names' parameter.
fuzzy_search (optional)
This parameter defines if spelling differences need to be considered for the search string.
- 1: Fuzzy search with distance 1 (e.g. Angela will also match for Angelo) for the "names" parameter.
- 2: Fuzzy search with distance 2 (e.g. Angela will also match for Angale) for the "names" parameter.
Example
- curl
- Python
- Java
- Javascript
curl --location --request GET 'https://api.dilisense.com/v1/registerEntity?names=REYCO%20GMBH%20GERMANY' \
--header 'x-api-key: <api_key>'
import requests
url = "https://api.dilisense.com/v1/registerEntity?profile_id=abcdefg-1234&names=REYCO GMBH GERMANY"
payload={}
headers = {
'x-api-key': '<api_key>'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dilisense.com/v1/registerEntity?profile_id=abcdefg-1234&names=REYCO GMBH GERMANY"))
.header("x-api-key", "<api_key>")
.build();
client.sendAsync(request, BodyHandlers.ofString())
.thenApply(HttpResponse::body)
.thenAccept(System.out::println)
.join();
var myHeaders = new Headers();
myHeaders.append("x-api-key", "<api_key>");
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch("https://api.dilisense.com/v1/registerEntity?profile_id=abcdefg-1234&names=REYCO GMBH GERMANY", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Response
A successful response has the HTTP code 200 and contains no payload.
Matches at the time of registration will not trigger a webhook. In order to identify existing matches the following endpoint is available: checkEntity
4. removeSearchProfile (GET)
The removeSearchProfile endpoint allows clients to remove a search profile that was previously registered with the Ongoing Monitoring API, based on the profile_id provided in the request parameters.
Endpoint
https://api.dilisense.com/v1/removeSearchProfile
Request parameters
profile_id
The unique identifier of the profile to be removed.
Example
- curl
- Python
- Java
- Javascript
curl --location --request GET 'https://api.dilisense.com/v1/removeSearchProfile?profile_id=abcdefg-1234' \
--header 'x-api-key: <api_key>'
import requests
url = "https://api.dilisense.com/v1/removeSearchProfile?profile_id=abcdefg-1234"
payload={}
headers = {
'x-api-key': '<api_key>'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dilisense.com/v1/removeSearchProfile?profile_id=abcdefg-1234"))
.header("x-api-key", "<api_key>")
.build();
client.sendAsync(request, BodyHandlers.ofString())
.thenApply(HttpResponse::body)
.thenAccept(System.out::println)
.join();
var myHeaders = new Headers();
myHeaders.append("x-api-key", "<api_key>");
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch("https://api.dilisense.com/v1/removeSearchProfile?profile_id=abcdefg-1234", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Response
A successful response has the HTTP code 200 and contains no payload.
5. Webhook Notification (POST)
The Ongoing Monitoring API provides a webhook-based notification system that enables clients to receive real-time alerts when a change in a search profile is found in any of the screening lists. Webhooks are automated HTTP callbacks that are triggered by a specific event, such as a match on a screening list. To set up webhook-based notifications, clients can register a URL with the Ongoing Monitoring API that will receive the notifications when a change for a search profile is found. The URL should be publicly accessible and capable of handling HTTP POST requests.
We will ask you for the webhook URL during the onboarding process.
Response
If the webhook URL receives a notification from the Ongoing Monitoring API, it should respond with a 200 OK HTTP status code as quickly as possible to indicate that the message has been received and acknowledged. If the webhook does not receive the notification successfully, the API will automatically attempt to resend the notification at regular intervals until the webhook acknowledges receipt of the message to ensure message delivery. To avoid timeouts or delays, any long-running processes should be written as code that can run asynchronously outside the webhook endpoint.
For each match a separate webhook is triggered (e.g., there can be multiple matches in one list and across lists).
Payload
The payload is sent to the registered webhook URL in JSON format, whenever there is a change to a risk profile. An example JSON payload for the entity type "Individual" is shown below:
{
"timestamp": "2024-03-24T19:16:00Z",
"profile_id": "abcdefg-1234",
"match_type": "ADD",
"entity": {
"source_id": "dilisense_pep",
"source_type": "PEP",
"pep_type": "POLITICIAN",
"entity_type": "INDIVIDUAL",
"name": "Boris Johnson",
"given_names": [
"Boris"
],
"last_names": [
"Johnson"
],
"gender": "MALE",
"date_of_birth": [
"19/06/1964"
],
"political_parties": [
"Conservative Party"
],
"description": [
"Prime Minister of the United Kingdom"
],
"occupations": [
"journalist",
"politician"
],
"links": [
"Facebook: borisjohnson"
],
"citizenship": [
"United Kingdom",
"United States of America"
],
"positions": [
"2001-06-07 - 2005-04-11 Member of the 53rd Parliament of the United Kingdom",
"2005-05-05 - 2008-06-04 Member of the 54th Parliament of the United Kingdom",
"2008-05-04 - 2016-05-07 Mayor of London",
"2015-05-07 - 2017-05-03 Member of the 56th Parliament of the United Kingdom",
"2016-07-13 - 2018-07-09 Secretary of State for Foreign and Commonwealth Affairs",
"2017-06-08 - 2019-11-06 Member of the 57th Parliament of the United Kingdom",
"Since 2016-01-01 Member of the Privy Council of the United Kingdom",
"Since 2019-07-23 Leader of the Conservative Party",
"Since 2019-07-24 First Lord of the Treasury",
"Since 2019-07-24 Minister for the Civil Service",
"Since 2019-07-24 Prime Minister of the United Kingdom",
"Since 2019-07-26 Minister for the Union",
"Since 2019-12-12 Member of the 58th Parliament of the United Kingdom"
],
"place_of_birth": [
"New York City"
],
"parents": [
"Charlotte Johnson Wahl",
"Stanley Johnson"
],
"siblings": [
"Jo Johnson",
"Leo Johnson",
"Rachel Johnson"
],
"spouse": [
"Allegra Mostyn-Owen",
"Marina Wheeler"
],
"children": [
"Cassia Peaches Johnson",
"Lara Lettice Johnson",
"Milo Arthur Johnson",
"Theodore Apollo Johnson",
"Wilfred Johnson"
]
}
}
The data above is test data to illustrate the payload. Any similarity to actual individuals, existing or past, is purely coincidental.
Attributes
profile_id (string)
A unique identifier the client sets to reference the notification to their records.
match_type (string)
- ADD: The notification is for a new addition to the database.
- UPDATE: The notification is for an update to an existing record.
- DELETE: The notification is for a deletion of an existing record.
entity (object)
The entity contains the attributes for an Individual or an Entity (see below).
6. Attributes - Individual
Attributes which are empty are not present in the response.
source_type (enumeration)
- SANCTION
- PEP
- CRIMINAL
- OTHER (These sources need to be requested from clients as they are not included by default. The current list is available at https://dilisense.com/en/sources/additional-sources)
One of these values will be set.
pep_type (enumeration)
- POLITICIAN
- JUDGE
- BOARD_MEMBER_OF_CENTRAL_BANK
- EXECUTIVE_AUDITOR
- ADMINISTRATION_OFFICE_EXECUTIVE
- MILITARY_OFFICIAL
- EMBASSY_OFFICIAL
- INTERNATIONAL_ORGANIZATION_OFFICIAL
- RELATIVES_AND_CLOSE_ASSOCIATES
- STATE_OWNED_ENTERPRISE
- BOARD_MEMBER_OF_STATE_OWNED_ENTERPRISE
- PROSECUTION_OFFICIAL
- AGENCY_OFFICIAL
- OTHER
One of these values will be set only for source_type PEP.
source_id (string)
The source id of the list that can be queried by the getSourceList API method call.
id (string)
The unique id across the whole dataset in an alphanumeric format (e.g. 9a18cb44f9ff6af5).
entity_type (enumeration)
Enumeration: INDIVIDUAL UNKNOWN
One of these values will be set.
list_date (long)
Unix timestamp in milliseconds presenting the date of the source as provided by the source authors. If not available, this value will be “0”.
gender (enumeration)
- FEMALE
- MALE
- UNKNOWN
One of these values will be set.
name (string)
The name of the individual.
tl_name (string)
A third party tool is used for the transliteration of the name from Arabic or Chinese script into Latin script. The transliterated name is not coming from the original source.
alias_names (string array)
A list with alias names of this individual.
last_names (string array)
A list with last names of this individual.
given_names (string array)
A list with given names of this individual.
alias_given_names (string array)
A list with alias given names of this individual.
name_remarks (string array)
A list of name remarks for this individual.
spouse (string array)
A list of spouse names for this individual.
parents (string array)
A list of parent names for this individual.
children (string array)
A list of children names for this individual.
siblings (string array)
A list of sibling names for this individual.
date_of_birth (string array)
A list of date of births for this individual.
date_of_birth_remarks (string array)
A list of date of birth remarks for this individual.
place_of_birth (string array)
A list of place of births for this individual.
place_of_birth_remarks (string array)
A list of place of birth remarks for this individual.
address (string array)
A list of addresses for this individual.
address_remarks (string array)
A list of address remarks for this individual.
citizenship (string array)
A list of citizenships for this individual in iso 3166-1 alpha-2 format.
citizenship_remarks (string array)
A list of citizenship remarks for this individual.
sanction_details (string array)
A list of sanction details for this individual.