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. If a search profile with this profile_id is already registered, the existing profile is updated with the parameters of the new 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.

doboptional

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

genderoptional

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_searchoptional

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

Registration does not include a baseline screening and matches at the time of registration will not trigger a webhook. To obtain the current screening result, call checkIndividual first and register the search profile afterwards.

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. If a search profile with this profile_id is already registered, the existing profile is updated with the parameters of the new 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_searchoptional

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

Registration does not include a baseline screening and matches at the time of registration will not trigger a webhook. To obtain the current screening result, call checkEntity first and register the search profile afterwards.

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.

info

The endpoint is idempotent. Removing a profile_id that is unknown or that has already been removed also returns the HTTP code 200, so that a request can safely be retried if a previous response did not reach your system.

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.

Authentication

Your API key is sent with every webhook request, so that you can verify that the notification originates from dilisense. In addition we can enable a payload signature, which is sent as an HTTP header. Please contact us at support@dilisense.com if you would like to use the payload signature and we will enable it for your account.

Delivery cadence

Notifications are driven by the updates of the dilisense database and are not sent on a fixed schedule. Each database update is compared against the previous state and the resulting changes are computed subsequently. If an update contains no relevant change for your registered search profiles, no webhook is sent.

info

For each match a separate webhook is triggered, with ADD, UPDATE or DELETE as the match_type (e.g., there can be multiple matches in one list and across lists).

Response

If the webhook URL receives a notification from the Ongoing Monitoring API, it should respond with an HTTP status code in the 2xx range within 30 seconds to indicate that the message has been received and acknowledged. The response body is ignored. To avoid timeouts or delays, any long-running processes should be written as code that can run asynchronously outside the webhook endpoint.

Testing the webhook

Once the webhook is configured, you can trigger a test notification to your configured webhook URL at any time in order to verify your integration:

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

A separate sandbox environment is not required. If you would like us to verify the integration together with you, please send us your webhook URL and we will send a test notification from our side.

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_idstring

A unique identifier the client sets to reference the notification to their records.

match_typestring

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

entityobject

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_typeenumeration

• 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_typeenumeration

• 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_idstring

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

idstring

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

entity_typestring

• INDIVIDUAL
• UNKNOWN

One of these values will be set.

list_datelong

Unix timestamp in milliseconds presenting the date of the source as provided by the source authors. If not available, this value will be “0”.

genderenumeration

• FEMALE
• MALE
• UNKNOWN

One of these values will be set.

namestring

The name of the individual.

tl_namestring

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_namesstring array

A list with alias names of this individual.

last_namesstring array

A list with last names of this individual.

given_namesstring array

A list with given names of this individual.

alias_given_namesstring array

A list with alias given names of this individual.

name_remarksstring array

A list of name remarks for this individual.

spousestring array

A list of spouse names for this individual.

parentsstring array

A list of parent names for this individual.

childrenstring array

A list of children names for this individual.

siblingsstring array

A list of sibling names for this individual.

date_of_birthstring array

A list of date of births for this individual.

date_of_birth_remarksstring array

A list of date of birth remarks for this individual.

place_of_birthstring array

A list of place of births for this individual.

place_of_birth_remarksstring array

A list of place of birth remarks for this individual.

addressstring array

A list of addresses for this individual.

address_remarksstring array

A list of address remarks for this individual.

citizenshipstring array

A list of citizenships for this individual in iso 3166-1 alpha-2 format.

citizenship_remarksstring array

A list of citizenship remarks for this individual.

sanction_detailsstring array

A list of sanction details for this individual.

descriptionstring array

A list of descriptions for this individual.

occupationsstring array

A list of occupations for this individual.

positionsstring array

A list of positions for this individual.

political_partiesstring array

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

linksstring array

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

titlesstring array

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

functionsstring array

A list of functions for this individual.

other_informationstring 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_typeenumeration

• 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_typeenumeration

