> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taidalos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Search API

> This guide provides a step-by-step tutorial on solving the adverse media screening challenge using a few simple APIs.

APIs are tools that help software systems communicate with each other, allowing you to solve problems and automate
tasks. This guide will walk you through using an API to streamline adverse media screening — checking for negative media
coverage about individuals or organizations.

## Goal

By the end of this guide, you’ll know how to set up and run media screenings via API and connect the results to your CRM
system.

## 1. Explore the API documentation (optional)

After you sign up, you can explore the API documentation (in the lower left-hand corner of the sidebar). You can also
download the Open API Specifications and use them however you like. You can import them into Postman or a similar
solution to make API calls from the convenience of a User Interface.

Download Postman or insomnia here:
[https://www.postman.com/downloads/](https://www.postman.com/downloads/)
[https://insomnia.rest/download](https://insomnia.rest/download)

## 2. Let’s understand the objects

### `subject`

A `subject` is the subject you want to investigate (e.g., do media research). This can be an individual or a legal
entity. One subject can have multiple `media-searches`.

### `media-search-configuration`

A `media-search-configuration` holds configuration data for `media-searches`. You can create one
`media-search-configuration` object and reference this object for multiple `media-search`objects.

### `media-search`

A `media-search` is the parent container for all `media-search-execution` objects for a given `subject`. To create a
`media-search`, you need a `subject` and a `media-search-configuration` reference.

### `media-search-execution`

You can create `media-searche` objects without executing them. One `media-search` object can have 0, 1, or multiple
`media-search-execution` objects. This is handy for creating `media-search`es in bulk without immediate execution or
having multiple `media-search-execution`s over time (monitoring).

## Steps By Step Guide to your first media search results

### 1. Sign Up

Sign up at [https://taidalos.com](https://taidalos.com) (it’s free, no credit card required, enough free credits to play around with the
application and API)

### 2. Create an API Key

After you have signed up, go to “Integrations” and create a new API key by adding a meaningful description and click
“Generate API Credentials”. Copy the key to a safe place. You will not be able to see the secret again. However, you can
create a new secret anytime and delete the old one.

Add the API key to the `header` for each request like so:
`Authorization: Basic...`
In Postman, you can go to the top level of the collection (Taidalos API Documentation), and go to “Authorization”.
Select “API Key” as the Auth Type. Add “Authorization” as the key and the API Key you have created as the value. Set
“Add to” to “Header” and click “Save”.

### 3. Create a subject

You can create a `subject` with as much or as little information as you want or that is available to you. The only
property that is required is the `name`.

All information:

* **Name (required)**
* Internal ID
* Aliases
* Type (“INDIVIDUAL”, “LEGAL\_ENTITY”)
* Date of Birth (for individuals)
* Date of Incorporation (for Legal Entities)
* Places
* Industries
* Nationalities

A very simple request could look something like:

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/subjects/create-subject' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "data": {
    "name": "Jan Marsalek"
  }
}'
```

Or more complex ones like:

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/subjects/create-subject' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "data": {
    "name": "Meta",
    "type": "LEGAL_ENTITY",
    "aliases": [
      "Facebook",
      "Instagram"
    ],
    "places": [
      {
        "description": "Head Quarter",
        "place": "1 Hacker Way, Menlo Park, CA 94025, US"
      },
      {
        "description": "Office in Hamburg",
        "place": "Curienstraße 2, 20095 Hamburg"
      }
    ],
    "date_of_incorporation": "2004-01-04",
    "industries": [
      "Software",
      "Communication"
    ],
    "internal_id": "crm_id#123456789"
  }
}'
```

To start quickly, use the simple one and add more information, such as the internal\_id (which can be your system's CRM
ID), to the payload.

### 4. Create a Search Configuration

> **Update May 2025** Use `keyword_lists` instead of `keywords` to configure your keywords. That way you can cover
> multiple languages. The property `keywords` is still supported for backward compatability.

You only need to create one `media-search-configuration` that can be reused across multiple `media-search` objects. To
start
quickly, use the template below and save the `media_search_configuration_id` from the response.

