# CFPB Consumer Complaints - Company Complaint Profiles (`kdhan/cfpb-consumer-complaints`) Actor

Complaint profiles for US banks and lenders from the official CFPB Consumer Complaint Database: counts, top products and issues, company response types, timely-response rate and monthly trend, or the individual complaint list. No API key, no scraping.

- **URL**: https://apify.com/kdhan/cfpb-consumer-complaints.md
- **Developed by:** [Doohan Kim](https://apify.com/kdhan) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 cfpb complaint records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## 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 Complaints - Company Complaint Profiles

Look up how many consumer complaints a US bank, card issuer, lender, debt collector or credit
bureau has received, what they are about, how the company answered and how the volume moves month
by month. Data comes straight from the official **CFPB Consumer Complaint Database** open-data API.
No scraping, no API key.

Two modes:

- **summary** - one profile per company (counts, top products and issues, company response types,
  timely-response rate, top states, submission channels, monthly trend).
- **complaints** - the individual complaints, newest first (product, issue, dates, state, 3-digit ZIP
  prefix, company response, link to the CFPB page).

### Input

```json
{
  "companies": ["Wells Fargo", "Capital One"],
  "mode": "summary",
  "products": ["Mortgage"],
  "states": ["CA", "TX"],
  "dateFrom": "2025-01-01",
  "dateTo": "2025-12-31",
  "maxResults": 5
}
```

All fields are optional; with an empty input the Actor summarizes an example company (Wells Fargo)
over the last 12 months.

- `companies` - partial names, at least 3 characters. The text is matched against the company names
  CFPB uses (for example "wells fargo" finds `WELLS FARGO & COMPANY`; "chase" finds
  `JPMORGAN CHASE & CO.`). Names that contain your whole text come first. `matchType` tells you
  whether the match was the whole text (`phrase`) or all words (`words`).
- `products` - CFPB product names, case does not matter (a unique part of a name is enough).
  Use `Product•Sub-product` for a sub-product. Unknown names are rejected with the list of valid ones.
- `states` - the consumer's state, two letters.
- `dateFrom` / `dateTo` - the date CFPB received the complaint, both days included. If both are empty
  the last 12 calendar months (including the current one) are used and `period.defaultedToLast12Months`
  is `true`. If only `dateTo` is given there is no start limit (the monthly trend covers the last 60 months).
- `maxResults` - **per company name**. Summary mode: how many matching companies are summarized
  (1-25, default 5, most complaints first). Complaints mode: how many complaints are returned
  (1-10000, default 100, newest first).

### Output

#### Summary row (`type: company_summary`)

`company`, `complaintCount`, `period`, `filters`, `timelyResponse` (`yes`, `no`, `ratePct`),
`responseTypes[]`, `monetaryReliefPct`, `anyReliefPct` (monetary or non-monetary relief),
`topProducts[]`, `topIssues[]`, `topStates[]` (top 10 each, with `count` and `pct`),
`submittedVia[]`, `monthlyTrend[]` (`month`, `count`, `partialMonth` when the period starts or ends
mid-month), `dataAsOf`, `source`, `license`, `disclaimer`.

Notes on the numbers:

- `ratePct` is the share of complaints with a timely company response among those where CFPB records
  the answer. Complaints still `In progress` appear in `responseTypes` and in `complaintCount`.
- When you filter by product or state, the distribution of that dimension is counted value by value,
  because CFPB's own breakdown ignores its own filter (verified; a naive read would show all products).
- The monthly trend needs one request per month, so a 12-month summary takes about 15 requests.

#### Complaint row (`type: complaint`)

`complaintId`, `complaintUrl`, `company`, `dateReceived`, `dateSentToCompany`, `product`,
`subProduct`, `issue`, `subIssue`, `state`, `zip3`, `tags` (for example `Older American`,
`Servicemember`), `submittedVia`, `companyResponse`, `companyPublicResponse`, `timelyResponse`,
`dataAsOf`, `source`, `license`, `disclaimer`.

#### No silent failures

- A name that matches nothing is returned as `found: false` with a `reason` (not charged).
- If the CFPB API cannot be reached the row has `found: null`, an `error`, and says that this does
  **not** mean the company has no complaints (not charged).
- If only the monthly trend fails, the summary is still returned, `monthlyTrend` is `null` and
  `sectionErrors` explains why. If monthly counts do not add up to the total (data changed during
  the run) that is reported in `sectionErrors` too.

### Privacy warning

The database contains no consumer names or street addresses, and this Actor outputs only the state
and the **first three digits of the ZIP code**. The CFPB database can also publish consumers' free-text
narratives (CFPB removes personal information before publishing). **The public API currently returns
no narrative field at all, so this Actor outputs none.** If CFPB adds narratives, they will appear as
`narrative` exactly as published; free text can still contain personal identifiers that the scrubbing
missed, so do not try to identify or contact complainants, and treat any narrative as sensitive data.

### Important: what the numbers mean

Complaints are **consumer assertions, not verified facts or findings against the company.** CFPB
states: "This database is not a statistical sample of consumers' experiences in the marketplace and
these complaints are not necessarily representative of all consumers' experiences with a financial
product or company." and "When looking at complaint volume about a company or product, consider
company size and/or market share." Complaints referred to other regulators (for example about
depository institutions with less than $10 billion in assets) are not published. A low count does not
mean low harm. Do not use this data alone to make lending, hiring or legal decisions.

