# CFPB Consumer Complaint Delta Monitor (`apex-nexus/cfpb-complaint-delta-monitor`) Actor

- **URL**: https://apify.com/apex-nexus/cfpb-complaint-delta-monitor.md
- **Developed by:** [Valunex](https://apify.com/apex-nexus) (community)
- **Stats:** 2 total users, 1 monthly users, 100.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/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CFPB Consumer Complaint Delta Monitor

Monitors the public CFPB Consumer Complaint Database API for a user-maintained
watchlist of companies / products / issues and emits one dataset item (alert)
per newly filed complaint matching the watchlist since the last run — "free
when nothing changes."

### Who it is for

Compliance, risk, market-research and consumer-advocacy teams that need to
track new complaints filed against specific financial companies, products or
issues. Instead of manually re-polling the CFPB complaint database on a
schedule, run this Actor on a cadence and it only alerts on what is new.

### What makes it different

Existing complaint monitors typically bill you on every scan even when nothing
changed. This Actor keeps a watchlist plus a per-watchlist checkpoint (last
checked `dateReceived` high-water mark plus a content fingerprint per
complaint ID) in the Apify default key-value store, so repeat runs emit only
genuinely new complaints matching the watchlist — a true recurring delta
monitor, free when nothing changes.

### Data source

Public CFPB Consumer Complaint Database — no API key, no login, no proxies.
CFPB states all complaint data it publishes is freely available for anyone to
use, analyze, and build on:

- https://www.consumerfinance.gov/data-research/consumer-complaints/search/api/v1/

No credentials, no proxies, no scraping of anti-bot pages, no commercial
inference (no LLMs) inside the product.

### Pricing (pay-per-event framing, Apify Store)

This is a **FREE listing** until the owner enables monetization and completes
payout/KYC. Pricing shown here is README framing only; no monetization is
flipped in this release candidate.

- **New-complaint alert (dataset item): per-alert price** — you pay only when
  the Actor emits a new complaint matching your watchlist.
- **Nothing-changed runs: free** (zero dataset items emitted).
- Actor start: standard Apify Actor start fee.

Apify retains a 20% commission on revenue; payouts are monthly and require
completed identity verification (KYC).

### Input

See `.actor/input_schema.json`. All fields optional; the default input is:

```json
{
  "watchlist": ["Wells Fargo", "Chase", "Citibank", "Bank of America", "Capital One"],
  "lookbackDays": 30,
  "maxResults": 25
}
```

- `watchlist`: optional array of company/product/issue strings matched
  case-insensitively against the company, product, sub-product, issue and
  sub-issue of each complaint. Empty means every complaint is in scope.
- `lookbackDays` (1-365, default 30): how far back to look on the first run;
  repeat runs only emit complaints newer than the last checked state.
- `maxResults` (1-200, default 25): cap on alerts emitted in a single run.

### Output

One dataset item per new complaint:

```json
{
  "complaintId": "31568254",
  "dateReceived": "2026-11-01T03:56:29.000Z",
  "product": "Credit reporting or other personal consumer reports",
  "subProduct": "Credit reporting",
  "issue": "Incorrect information on your report",
  "subIssue": "Information belongs to someone else",
  "company": "TRANSUNION INTERMEDIATE HOLDINGS, INC.",
  "state": "TX",
  "zipCode": "78237",
  "timely": "Yes",
  "companyResponse": "In progress",
  "newSinceLastRun": true,
  "changeType": "new",
  "watchlistMatched": null,
  "source": "https://www.consumerfinance.gov/data-research/consumer-complaints/search/api/v1/"
}
```

Every field is `null` when it could not be parsed from the CFPB API — the
Actor never guesses. `changeType` is `"new"` for a previously unseen
complaint ID.

### Checkpoint / delta behaviour

State (the last-checked `dateReceived` high-water mark plus a content
fingerprint per complaint ID) is kept in the Apify default key-value store.
On each run the Actor queries the CFPB API for complaints received on or
after the checkpoint, sorted newest first, deduplicates by complaint ID, and
only pushes previously unseen complaints matching the watchlist. Resetting
the store re-emits complaints within the lookback window.

### Limits

- Max 50 watchlist terms, 200 alerts per run, 365-day lookback.
- Up to 1,000 CFPB records scanned per run (per watchlist term, sorted
  newest first, stops at the checkpoint).
- Checkpoints persist per watchlist in the Actor key-value store.

### Verification

- `pytest actor/tests` — deterministic unit tests (no network): input
  normalization, watchlist matching, fingerprinting, delta scan, dedup.
- `ruff check actor/` — must be clean (0 errors).
- Default-input smoke run against the public CFPB API returns more than
  0 items in under 5 minutes (publish precondition).

# Actor input Schema

## `watchlist` (type: `array`):

Case-insensitive substring filter matched against the company, product, sub-product, issue and sub-issue of each complaint. Empty means every complaint is in scope.

## `lookbackDays` (type: `integer`):

How far back to look for complaints on the first run; repeat runs only emit complaints newer than the last checked state.

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

Cap the number of new complaints emitted in a single run.

## Actor input object example

```json
{
  "watchlist": [],
  "lookbackDays": 30,
  "maxResults": 25
}
```

# Actor output Schema

## `overview` (type: `string`):

Dataset items filtered by the overview view defined in the dataset schema.

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

All dataset items emitted by the Actor run (new complaints).

# 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 = {
    "watchlist": [],
    "lookbackDays": 30,
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("apex-nexus/cfpb-complaint-delta-monitor").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 = {
    "watchlist": [],
    "lookbackDays": 30,
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("apex-nexus/cfpb-complaint-delta-monitor").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "watchlist": [],
  "lookbackDays": 30,
  "maxResults": 25
}' |
apify call apex-nexus/cfpb-complaint-delta-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apex-nexus/cfpb-complaint-delta-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/poFFbqehE1uKVjstZ/builds/6VgYDcfVSYFrXSwKR/openapi.json