• STATE_OWNED_ENTERPRISE

This is only set for source_type PEP.

source_idstring

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

idstring

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

entity_typestring

• ENTITY
• UNKNOWN

One of these values will be set.

list_datelong

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_numberstring array

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

namestring

The name of the entity.

tl_namestring

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_namesstring array

A list of alias names for this entity.

name_remarksstring array

A list of name remarks for this entity.

jurisdictionstring array

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

addressstring array

A list of addresses for this entity.

address_remarksstring array

A list of address remarks for this entity.

sanction_detailsstring array

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

linksstring array

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

other_informationstring array

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

---

8. Postman Collection

A Postman collection is a group of individual API calls and organized in folders. With the attached names and descriptions, such a collection helps understanding and trying out our API with a button click.

You can use it with your API key which you receive after registration (no credit card required):

https://dilisense.com/en/register

{
  "info": {
    "_postman_id": "0d8c7b30-4499-447e-ad01-fdbc0540f18b",
    "name": "dilisense",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "1749711"
  },
  "item": [
    {
      "name": "registerIndividual",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "x-api-key",
            "value": "{{auth-key}}",
            "type": "text"
          }
        ],
        "url": {
          "raw": "https://api.dilisense.com/v1/registerIndividual?profile_id=123&names=Donald Trump",
          "protocol": "https",
          "host": [
            "api",
            "dilisense",
            "com"
          ],
          "path": [
            "v1",
            "registerIndividual"
          ],
          "query": [
            {
              "key": "profile_id",
              "value": "123"
            },
            {
              "key": "names",
              "value": "Donald Trump"
            },
            {
              "key": "search_all",
              "value": null,
              "type": "text",
              "disabled": true
            },
            {
              "key": "dob",
              "value": null,
              "disabled": true
            },
            {
              "key": "gender",
              "value": null,
              "disabled": true
            },
            {
              "key": "fuzzy_search",
              "value": null,
              "disabled": true
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "registerEntity",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "x-api-key",
            "value": "{{auth-key}}",
            "type": "text"
          }
        ],
        "url": {
          "raw": "https://api.dilisense.com/v1/registerEntity?profile_id=123&names=Google",
          "protocol": "https",
          "host": [
            "api",
            "dilisense",
            "com"
          ],
          "path": [
            "v1",
            "registerEntity"
          ],
          "query": [
            {
              "key": "profile_id",
              "value": "123",
              "type": "text"
            },
            {
              "key": "names",
              "value": "Google"
            },
            {
              "key": "search_all",
              "value": null,
              "type": "text",
              "disabled": true
            },
            {
              "key": "fuzzy_search",
              "value": "",
              "disabled": true
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "removeSearchProfile",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "x-api-key",
            "value": "{{auth-key}}",
            "type": "text"
          }
        ],
        "url": {
          "raw": "https://api.dilisense.com/v1/removeSearchProfile?profile_id=123",
          "protocol": "https",
          "host": [
            "api",
            "dilisense",
            "com"
          ],
          "path": [
            "v1",
            "removeSearchProfile"
          ],
          "query": [
            {
              "key": "profile_id",
              "value": "123"
            }
          ]
        }
      },
      "response": []
    }
  ],
  "auth": {
    "type": "apikey"
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          ""
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          ""
        ]
      }
    }
  ],
  "variable": [
    {
      "key": "auth-key",
      "value": "<your_api_key>",
      "type": "string"
    }
  ]
}

---

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

---

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

The registerIndividual, registerEntity and removeSearchProfile calls are free of charge and do not count towards the usage of the AML Screening API. Ongoing Monitoring is billed based on the average number of active search profiles during a month.

Reconciliation

For security reasons we do not offer an endpoint that returns all registered search profiles and their details. The /usage endpoint returns the number of currently registered search profiles, which you can reconcile against the search profiles tracked in your own system.

---

11. 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."
}