### Data source

CFPB Consumer Complaint Database search API
(`https://www.consumerfinance.gov/data-research/consumer-complaints/search/api/v1/`).
The API metadata and OpenAPI description state the license: **Creative Commons CC0**. The database is
updated about daily; `dataAsOf` is the API's `last_updated` value. This Actor is not affiliated with
or endorsed by the CFPB.

### Pricing

Pay-per-event, event name `cfpb-record` (one company summary or one complaint returned). Names that
are not found and error rows are not charged. The Actor respects your maximum cost per run.

### Limits

- Maximum 10 company names per run; 60 months of monthly trend; 10000 complaints per name.
- The CFPB site sits behind a firewall that blocks unknown client identifiers; if CFPB blocks the
  platform's network the rows come back with `found: null` and a clear error.

# Actor input Schema

## `companies` (type: `array`):

Partial company names, at least 3 characters, for example Wells Fargo or Capital One.

## `mode` (type: `string`):

summary = one profile per company. complaints = individual complaints, newest first.

## `products` (type: `array`):

CFPB product names, for example Mortgage or Checking or savings account.

## `states` (type: `array`):

Two-letter state codes of the consumer, for example CA or TX.

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

First day, YYYY-MM-DD. If both dates are empty the last 12 months are used.

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

Last day, YYYY-MM-DD, inclusive. Defaults to today.

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

Summary: companies summarized per name (1-25, default 5). Complaints: complaints per name (1-10000, default 100). Charged per record.

## Actor input object example

```json
{
  "companies": [
    "Wells Fargo"
  ],
  "mode": "summary"
}
```

# Actor output Schema

## `records` (type: `string`):

Company summaries or individual complaints with data freshness (dataAsOf) and disclaimer.

# 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 = {
    "companies": [
        "Wells Fargo"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdhan/cfpb-consumer-complaints").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 = { "companies": ["Wells Fargo"] }

# Run the Actor and wait for it to finish
run = client.actor("kdhan/cfpb-consumer-complaints").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 '{
  "companies": [
    "Wells Fargo"
  ]
}' |
apify call kdhan/cfpb-consumer-complaints --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdhan/cfpb-consumer-complaints"
        }
    }
}
```

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/pRyTO0GPx8aZYSFjA/builds/t7ECnOBoBR1Whi2FX/openapi.json