An official website of the United States Government Español

Technical documentation

Heads up: Technical changes are in the works

We’re developing an open source public data platform which will serve the Consumer Complaint Database in the future. That means the API will change over time. Check it out and contribute.

What is this data?

The Consumer Complaint Database contains complaints we’ve received about financial products and services. It has complaints about:
  • Bank accounts or services
  • Consumer loans
  • Credit cards
  • Credit reporting
  • Debt collection
  • Money transfers
  • Mortgages
  • Private student loans
We list complaints in the database when the company responds to the complaints, which confirms a relationship with the consumer, or after the company has had the complaint for 15 calendar days, whichever comes first. Complaints can be removed if they do not meet all of the publication criteria defined in our policy statement. In addition, we exclude any complaints that:
  • Are missing critical information such as company or product,
  • Have been referred to other agencies,
  • Are duplicative, and/or
  • Identify the incorrect company.
Data is refreshed nightly to include new complaints and update existing ones.

Release notes

Release 7 APRIL 2014
This release includes complaints received after March 12, 2014, when the Bureau's case management system was upgraded. It also includes updates to older complaints that have happened since that date.
Release 6 DECEMBER 2013
This release reflects changes to the consumer complaint form:
  • The issues consumers can select on the student loan complaint form were revised. “Repaying your loan” and “Problems when you are unable to pay” were removed and “Can’t pay my loan” and “Dealing with my lender or servicer” were added.
  • Consumers can now select a sub-issue for student loan complaints.
  • Consumers can now submit a credit reporting complaint about the issues “Incorrect information on my credit report” and “Credit reporting company’s investigation” without first filing a dispute with the credit reporting company.
Complaints we receive beginning December 18, 2013 will reflect these changes as they appear in the database. Complaints received before then will remain unchanged.
Release 5 NOVEMBER 2013
This release expands the database to include complaints we’ve received about debt collection dating back to July 10, 2013. Additionally, consumer-reported ZIP codes for areas with populations of 20,000 or fewer persons are no longer included in the database.
Release 4 MAY 2013
This release expands the database to include complaints we’ve received about credit reporting dating back to October 22, 2012 and about money transfers dating back to April 4, 2013. It also adds the Sub-issue and State data fields. More information on the newly added fields can be found in the Field Reference, below.
Release 3 MARCH 2013
This release expanded the database to include complaints we’ve received related to mortgages dating back to December 1, 2011 and bank accounts and services, private student loans, and other consumer loans dating back to March 1, 2012. It also added the Sub-product data field.
Release 2 OCTOBER 2012
This release expanded the database to include credit card complaints dating back to December 1, 2011.
Release 1JUNE 2012
This release included complaints about credit cards received on or after June 1, 2012.

Field reference

The following fields are currently included in the database.
Field name Description Data Type Notes
Complaint ID The unique identification number for a complaint number
Product The type of product the consumer identified in the complaint plain text This field is a categorical variable.
Sub-product The type of sub-product the consumer identified in the complaint plain text This field is a categorical variable. Not all Products have Sub-products.
Issue The issue the consumer identified in the complaint plain text This field is a categorical variable. Possible values are dependent on Product. On December 18, 2013 the issues for student loan complaints were revised. “Repaying your loan” and “Problems when you are unable to pay” were removed and “Can’t pay my loan” and “Dealing with my lender or servicer” were added. Complaints received beginning on that date reflect this change. Complaints received before that date remain unchanged.
Sub-issue The sub-issue the consumer identified in the complaint plain text This field is a categorical variable. Possible values are dependent on product and issue. Not all Issues have corresponding Sub-issues. On December 18, 2013, sub-issues were added for student loan complaints. Previously, sub-issues were not used for this type of complaint. Complaints received beginning on that date reflect this change. Complaints received before that date remain unchanged.
ZIP code The consumer’s reported mailing ZIP code for the complaint plain text Includes only the first five digits and is blank for complaints submitted with non-numeric values. Excludes ZIP codes for areas with populations of 20,000 or fewer persons. In some instances, the consumer-submitted ZIP code and State fields may not match.
Submitted via How the complaint was submitted to CFPB plain text This field is a categorical variable.
State The consumer’s reported mailing state for the complaint plain text This field is a categorical variable.
Date received The date the CFPB received the complaint date & time
Date sent to company The date the CFPB sent the complaint to the company date & time
Company The complaint is about this company plain text This field is a categorical variable.
Company response This is how the company responded to the complaint plain text This field is a categorical variable.
Timely response? Whether the company gave a timely response plain text yes/no
Consumer disputed? Whether the consumer disputed the company’s response plain text yes/no

API documentation

The Consumer Complaint Database API is a suite of RESTful commands you can use to read and filter data from the database using scripts. It is built on the Socrata Open Data API (SODA), and users of other APIs built on this technology will find it familiar.

End point and authentication