The below example uses two keyword lists to cover English and German media. Create a template in the UI to explore more
languages and tailor the keywords to meet your risk appetite.

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/media-searches/configuration/create-configuration' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "data": {
        "keyword_lists": [
            {
                "name": "English Keywords",
                "keywords": [
                    "Arms Dealing",
                    "Arrested",
                    "Blackmail",
                    "Bribe",
                    "Child Labour",
                    "Convicted",
                    "Corrupt",
                    "Counterfeiting",
                    "Data Breach",
                    "Drug Trafficking",
                    "Embezzlement",
                    "Espionage",
                    "Exploitation",
                    "Extortion",
                    "Felony",
                    "Fined",
                    "Forced Labor",
                    "Fraud",
                    "Human Rights",
                    "Human Trafficking",
                    "Indicted",
                    "Market Manipulation",
                    "Misappropriation",
                    "Money Laundering",
                    "Organised Crime",
                    "Piracy",
                    "Pollution",
                    "Ponzi",
                    "Price Fixing",
                    "Privacy Violation",
                    "Racism",
                    "Racketeering",
                    "Sanction",
                    "Scam",
                    "Sentenced",
                    "Shell Company",
                    "Slavery",
                    "Smuggling",
                    "Steal",
                    "Tax Evasion",
                    "Terrorist",
                    "Theft",
                    "Wildlife Trafficking"
                ]
            },
            {
                "name": "German Keywords",
                "keywords": [
                    "Angeklagt",
                    "Ausbeutung",
                    "Bestechung",
                    "Betrug",
                    "Briefkastenfirma",
                    "Datenschutzverletzung",
                    "Diebstahl",
                    "Drogenhandel",
                    "Erpressung",
                    "Fälschung",
                    "Geldstrafe",
                    "Geldwäsche",
                    "Kinderarbeit",
                    "Korrupt",
                    "Marktmanipulation",
                    "Menschenhandel",
                    "Menschenrechte",
                    "Organisierte Kriminalität",
                    "Piraterie",
                    "Ponzi",
                    "Preisabsprache",
                    "Rassismus",
                    "Sanktion",
                    "Schmuggel",
                    "Schwerverbrechen",
                    "Sklaverei",
                    "Spionage",
                    "Stehlen",
                    "Steuerhinterziehung",
                    "Terrorist",
                    "Umweltverschmutzung",
                    "Unterschlagung",
                    "Verhaftet",
                    "Verletzung der Privatsphäre",
                    "Veruntreuung",
                    "Verurteilt",
                    "Waffenhandel",
                    "Wildtierhandel",
                    "Zwangsarbeit"
                ]
            }
        ],
        "language": "en",
        "risk_categories": [
            "Arms & Drugs & Human Trafficking",
            "Civil/Administrative Actions",
            "Corruption",
            "Criminal Proceedings",
            "Data & Privacy Violations",
            "Discrimination",
            "Environmental Crimes",
            "Extortion & Blackmail",
            "Fraud & Theft",
            "Human Rights Violations",
            "Money Laundering",
            "Organized Crime",
            "Other Financial Crimes",
            "Racketeering",
            "Sanctions",
            "Tax Crimes",
            "Terrorism"
        ]
    }
}'
```

### 4.1. Monitoring (Optional)

> **Update** New feature since March 2025

Since March 2025, you can adjust the `media-search-configuration` to run searches periodically, ensuring you never miss
new media. You
can choose from daily, weekly, monthly, quarterly, or yearly monitoring. Simply add the monitoring object

```txt theme={null}
"monitoring": {
    "interval": "WEEKLY",
    "is_active": true
}
```

to the `media-search-configuration` request like this:

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/media-searches/configuration/create-configuration' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "data": {
        "keyword_lists": [
            {
                "name": "English Keywords",
                "keywords": [
                    "Arms Dealing",
                    "Arrested",
                    "Blackmail",
                    "Bribe",
                    "Child Labour",
                    "Convicted",
                    "Corrupt",
                    "Counterfeiting",
                    "Data Breach",
                    "Drug Trafficking",
                    "Embezzlement",
                    "Espionage",
                    "Exploitation",
                    "Extortion",
                    "Felony",
                    "Fined",
                    "Forced Labor",
                    "Fraud",
                    "Human Rights",
                    "Human Trafficking",
                    "Indicted",
                    "Market Manipulation",
                    "Misappropriation",
                    "Money Laundering",
                    "Organised Crime",
                    "Piracy",
                    "Pollution",
                    "Ponzi",
                    "Price Fixing",
                    "Privacy Violation",
                    "Racism",
                    "Racketeering",
                    "Sanction",
                    "Scam",
                    "Sentenced",
                    "Shell Company",
                    "Slavery",
                    "Smuggling",
                    "Steal",
                    "Tax Evasion",
                    "Terrorist",
                    "Theft",
                    "Wildlife Trafficking"
                ]
            },
            {
                "name": "German Keywords",
                "keywords": [
                    "Angeklagt",
                    "Ausbeutung",
                    "Bestechung",
                    "Betrug",
                    "Briefkastenfirma",
                    "Datenschutzverletzung",
                    "Diebstahl",
                    "Drogenhandel",
                    "Erpressung",
                    "Fälschung",
                    "Geldstrafe",
                    "Geldwäsche",
                    "Kinderarbeit",
                    "Korrupt",
                    "Marktmanipulation",
                    "Menschenhandel",
                    "Menschenrechte",
                    "Organisierte Kriminalität",
                    "Piraterie",
                    "Ponzi",
                    "Preisabsprache",
                    "Rassismus",
                    "Sanktion",
                    "Schmuggel",
                    "Schwerverbrechen",
                    "Sklaverei",
                    "Spionage",
                    "Stehlen",
                    "Steuerhinterziehung",
                    "Terrorist",
                    "Umweltverschmutzung",
                    "Unterschlagung",
                    "Verhaftet",
                    "Verletzung der Privatsphäre",
                    "Veruntreuung",
                    "Verurteilt",
                    "Waffenhandel",
                    "Wildtierhandel",
                    "Zwangsarbeit"
                ]
            }
        ],
        "language": "en",
        "risk_categories": [
            "Arms & Drugs & Human Trafficking",
            "Civil/Administrative Actions",
            "Corruption",
            "Criminal Proceedings",
            "Data & Privacy Violations",
            "Discrimination",
            "Environmental Crimes",
            "Extortion & Blackmail",
            "Fraud & Theft",
            "Human Rights Violations",
            "Money Laundering",
            "Organized Crime",
            "Other Financial Crimes",
            "Racketeering",
            "Sanctions",
            "Tax Crimes",
            "Terrorism"
        ],
        "monitoring": {
            "interval": "WEEKLY",
            "is_active": true
        }
    }
}'
```

