Adverse media screening

From news article to risk category in ~2 seconds

The pipeline is four stages: query construction, article fetch, LLM classification, and response assembly.

1. 1

   Query construction

   The entity name is escaped and wrapped in exact-phrase quotes, for people and companies alike. A tone<-3 filter keeps only negatively-toned articles. No keyword pre-filter is applied: whether an article is adverse, and in which category, is decided by the classifier against the full taxonomy.

2. 2

   GDELT DOC 2.0 fetch

   Up to 75 articles from the last 56 days are fetched from GDELT with 3 retries and exponential backoff. Social media domains, press releases, and known content farms are filtered out. Results are cached in Redis for 24 hours.

3. 3

   LLM classification

   Up to 20 articles per screening are classified in a single call with a fixed output schema. For each headline the classifier states the subject's role (accused, victim, only mentioned, or unclear), the category of any wrongdoing alleged against the subject, how clearly the headline describes an adverse act by the subject, and how sure it is that the article is about this subject rather than a namesake. Results are cached for 7 days.

4. 4

   Response assembly

   An article is flagged only when the subject is accused, the category is adverse, the article is about this subject, and the headline clearly describes the act. A serious allegation (sanctions, crime, fraud, corruption) whose subject role is unclear is not flagged but is marked needsReview. The risk score comes from the most severe flagged incident, with a small capped increase for further distinct incidents; it maps to overallRisk (CLEAR → CRITICAL), and any flagged or needs-review article keeps it off CLEAR. Every assessed article is returned, flagged or not.

POST /v1/adverse-media/screen

Authenticate with a Bearer token and provide the entity name, type, and optional context. The full schema is in the OpenAPI reference.

curl -X POST https://api.verifex.tech/v1/adverse-media/screen \
  -H "Authorization: Bearer vfx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "Acme Corporation",
    "entityType": "COMPANY",
    "context": {
      "country": "US",
      "industry": "pharmaceuticals"
    }
  }'

Structured risk assessment with per-article detail

Every response includes an overall risk level, a numeric score, flagged article count, and full per-article results with confidence and reasoning.

{
  "entityName": "Acme Corp",
  "screenedAt": "2026-05-15T10:31:00Z",
  "status": "COMPLETE",
  "outcome": "review_required",
  "headline": "Review required",
  "searchWindowDays": 56,
  "coverage": { "gdelt": "ok", "classifier": "ok", "complete": true },
  "overallRisk": "MEDIUM",
  "riskScore": 42,
  "articlesFound": 20,
  "articlesFlagged": 1,
  "articlesNeedingReview": 0,
  "cached": false,
  "llmCost": 0.0008,
  "promptVersion": "v2.0.0",
  "classifierModel": "claude-haiku-5-5",
  "quota": { "used": 12, "limit": 50, "remaining": 38, "resetsAt": "2026-06-01T00:00:00Z" },
  "results": [
    {
      "title": "Acme Corp fined $2M for compliance violations",
      "url": "https://example.com/article/123",
      "domain": "reuters.com",
      "publishedAt": "2026-05-15T10:30:00Z",
      "riskCategory": "REGULATORY",
      "subjectRole": "ACCUSED",
      "sanctionsContext": null,
      "adverseConfidence": 0.91,
      "entityMatchConfidence": 0.95,
      "confidence": 0.91,
      "reasoning": "Article describes a regulatory fine directly tied to the entity.",
      "isRelevant": true,
      "needsReview": false,
      "sentiment": 0
    }
  ]
}

Seven risk categories

The classifier assigns every article exactly one riskCategory: the type of adverse content. This is a different axis from overallRisk, which is the screening’s severity (UNKNOWN, CLEAR, LOW, MEDIUM, HIGH, CRITICAL). Six categories describe adverse content; NONE means none was found.

Quota-gated by plan

Adverse media screening is available on Growth, Pro, and Enterprise plans. Free and Starter plans receive a 403 response.

Quota is enforced atomically via Redis Lua script. Cache hits (Redis or PostgreSQL) consume zero quota. LLM failures also consume zero quota. Quota resets monthly with the billing cycle.

Expected errors and how to handle them

Official SDKs for common backends

The adverse media endpoint is accessible via the same SDKs as the rest of the Verifex API.

import { Verifex } from "verifex";

const verifex = new Verifex({ apiKey: "vfx_your_api_key" });

const result = await verifex.adverseMediaScreen({
  entity: "Acme Corporation",
  entityType: "COMPANY",
  context: { country: "US" },
});

console.log(result.overallRisk, result.articlesFlagged);

from verifex import VerifexClient

client = VerifexClient("vfx_your_api_key")

result = client.adverse_media_screen(
    entity="Acme Corporation",
    entity_type="COMPANY",
    context={"country": "US"},
)

print(result.overall_risk, result.articles_flagged)

import (
    "context"
    verifex "github.com/Verifex-dev/verifex-go-sdk"
)

client := verifex.New("vfx_your_api_key")

result, err := client.AdverseMediaScreen(context.Background(), verifex.AdverseMediaRequest{
    Entity:     "Acme Corporation",
    EntityType: "COMPANY",
})

fmt.Println(result.OverallRisk, result.ArticlesFlagged)

use verifex::{Verifex, AdverseMediaRequest};

let client = Verifex::new("vfx_your_api_key");

let result = client
    .adverse_media_screen(AdverseMediaRequest {
        entity: "Acme Corporation".into(),
        entity_type: "COMPANY".into(),
        ..Default::default()
    })
    .await?;

println!("{} — {} flagged", result.overall_risk, result.articles_flagged);