> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumer Finance Complaints

> Count the consumer complaints filed about a financial company, with what they are about, how the company answered and the newest ones.

Given a financial company's name, return how many complaints consumers have filed about it with the US Consumer Financial Protection Bureau, the five largest groups by product and by how the company answered, and the newest complaints. Use it to check a bank, lender, card issuer or credit bureau before dealing with it. Complaints are consumers' reports, not findings. The source matches the name as text, so similarly named companies can appear: `companies` lists the five most matched names with their counts and every complaint carries the company name the source holds. `since` (YYYY-MM-DD) counts only complaints received on or after that date and `limit` sets how many complaints are returned (1 to 25, default 10). A name with no complaint is a completed result with a total of 0 and empty lists.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="company_name" type="string" required>
  The financial company's name, 2 to 100 characters, for example Wells Fargo. 2 to 100 characters.
</ParamField>

<ParamField body="since" type="string">
  Count only complaints received on or after this date, YYYY-MM-DD; default all. Use YYYY-MM-DD.
</ParamField>

<ParamField body="limit" type="integer">
  Most complaints to return, newest first, 1 to 25; default 10. From 1 to 25. Defaults to `10`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `company_consumer_complaints`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US Consumer Financial Protection Bureau`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="number">
  Complaints matching the name (and `since`, when given).
</ResponseField>

<ResponseField name="data.result.companies" type="object[]">
  The five most matched company names, so the caller can see whether the name was ambiguous.
</ResponseField>

<ResponseField name="data.result.companies[].name" type="string">
  The company name as the source holds it.
</ResponseField>

<ResponseField name="data.result.companies[].count" type="number">
  Count.
</ResponseField>

<ResponseField name="data.result.by_product" type="object[]">
  The five largest groups by financial product.
</ResponseField>

<ResponseField name="data.result.by_product[].name" type="string">
  Name.
</ResponseField>

<ResponseField name="data.result.by_product[].count" type="number">
  Count.
</ResponseField>

<ResponseField name="data.result.by_response" type="object[]">
  The five largest groups by how the company answered.
</ResponseField>

<ResponseField name="data.result.by_response[].name" type="string">
  Name.
</ResponseField>

<ResponseField name="data.result.by_response[].count" type="number">
  Count.
</ResponseField>

<ResponseField name="data.result.complaints" type="object[]">
  The newest complaints first.
</ResponseField>

<ResponseField name="data.result.complaints[].id" type="string">
  The source's complaint id. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].company" type="string">
  The company name as the source holds it. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].product" type="string">
  Product. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].sub_product" type="string">
  Sub product. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].issue" type="string">
  Issue. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].sub_issue" type="string">
  Sub issue. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].state" type="string">
  US state of the consumer. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].received_on" type="string">
  Date the source received the complaint, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].response" type="string">
  How the company answered, for example Closed with explanation. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].public_response" type="string">
  The company's public statement, when it gave one. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.complaints[].timely" type="boolean">
  True when the company answered within the time allowed.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-consumer-complaints \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "company_name": "Wells Fargo",
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-consumer-complaints", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "company_name": "Wells Fargo",
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/company-consumer-complaints', {
    company_name: 'Wells Fargo',
    limit: 1
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "company_consumer_complaints",
      "result": {
        "total": 176252,
        "companies": [
          {
            "name": "WELLS FARGO & COMPANY",
            "count": 176252
          }
        ],
        "by_product": [
          {
            "name": "Mortgage",
            "count": 49852
          }
        ],
        "by_response": [
          {
            "name": "Closed with explanation",
            "count": 139770
          }
        ],
        "complaints": [
          {
            "id": "29372201",
            "company": "WELLS FARGO & COMPANY",
            "product": "Credit reporting or other personal consumer reports",
            "sub_product": "Other personal consumer report",
            "issue": "Identity theft protection or other monitoring services",
            "sub_issue": "Problem canceling credit monitoring or identify theft protection service",
            "state": "CA",
            "received_on": "2026-10-07",
            "response": "Closed with explanation",
            "public_response": "Company has responded to the consumer and the CFPB and chooses not to provide a public response",
            "timely": true
          }
        ]
      },
      "evidence": {
        "source": "US Consumer Financial Protection Bureau",
        "source_kind": "public",
        "retrieved_at": "2026-10-13T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.