# CFPB Consumer Complaints Normalizer (`wakey7dev/cfpb-complaints-normalizer`) Actor

Search 16.8M+ CFPB complaints with company dedup, issue categorization, and severity scoring. Premium value-add over raw scrapers.

- **URL**: https://apify.com/wakey7dev/cfpb-complaints-normalizer.md
- **Developed by:** [Chris Wakefield](https://apify.com/wakey7dev) (community)
- **Categories:** Business
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

![Chris The Dev](https://raw.githubusercontent.com/chriswakefield87/appstore-screenshot-translator/main/assets/actor-banner.png)

## CFPB Consumer Complaints Normalizer 🔍

Search and normalize **16.8M+ consumer financial complaints** from the CFPB (Consumer Financial Protection Bureau) public database. Get cleaned, categorized, and scored complaint data with **AI-powered normalization** — company name deduplication, issue categorization, and severity scoring.

**No API key needed** — the CFPB database is completely free and public.

### ✨ What Makes This Different

Most CFPB scrapers give you raw data. This actor gives you **actionable intelligence**:

- 🏢 **Company Name Normalization** — "TRANSUNION INTERMEDIATE HOLDINGS, INC." → "TransUnion". 80+ company mappings covering banks, debt collectors, credit bureaus, and mortgage servicers.
- 🏷️ **Issue Categorization** — 178 raw issue types grouped into 15 high-level categories (Credit Report Errors, Debt Collection Harassment, Mortgage Servicing, etc.)
- 🔥 **Severity Scoring (0-100)** — Multi-signal scoring based on issue type, narrative presence, dispute status, and company response
- 📊 **Trend Analysis** — Top products, companies, issue categories, severity distribution, and response type breakdowns

### 📥 Input Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `searchQuery` | string | ✅ | Company name, product, or keyword to search |
| `product` | string | ❌ | Filter by product (e.g. "Credit reporting", "Debt collection") |
| `issue` | string | ❌ | Filter by specific issue type |
| `company` | string | ❌ | Filter by company name (exact CFPB name) |
| `state` | string | ❌ | Two-letter US state code (e.g. "CA", "TX") |
| `dateFrom` | string | ❌ | Start date YYYY-MM-DD |
| `dateTo` | string | ❌ | End date YYYY-MM-DD |
| `hasNarrative` | boolean | ❌ | Only complaints with written narratives |
| `maxResults` | integer | ❌ | Max complaints (1-1000, default 50) |
| `includeTrends` | boolean | ❌ | Compute trend analysis (default true) |

### 📤 Example Input

```json
{
  "searchQuery": "credit reporting",
  "product": "Credit reporting or other personal consumer reports",
  "company": "TRANSUNION INTERMEDIATE HOLDINGS, INC.",
  "hasNarrative": true,
  "maxResults": 50,
  "includeTrends": true
}
```

### 📊 Example Output

```
==========================================================================================
  CFPB CONSUMER COMPLAINTS — NORMALIZED RESULTS
==========================================================================================
  Search:        credit reporting
  Retrieved:     50 complaints
  With Narrative: 50 (100.0%)
  Consumer Disputed: 12 (24.0%)
  Timely Response: 96.0%

  Top Products                                  Count
  ──────────────────────────────────────────────────────
  Credit reporting or other personal consumer    50

  Top Issue Categories                          Count
  ──────────────────────────────────────────────────────
  Credit Report Errors                           28
  Dispute Handling                               15
  Credit Report Misuse                            7

  Severity Distribution                         Count
  ──────────────────────────────────────────────────────
  HIGH                                            18
  MEDIUM                                          24
  LOW                                              8

  Top Companies                                 Count
  ──────────────────────────────────────────────────────
  TransUnion                                      50

  Sample Complaints (first 5):
  ──────────────────────────────────────────────────────
   1. [2024-09-03] TransUnion               | Credit Report Misuse  | high
   2. [2024-08-28] TransUnion               | Credit Report Errors  | medium
   3. [2024-08-15] TransUnion               | Dispute Handling      | high
```

Each dataset item includes:

- `companyRaw` / `companyNormalized` — original and cleaned company names
- `issueCategory` — high-level issue grouping
- `severityScore` (0-100) / `severityLevel` (low/medium/high)
- All original fields: product, issue, date, state, response, narrative flag, disputed flag

### 🎯 Use Cases

- **Fintech Competitive Intelligence** — Track competitor complaint trends
- **Compliance & Risk** — Monitor systemic issues across financial institutions
- **Law Firms** — Identify class-action opportunities and patterns
- **Journalism** — Investigative reporting on consumer finance abuses
- **Consumer Advocacy** — Track complaint volumes by company, product, and state
- **AI/ML Training** — Clean, categorized datasets for NLP models

### 🔗 Data Source

[CFPB Consumer Complaint Database](https://www.consumerfinance.gov/data-research/consumer-complaints/) — Public domain, no API key required. Updated daily.

# Actor input Schema

## `searchQuery` (type: `string`):

Company name, product, or keyword to search for (e.g. 'Transunion', 'credit reporting', 'mortgage')

## `product` (type: `string`):

Filter by financial product (e.g. 'Credit reporting', 'Debt collection', 'Mortgage', 'Credit card', 'Student loan'). Leave empty to search all products.

## `issue` (type: `string`):

Filter by specific issue type. Leave empty for all issues.

## `company` (type: `string`):

Filter by company name exactly as it appears in CFPB database. Leave empty for all companies.

## `state` (type: `string`):

Two-letter US state code (e.g. 'CA', 'TX', 'FL'). Leave empty for all states.

## `dateFrom` (type: `string`):

Start date in YYYY-MM-DD format. Leave empty for all-time.

## `dateTo` (type: `string`):

End date in YYYY-MM-DD format. Leave empty for today.

## `hasNarrative` (type: `boolean`):

Only return complaints with written consumer narratives (more detail for analysis)

## `maxResults` (type: `integer`):

Maximum number of complaints to retrieve (1-1000)

## `includeTrends` (type: `boolean`):

Compute complaint volume trends, top issues, and company response statistics

## Actor input object example

```json
{
  "hasNarrative": false,
  "maxResults": 50,
  "includeTrends": true
}
```

# Actor output Schema

## `results` (type: `string`):

Full normalized complaint records as JSON dataset items.

## `summary` (type: `string`):

Human-readable summary table with key metrics.

## `stats` (type: `string`):

Machine-readable statistics for dashboards and workflows.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("wakey7dev/cfpb-complaints-normalizer").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("wakey7dev/cfpb-complaints-normalizer").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call wakey7dev/cfpb-complaints-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=wakey7dev/cfpb-complaints-normalizer",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/wxMzKQ9GkbWyBqK9x/builds/viaizfz3iVCg0rZF6/openapi.json