The Consumer Complaint Database API provides a single end point (location for accessing the data) and does not require authentication.
End Point: http://data.consumerfinance.gov/api/views

Basic query

For users already comfortable using APIs, here is an example of a simple search query using the UNIX cURL command:
> curl "https://data.consumerfinance.gov/api/views/25ei-6bcr/rows.json?search=1"
{
  "meta" : {
    "view" : {
      "id" : "25ei-6bcr",
      "name" : "Credit Card Complaints",
      "averageRating" : 0,
      "createdAt" : 1337199939,
      ...
      "flags" : [ "default” ]
    }
  },
  "data" : [ ... ]
}

Dataset and views

The Consumer Complaint Database consists of a single Dataset -- the equivalent of a single database table or Excel worksheet. It also provides a number of persistent Views of the dataset, providing filtered slices of the data for targeted analysis.

Structure of a view

In addition to the complaint data, a View includes all of the metadata describing the View itself. The metadata include descriptive values such as name, description, and tags, as well as structural data like the ViewColumns it contains and any SortBys or ViewFilters that have been specified. Here are the fields included in a View.
Field Field Type Description
columns ViewColumn[] List of columns that are included
description string Description for this view
displayType string The type of display used by this view (e.g. map, table, line chart etc)
downloadCount integer The number of times this view has been downloaded
flags string[] An array of flags which will include any of the following that apply to this View: default This view is a dataset from which other views can be derived shared This view has been shared to the current user
grants Grant[] The visible permissions on this view
id string A unique ID for this view
name string The name for this view
owner User The User who created this this view
rights string[] The effective rights the user has on this view
rowsUpdatedAt datetime The last time data in this view was updated, including changes to the underlying table
rowsUpdatedBy string The ID of the user who last edited this table
searchString string The full text search string that defines this filtered view
tableId integer The ID of the parent dataset for this view
tags string[] An array of owner-specified tags for this view
userTags UserTag[] An array of user-specified tags for this view
viewCount integer The number of times this view has been opened
viewType string The type of the underlying dataset

API calls

You can retrieve metadata about the dataset and views, as well as query for views that match given search criteria. You can also retrieve specific rows of data from the dataset and views.
End Point Request Purpose Parameters
/api/viewsGETQuery for views that match a given set of criteria. The resulting output will include summary information about the views that matched your query. Additional query parameters restrict the search further (as a boolean "AND"). category (string): Filters for views matching this category name (string): Filters for views containing this text in their name description (string): Filters for views with this text in their description tags (string): Filters for views matching these tags full (string): Filters for views with this text in the metadata or content count (boolean): Executes the query with the given parameters and only returns the total number of rows, and ignores the limit parameter limit (integer): Total number of results to return, up to 200 at a time page (integer): Page number to retrieve additional pages of results
/api/views/(view ID) GET Retrieve a specific view by ID. view ID (string): (required) The ID of the view to retrieve
/api/views/(view ID)/columns GET List all of the columns in a view. view ID (string): (required) The view ID
/api/views/(view ID)/columns/(column ID) GET Retrieve details about a particular column. view ID (string): (required) The view ID column ID (integer): (required) The ID of the column to retrieve
/api/views/(view ID)/rows GET Retrieve multiple rows from a view as nested arrays instead of in the expanded form. By default this will return all the rows in the view, but you can limit the number of rows returned with max_rows or request only specific rows using ids. You can also request only row IDs by passing row_ids_only. view ID (string): (required) The ID of the view that contains the row row_ids_only (boolean): If true, the service will only return row IDs max_rows (integer): Limit the number of rows returned include_ids_after (integer): Include this number of rows, after which only row IDs are returned. search (string): Run a full text search on the view and only return rows/ids that match meta (boolean): If set to 'true', will write the view object. Only valid if rendering JSON. Default is true. as_hashes (boolean): If set to 'true', write fields in hash format. Otherwise, write fields in array. Only valid if rendering JSON. Default to false (array). exclude_system_fields (boolean): If set to 'true', do not return system fields like row id. Only valid if rendering JSON. Default to false. unwrapped (boolean): If set to 'true', return just array or rows with no outer object. Only valid if rendering JSON. Default to false. most_recent (boolean): If set to 'true', return only the most recent rows added to the dataset. Only valid if rendering RSS. Default to true. access_type (AccessChannel): valid values are PRINT, EMAIL, API, RSS, WIDGET, DOWNLOAD, WEBSITE
/api/views/(view ID)/rows/(row ID) GET Retrieve the expanded representation of a particular row by ID. You must have read permissions on the view in order to access this resource. view ID (string): (required) The ID of the view that contains the row row ID (string): (required) The ID of the row to retrieve
/api/views?method=get NoConditional GET Retrieve a specific view by ID. Does not return a 304. view ID (string): (required) The ID of the view to retrieve

More information

Socrata provides a number of resources for users of SODA APIs like the Consumer Complaint Database API. Code samples and other examples are available at http://github.com/socrata