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

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>'

Python

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)

Java

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();

Javascript

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.

info

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

curl --location --request GET 'https://api.dilisense.com/v1/registerEntity?names=REYCO%20GMBH%20GERMANY' \
--header 'x-api-key: <api_key>'

Python

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)

Java

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();

Javascript

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.

info

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

curl --location --request GET 'https://api.dilisense.com/v1/removeSearchProfile?profile_id=abcdefg-1234' \
--header 'x-api-key: <api_key>'

Python

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)

Java

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();

Javascript

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.

info

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.

info

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)

Indicates whether the notification is for a new addition to the database ('ADD') or an update to an existing record ('UPDATE'). UPDATE also includes the removal of records.

entity (object)

The entity contains the attributes for an Individual or an Entity (see below).

6. Attributes - Individual

info

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 listSources 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.

description (string array)

A list of descriptions for this individual.

occupations (string array)

A list of occupations for this individual.

positions (string array)

A list of positions for this individual.

political_parties (string array)

A list of political parties for this individual. Usually this is only filled for source_type = PEP.

links (string array)

A list of links for this individual. This can be websites but also email addresses.

titles (string array)

A list of titles for this individual (e.g. Dr., Prof., Hon. etc.).

functions (string array)

A list of functions for this individual.

other_information (string array)

A list of other information for this individual that cannot be categorized otherwise.

7. Attributes - Entity

info

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)

• STATE_OWNED_ENTERPRISE

This is only set for source_type PEP.

source_id (string)

The source id of the list that can be queried by the listSources API method call.

id (string)

The unique id across the whole dataset in an alphanumeric format (e.g. 9a18cb44f9ff6af5).

entity_type (enumeration)

• Entity
• 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”.

company_number (string array)

The company number of this entity (e.g. the registration number in the respective jurisdiction).

name (string)

The name if the entity.

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 of alias names for this entity.

name_remarks (string array)

A list of name remarks for this entity.

jurisdiction (string array)

A list of jurisdictions for this entity in iso 3166-1 alpha-2 format.

address (string array)

A list of addresses for this entity.

address_remarks (string array)

A list of address remarks for this entity.

sanction_details (string array)

The details of why the entity is sanctioned. Only available for source_type = SANCTION.

links (string array)

A list of links for this entity. This can be websites but also email addresses.

other_information (string array)

A list of other information for this entity that cannot be categorized otherwise.

---

8. Versioning

The API versioning will be incremental starting from v1. Only if there are breaking changes, we will increase the version to v2 and higher. We reserve the right to introduce new functionalities at any time which are not considered breaking the current API request / response logic.

Once a new API version is available, you will be notified. However you can still use the old API version for at least 12 months before we stop support for the old version.

---

9. Usage Limits

We apply usage limits ("quotas") to protect you from unexpected costs. You can update that quota anytime by sending an email to sales@dilisense.com.

---

10. Errors

The dilisense API adheres to the regular HTTP error codes. This means that codes in the 2xx range indicate a successful API call, codes in the range of 4xx indicate an error on the client side (e.g. failed authentication, missing request parameter etc.) and codes in the 5xx range inform you about an error with the dilisense servers.

The detailed error codes are:

200 - OK - The request was successful.
400 - Bad Request - The request was incorrect.
401 - Unauthorized - The API key was not valid.
403 - Forbidden - The URL is not accessible.
500 - Internal Server Error - An internal error occurred.

There is a detailed error message (JSON) available for each of the error responses, for example:

"{"error_message": "The name parameter is mandatory, but has not been set."}"