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 require your API key in the x-api-key header. See Authentication.

---

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%20Johnson&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%20Johnson&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%20Johnson&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 perform an initial screening, and matches that already exist at the time of registration will not trigger a webhook. Therefore, first register the search profile and screen the name with checkIndividual 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?profile_id=abcdefg-1234&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%20GMBH%20GERMANY"

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%20GMBH%20GERMANY"))
     .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%20GMBH%20GERMANY", 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 perform an initial screening, and matches that already exist at the time of registration will not trigger a webhook. Therefore, first register the search profile and screen the name with checkEntity 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 every notification carries a payload signature in the x-dilisense-signature header, which proves that the body originates from dilisense and was not altered, see Signature Verification.

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",
  "event_id": "3f6c2a9e-8d41-4b7a-9c5e-1a2b3c4d5e6f",
  "profile_id": "abcdefg-1234",
  "match_type": "ADD",
  "entity": {
	"id": "c438b18a93cd3c13",
	"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

event_idstring

A unique identifier of the notification in UUID format, which is always included. If a notification is delivered again, for example because your endpoint did not acknowledge it in time, it is sent with the same event_id, so that you can use it to detect and discard duplicates.

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

See Versioning.

---

10. Usage Limits

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. See Usage and Quotas.

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 as ongoing_monitoring_profiles_registered, which you can reconcile against the search profiles tracked in your own system.

---

11. Errors

The API returns the regular HTTP error codes with a JSON error message. See Errors for all codes and for how to handle throttling.