Skip to main content
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://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-searchobjects. 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-searches in bulk without immediate execution or having multiple media-search-executions over time (monitoring).

​
Steps By Step Guide to your first media search results

​
1. Sign Up

Sign up at https://taidlaos.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: 
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: 
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. 
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 
"monitoring": {
    "interval": "WEEKLY",
    "is_active": true
}
to the media-search-configuration request like this: 
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

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 
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-exections. Let us know if you have any questions or if anything is unclear. We are happy to help! Contact us: [email protected]

​
Next Steps

Use webhooks to listen to the completion ofmedia-search-execution s: How to get started with the webhook? to handel load on scale.