The property `is_active` needs to be set to `true`. The property `interval` can have the following values:

* `DAILY`
* `WEEKLY`
* `MONTHLY`
* `QUARTERLY`
* `YEARLY`

### 5. Create a media search with immediate execution

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/media-searches/create-search' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "data": {
    "execute_immediately": true,
    "media_search_configuration_id": "<id from step 4>",
    "subject_id": "id from step 3"
  }
}'
```

Make sure that `execute_immediately` is set to `true`.

**DONE!**

You can now go to the User Interface to see the media search (it might be in progress and not done yet). You can also
send requests to

```bash theme={null}
curl --location 'https://api.taidalos.com/v1/media-searches/aggregate/<media_search_id from step 5>' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

The summary and justification will be returned as Markdown. However, if you want, you can remove the Markdown tags
and use plain text by setting the `remove_markdown` query parameter to `true`.
This will remove all Markdown syntax except ordered and unordered list syntax, e.g., `-`, `1.`, `2.`, etc.

To get the results via the API. You can also set up webhooks to listen to the completion of `media-search-exection`s.

Let us know if you have any questions or if anything is unclear. We are happy to help!
Contact us: [cs@taidalos.com](mailto:cs@taidalos.com)

## Next Steps

Use webhooks to listen to the completion of`media-search-execution`
s: [How to get started with the webhook?](https://taidalos.com/blog/webhook-get-started/) to handel load on scale.