Adverse Media Screening API

Screen more than 235,000 news sources.

The dilisense API provides you with machine-to-machine access to the dilisense methods for checking individual and entity names against Adverse Media news sources. Our APIs are REST based and as such accept GET requests with the parameters specified in this document. The response is always in JSON format, successes as well as errors. The API calls have to be made via HTTPS requests.

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. checkIndividual (GET)

The checkIndividual API method searches for individuals that match certain criteria. The client can decide which lists should be included in the search to limit the results to the relevant ones.

Endpoint

https://api.dilisense.com/v1/media/checkIndividual

Request parameters

search_all

Search string that is screened against Adverse Media news sources.

fetch_articles (optional)

Determines if detailed articles are included in the response. Defaults to false.

Response

The response provided back is formatted as JSON.

timestamp (string)

The timestamp of the response (ISO 8601 date time).

total_hits (number)

The total_hits parameter represents the total number of articles matching the search across the entire search index.
This count includes:

1. Articles that do appear under any of the listed categories (e.g., political, terrorism, etc.).
2. Articles that do not belong to any specific category but still match the search criteria.

info

Because total_hits counts every match for your search query, it is possible that the sum of the category-specific hits is less than total_hits. The difference comes from those articles which do not fall under any defined category but still mention your search term.

Example

Suppose you search for "Boris Johnson" and the API response shows:

• total_hits: 2,000
• A breakdown of 1,650 articles spread across the categories (e.g., political, terrorism, violent_crime, etc.)

In this scenario, the remaining 350 articles still mention "Boris Johnson" but do not fit into any of those categories. These “uncategorized” articles are still included in the overall total_hits count of 2,000, even though they do not appear within news_exposures for a specific category.

news_exposures (object)

Object with the keys specified in category.

info

All categories will be returned, even if they contain 0 hits.

Each object within news_exposures contains the following attributes:

category (enumeration)

• political
• regulatory
• terrorism
• financial_crime
• organized_crime
• violent_crime

hits (number)

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

articles (array)

The array is only present if fetch_articles parameter is set to 'true'.

info

The number of articles per category is limited to 10 items. The limit can be increased per API key if required.

Each article contains the following attributes:

timestamp (string)

The timestamp of the article (ISO 8601 date time).

language (string)

The ISO 2 3166-1 alpha-2 code of the article language.

headline (string)

The headline of the article.

source_link (string)

The link to the source of the article. Some articles might be only accessible with a subscription of the respective media company.

body (string)

The content of the article. Paragraphs are marked with <p></p>.

Example

curl

Request

curl --location --request GET 'https://api.dilisense.com/v1/media/checkIndividual?search_all=Boris%20Johnson' \
--header 'x-api-key: <api_key>'

Python

import requests

url = "https://api.dilisense.com/v1/media/checkIndividual?search_all=Boris Johnson"

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/media/checkIndividual?search_all=Boris Johnson"))
     .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/media/checkIndividual?search_all=Boris Johnson", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Response (fetch_articles=false)

{
  "timestamp": "2024-12-20T14:17:16.843Z",
  "total_hits": 1715870,
  "news_exposures": {
    "violent_crime": {
      "category": "violent_crime",
      "hits": 28466
    },
    "terrorism": {
      "category": "terrorism",
      "hits": 796691
    },
    "regulatory": {
      "category": "regulatory",
      "hits": 984492
    },
    "financial_crime": {
      "category": "financial_crime",
      "hits": 26088
    },
    "political": {
      "category": "political",
      "hits": 1649400
    },
    "organized_crime": {
      "category": "organized_crime",
      "hits": 23546
    }
  }
}

Response (fetch_articles=true)

{
    "timestamp": "2024-11-11T14:22:07.447Z",
    "total_hits": 1307,
    "news_exposures": {
        "terrorism": {
            "category": "terrorism",
            "hits": 801,
            "articles": [
                {
                    "timestamp": "2024-11-06T08:02:35Z",
                    "language": "en",
                    "headline": "Boris Johnson ‘fired' during live US election coverage for plugging memoir - Evening Standard 1",
                    "body": "<p> Channel 4 ‘fired' Boris Johnson from US election show for promoting his book, co-host says</p> <p> The Guardian</p> <p> US election 2024 result viewers praise Emily Maitlis for eviscerating Boris Johnson</p> <p> The Independent</p> <p> Boris Johnson ‘fired' from Channel 4's US election coverage</p> <p> The Telegraph</p> <p> Stormy Daniels and Boris Johnson were only the start of a mad night</p> <p> The Times</p>",
                    "source_link": "https://www.info-flash.com/info-flash/actualites/royaume-uni/93518-united-kingdom/79685542-boris-johnson-fired-during-live-us-election-coverage-for-plugging-memoir-evening-standard.html"
                }
	    ]
   	}
    }
}

The data above is test data to illustrate the payload. Any similarity to actual individuals, existing or past, is purely coincidental.

---

4. 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-4489-437e-ad01-fdbc0540f18b",
		"name": "dilisense - Adverse Media Screening API",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "11"
	},
	"item": [
		{
			"name": "media - checkIndividual",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "x-api-key",
						"value": "{{auth-key}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "{{url}}/media/checkIndividual?search_all=Boris Johnson&fetch_articles=true",
					"host": [
						"{{url}}"
					],
					"path": [
						"",
						"media",
						"checkIndividual"
					],
					"query": [
						{
							"key": "search_all",
							"value": "Boris Johnson"
						},
						{
							"key": "fetch_articles",
							"value": "true"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "media - checkEntity",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "x-api-key",
						"value": "{{auth-key}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "{{url}}/media/checkEntity?search_all=Boris Johnson&fetch_articles=true",
					"host": [
						"{{url}}"
					],
					"path": [
						"",
						"media",
						"checkEntity"
					],
					"query": [
						{
							"key": "search_all",
							"value": "Boris Johnson"
						},
						{
							"key": "fetch_articles",
							"value": "true"
						}
					]
				}
			},
			"response": []
		}
	],
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"key": "auth-key",
			"value": "x-api-key",
			"type": "string"
		}
	]
}

---

5. OpenAPI Documentation

The OpenAPI documentation (formerly known as swagger) can be used for automated generation of API client code. Our OpenAPI documentation is available here: https://api-doc.dilisense.com/

---

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

---

7. Usage Limits

After registration on https://dilisense.com/en/register you can find your API key with 100 free API calls per month in your dashboard. If you add your credit card, this quota limit will be increased automatically to 10.000 API calls per month. You can also contact our sales team (sales@dilisense.com) to increase you quota limit in case you want to pay via bank transfer or in case you need more than 10.000 API calls per month.

---

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