Julius Möller

How to get started with the 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://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

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.

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": {
    "keywords": [
      "Fraud", 
      "Theft", 
      "Steal", 
      "Scam", 
      "Money Laundering", 
      "Sanction", 
      "Human Rights Violation", 
      "Terrorist", 
      "Organised Crime", 
      "Corrupt", 
      "Bribe", 
      "Tax Evasion", 
      "Convicted", 
      "Sentenced", 
      "Arrested", 
      "Fined", 
      "Child Labour", 
      "Exploitation", 
      "Racism", 
      "Embezzlement", 
      "Cybercrime", 
      "Forgery", 
      "Extortion", 
      "Blackmail", 
      "Smuggling", 
      "Racketeering", 
      "Insider Trading", 
      "Ponzi Scheme", 
      "Identity Theft", 
      "Counterfeiting", 
      "Hacking", 
      "Piracy", 
      "Drug Trafficking", 
      "Arms Dealing", 
      "Espionage"
    ],
    "language": "en",
    "risk_categories": [
      "Fraud", 
      "Money Laundering", 
      "Sanctions", 
      "Human Rights Abuse", 
      "Environmental Abuse", 
      "Terrorism", 
      "Organized Crime", 
      "Corruption", 
      "Tax Crimes", 
      "Violence", 
      "Theft", 
      "Discrimination", 
      "Other"
    ]
  }
}'

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": {
    "keywords": [
      "Fraud", 
      "Theft", 
      "Steal", 
      "Scam", 
      "Money Laundering", 
      "Sanction", 
      "Human Rights Violation", 
      "Terrorist", 
      "Organised Crime", 
      "Corrupt", 
      "Bribe", 
      "Tax Evasion", 
      "Convicted", 
      "Sentenced", 
      "Arrested", 
      "Fined", 
      "Child Labour", 
      "Exploitation", 
      "Racism", 
      "Embezzlement", 
      "Cybercrime", 
      "Forgery", 
      "Extortion", 
      "Blackmail", 
      "Smuggling", 
      "Racketeering", 
      "Insider Trading", 
      "Ponzi Scheme", 
      "Identity Theft", 
      "Counterfeiting", 
      "Hacking", 
      "Piracy", 
      "Drug Trafficking", 
      "Arms Dealing", 
      "Espionage"
    ],
    "language": "en",
    "risk_categories": [
      "Fraud", 
      "Money Laundering", 
      "Sanctions", 
      "Human Rights Abuse", 
      "Environmental Abuse", 
      "Terrorism", 
      "Organized Crime", 
      "Corruption", 
      "Tax Crimes", 
      "Violence", 
      "Theft", 
      "Discrimination", 
      "Other"
    ],
    "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: ••••••'

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]

25 Screenings For Free

25 screenings free
No credit card required
Get 25 Screenings for Free