openapi: 3.0.0
info:
  version: 1.0.0
  title: Consumer Complaint Database API
  description: The API for searching the CFPB Consumer Complaint Database, which contains over 15 million consumer financial complaint records.
  termsOfService: 'https://cfpb.github.io/source-code-policy/'
  contact:
    name: Report API Issues
    url: https://github.com/cfpb/ccdb5-api/issues
  license:
    name: Creative Commons License CC0
    url: 'https://github.com/cfpb/ccdb5-api/blob/main/LICENSE'
servers:
  - url: 'https://www.consumerfinance.gov/data-research/consumer-complaints/search/api/v1/'
    description: Production server
tags:
  - name: Complaints
    description: These endpoints provide access to consumer complaints
  - name: Trends
    description: These endpoints provide access aggregated consumer complaint data
  - name: Typeahead
    description: These endpoints support the typeahead boxes in the UI
externalDocs:
  description: Additional API Information
  url: 'https://cfpb.github.io/api/ccdb/'
paths:
  /:
    get:
      tags:
        - Complaints
      summary: Search consumer complaints
      description: Search the contents of the consumer complaint database
      parameters:
        - $ref: '#/components/parameters/search_term'
        - $ref: '#/components/parameters/field'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/no_aggs'
        - $ref: '#/components/parameters/no_highlight'
        - $ref: '#/components/parameters/company'
        - $ref: '#/components/parameters/company_public_response'
        - $ref: '#/components/parameters/company_received_max'
        - $ref: '#/components/parameters/company_received_min'
        - $ref: '#/components/parameters/company_response'
        - $ref: '#/components/parameters/date_received_max'
        - $ref: '#/components/parameters/date_received_min'
        - $ref: '#/components/parameters/has_narrative'
        - $ref: '#/components/parameters/issue'
        - $ref: '#/components/parameters/product'
        - $ref: '#/components/parameters/search_after'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/submitted_via'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/timely'
        - $ref: '#/components/parameters/zip_code'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
            text/csv:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Invalid status value
  /_suggest:
    get:
      tags:
        - Typeahead
      summary: Suggest possible searches
      description: The endpoint for the main search box in the UI
      parameters:
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/suggest_text'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestResult'
        '400':
          description: Invalid input
  /_suggest_company:
    get:
      tags:
        - Typeahead
      summary: Suggest possible companies
      description: Provide a list of companies that match the input text
      parameters:
        - $ref: '#/components/parameters/suggest_text'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/company_public_response'
        - $ref: '#/components/parameters/company_received_max'
        - $ref: '#/components/parameters/company_received_min'
        - $ref: '#/components/parameters/company_response'
        - $ref: '#/components/parameters/date_received_max'
        - $ref: '#/components/parameters/date_received_min'
        - $ref: '#/components/parameters/has_narrative'
        - $ref: '#/components/parameters/issue'
        - $ref: '#/components/parameters/product'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/submitted_via'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/timely'
        - $ref: '#/components/parameters/zip_code'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestResult'
        '400':
          description: Invalid input
  /_suggest_zip:
    get:
      tags:
        - Typeahead
      summary: Suggest possible zip codes
      description: Provide a list of zip codes that match the input text
      parameters:
        - $ref: '#/components/parameters/suggest_text'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/company_public_response'
        - $ref: '#/components/parameters/company_received_max'
        - $ref: '#/components/parameters/company_received_min'
        - $ref: '#/components/parameters/company_response'
        - $ref: '#/components/parameters/date_received_max'
        - $ref: '#/components/parameters/date_received_min'
        - $ref: '#/components/parameters/has_narrative'
        - $ref: '#/components/parameters/issue'
        - $ref: '#/components/parameters/product'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/submitted_via'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/timely'
        - $ref: '#/components/parameters/zip_code'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestResult'
        '400':
          description: Invalid input
  '/{complaintId}':
    get:
      tags:
        - Complaints
      summary: Find consumer complaint by ID
      description: Get complaint details for a specific ID
      parameters:
        - name: complaintId
          in: path
          description: ID of the complaint
          required: true
          schema:
            type: integer
            format: int64
            minimum: 0
            maximum: 9999999999
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Complaint'
        '400':
          description: Invalid ID supplied
        '404':
          description: Complaint not found
  /geo/states:
    get:
      tags:
        - Complaints
      summary: Get the state-by-state information
      description: Get complaint information broken down by states
      parameters:
        - $ref: '#/components/parameters/search_term'
        - $ref: '#/components/parameters/field'
        - $ref: '#/components/parameters/company'
        - $ref: '#/components/parameters/company_public_response'
        - $ref: '#/components/parameters/company_received_max'
        - $ref: '#/components/parameters/company_received_min'
        - $ref: '#/components/parameters/company_response'
        - $ref: '#/components/parameters/date_received_max'
        - $ref: '#/components/parameters/date_received_min'
        - $ref: '#/components/parameters/has_narrative'
        - $ref: '#/components/parameters/issue'
        - $ref: '#/components/parameters/product'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/submitted_via'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/timely'
        - $ref: '#/components/parameters/zip_code'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatesResult'
  /trends:
    get:
      tags:
        - Trends
      summary: List trends
      description: Return specific aggregations for a search
      parameters:
        - $ref: '#/components/parameters/search_term'
        - $ref: '#/components/parameters/field'
        - $ref: '#/components/parameters/company'
        - $ref: '#/components/parameters/company_public_response'
        - $ref: '#/components/parameters/company_received_max'
        - $ref: '#/components/parameters/company_received_min'
        - $ref: '#/components/parameters/company_response'
        - $ref: '#/components/parameters/date_received_max'
        - $ref: '#/components/parameters/date_received_min'
        - $ref: '#/components/parameters/focus'
        - $ref: '#/components/parameters/has_narrative'
        - $ref: '#/components/parameters/issue'
        - $ref: '#/components/parameters/lens'
        - $ref: '#/components/parameters/product'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/submitted_via'
        - $ref: '#/components/parameters/sub_lens'
        - $ref: '#/components/parameters/sub_lens_depth'
        - $ref: '#/components/parameters/tags'
        - $ref: '#/components/parameters/timely'
        - $ref: '#/components/parameters/trend_depth'
        - $ref: '#/components/parameters/trend_interval'
        - $ref: '#/components/parameters/zip_code'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendsResult'
            text/csv:
              schema:
                $ref: '#/components/schemas/TrendsResult'
        '400':
          description: Invalid status value
security: []
components:
  parameters:
    company:
      name: company
      in: query
      description: Filter the results to only return these companies
      explode: true
      schema:
        type: array
        items:
          type: string
    company_public_response:
      name: company_public_response
      in: query
      description: Filter the results to only return these types of public response by the company
      explode: true
      schema:
        type: array
        items:
          type: string
    company_received_max:
      name: company_received_max
      in: query
      description: Return results with date < company_received_max (i.e. 2017-03-04)
      schema:
        type: string
        format: date
    company_received_min:
      name: company_received_min
      in: query
      description: Return results with date >= company_received_min (i.e. 2017-03-04)
      schema:
        type: string
        format: date
    company_response:
      name: company_response
      in: query
      description: Filter the results to only return these types of response by the company
      explode: true
      schema:
        type: array
        items:
          type: string
    date_received_max:
      name: date_received_max
      in: query
      description: Return results with date < date_received_max (i.e. 2017-03-04)
      schema:
        type: string
        format: date
    date_received_min:
      name: date_received_min
      in: query
      description: Return results with date >= date_received_min (i.e. 2017-03-04)
      schema:
        type: string
        format: date
    field:
      name: field
      in: query
      description: If the parameter "search_term" has a value, use "field" to specify which field is searched. If not specified, "complaint_what_happened" will be searched.
      schema:
        type: string
        enum:
          - complaint_what_happened
          - company_public_response
          - all
        default: complaint_what_happened
    focus:
      name: focus
      in: query
      description: The name of the product or company on which to focus charts for products and issues
      explode: true
      schema:
        type: array
        items:
          type: string
    format:
      name: format
      in: query
      description: Format to be returned, if this parameter is not specified, frm/size parameters can be used properly, but if a format is specified for exporting, frm/size will be ignored
      schema:
        type: string
        enum:
          - json
          - csv
        default: json
    from:
      name: frm
      in: query
      description: Return results starting from a specific index, only if format parameter is not specified, ignore otherwise
      schema:
        type: integer
        format: int64
        minimum: 1
        maximum: 100000
        default: 0
    has_narrative:
      name: has_narrative
      in: query
      description: Filter the results to only return the specified state of whether it has narrative in the complaint or not, i.e. yes, no
      explode: true
      schema:
        type: array
        items:
          type: string
    issue:
      name: issue
      in: query
      description: "Filter the results to only return these types of issue and subissue, i.e. product-only: Getting a Loan, subproduct needs to include product, separated by '•', Getting a Loan•Can't qualify for a loan"
      explode: true
      schema:
        type: array
        items:
          type: string
    lens:
      name: lens
      in: query
      required: true
      description: The data lens through which to view complaint trends over time.
      schema:
        type: string
        enum:
          - overview
          - issue
          - product
          - tags
        default: overview
    no_aggs:
      name: no_aggs
      in: query
      description: Include aggregations in result or not, True means no aggregations will be included, False means aggregations will be included.
      schema:
        type: boolean
        default: false
    no_highlight:
      name: no_highlight
      in: query
      description: Include highlight of search term in result or not, True means no highlighting will be included, False means highlighting will be included.
      schema:
        type: boolean
        default: false
    product:
      name: product
      in: query
      description: "Filter the results to only return these types of product and subproduct, i.e. product-only: Mortgage, subproduct needs to include product, separated by '•', Mortgage•FHA mortgage"
      explode: true
      schema:
        type: array
        items:
          type: string
    search_after:
      name: search_after
      in: query
      description: Used in conjunction with frm parameter to paginate results.
      schema:
        type: string
    search_term:
      name: search_term
      in: query
      description: Return results containing specific term
      schema:
        type: string
    size:
      name: size
      in: query
      description: Limit the size of the results
      schema:
        type: integer
        format: int64
        minimum: 1
        maximum: 100
        default: 10
    sort:
      name: sort
      in: query
      description: Return results sort in a particular order
      schema:
        type: string
        enum:
          - relevance_desc
          - relevance_asc
          - created_date_desc
          - created_date_asc
        default: relevance_desc
    state:
      name: state
      in: query
      description: Filter the results to only return these states (use abbreviation, i.e. CA, VA)
      explode: true
      schema:
        type: array
        items:
          type: string
    sub_lens:
      name: sub_lens
      in: query
      description: The sub-lens through which to view complaint trends over time.
      schema:
        type: string
        enum:
          - issue
          - product
          - sub_product
          - sub_issue
          - tags
    sub_lens_depth:
      name: sub_lens_depth
      in: query
      description: The top X trend sub aggregations will be returned, where X is the supplied sub_lens_depth.
      schema:
        type: integer
        maximum: 10000000
        minimum: 5
        format: int64
        default: 10
    submitted_via:
      name: submitted_via
      in: query
      description: Filter the results to only return these types of way consumers submitted their complaints
      explode: true
      schema:
        type: array
        items:
          type: string
    suggest_text:
      name: text
      in: query
      description: text to use for suggestions
      required: true
      schema:
        type: string
    tags:
      name: tags
      in: query
      description: Filter the results to only return these types of tag
      explode: true
      schema:
        type: array
        items:
          type: string
    timely:
      name: timely
      in: query
      description: Filter the results to show whether a response was timely
      explode: true
      schema:
        type: array
        items:
          type: string
    trend_depth:
      name: trend_depth
      in: query
      description: The top X trend aggregations will be returned, where X is the supplied trend_depth.
      schema:
        type: integer
        maximum: 10000000
        minimum: 5
        format: int64
        default: 10
    trend_interval:
      name: trend_interval
      in: query
      description: The interval of time to use for trends aggregations histograms.
      required: true
      schema:
        type: string
        enum:
          - year
          - quarter
          - month
          - week
          - day
    zip_code:
      name: zip_code
      in: query
      description: Filter the results to only return these zip codes
      explode: true
      schema:
        type: array
        items:
          type: string
  schemas:
    Aggregation:
      type: object
      description: An OpenSearch aggregation
      properties:
        doc_count:
          type: integer
          description: The total number of complaints covered in this aggregation
        field:
          type: object
          description: The name of the field being aggregated
          properties:
            buckets:
              type: array
              items:
                $ref: '#/components/schemas/Bucket'
            doc_count_error_upper_bound:
              type: integer
              description: The number of possible errors that occurred when searching the shards
            sum_other_doc_count:
              type: integer
              description: The number of complaints that were not included in this aggregation.
    AggregationDate:
      type: object
      properties:
        value_as_string:
          type: string
          format: date-time
          description: ISO-8601 formatted date (yyyy-mm-ddTHH:MM:SSZZ)
        value:
          type: number
          description: Seconds since 1970 (Unix Epoch)
    Bucket:
      type: object
      properties:
        doc_count:
          type: integer
          description: The number of complaints that match this key
        key:
          type: string
    Complaint:
      type: object
      externalDocs:
        description: Official documentation
        url: 'https://cfpb.github.io/api/ccdb/fields.html'
      properties:
        company:
          type: string
          description: The complaint is about this company
        company_public_response:
          type: string
          description: The company's optional, public-facing response to a consumer's complaint
        company_response:
          type: string
          description: The response from the company about this complaint
        complaint_id:
          type: integer
          description: The unique identification number for a complaint
        complaint_what_happened:
          type: string
          description: A description of the complaint provided by the consumer
        date_received:
          type: string
          format: date
          description: The date the CFPB received the complaint
        date_sent_to_company:
          type: string
          description: The date the CFPB sent the complaint to the company
        has_narrative:
          type: boolean
          description: Indicates this complaint has a narrative
        issue:
          type: string
          description: The issue the consumer identified in the complaint
        product:
          type: string
          description: The type of product the consumer identified in the complaint
        state:
          type: string
          description: The state of the mailing address provided by the consumer
        sub_issue:
          type: string
          description: The sub-issue the consumer identified in the complaint
        sub_product:
          type: string
          description: The type of sub-product the consumer identified in the complaint
        submitted_via:
          type: string
          description: How the complaint was submitted to the CFPB
        tags:
          type: string
          description: Data that supports easier searching and sorting of complaints
        timely:
          type: string
          description: Indicates whether the company gave a timely response or not
        zip_code:
          type: string
          description: The mailing ZIP code provided by the consumer
    Hit:
      type: object
      description: A single OpenSearch result
      properties:
        _source:
          $ref: '#/components/schemas/Complaint'
    Hits:
      type: object
      description: A set of complaints that matched the query
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
        max_score:
          type: number
          description: The highest score in the results
          format: float
        total:
          type: object
          properties:
            value:
              type: integer
              description: The count of matching hits
            relation:
              type: string
              description: Indicates the accuracy of the response (eq or gte)
    Meta:
      type: object
      properties:
        break_points:
          type: object
          description: Contains key value pairs of page and arrays. Used to paginate OpenSearch results in list view
        has_data_issue:
          type: boolean
          description: Indicates there has been an issue with the most recent data load
        is_data_stale:
          type: boolean
          description: Indicates the most recent data is over 5 business days old
        is_narrative_stale:
          type: boolean
          description: Indicates the most recent narratives are over 5 business days old
        last_indexed:
          type: string
          format: date-time
          description: The timestamp of the most recently indexed complaint
        last_updated:
          type: string
          format: date-time
          description: The timestamp of the most recent complaint
        license:
          type: string
          description: The open source license under which the API operates
        total_record_count:
          type: integer
          description: The total number of complaints currently indexed
    MultiLevelAggregation:
      type: object
      properties:
        doc_count:
          type: integer
          description: The total number of complaints covered in this aggregation
        field:
          type: object
          description: The name of the field being aggregated
          properties:
            buckets:
              type: array
              items:
                $ref: '#/components/schemas/MultiLevelBucket'
            doc_count_error_upper_bound:
              type: integer
              description: The number of possible errors that occurred when searching the shards
            sum_other_doc_count:
              type: integer
              description: The number of complaints that were not included in this aggregation.
    MultiLevelBucket:
      type: object
      properties:
        doc_count:
          type: integer
          description: The number of complaints that match this key
        key:
          type: string
    SearchResult:
      type: object
      properties:
        _meta:
          $ref: '#/components/schemas/Meta'
        aggregations:
          type: object
          properties:
            company_public_response:
              $ref: '#/components/schemas/Aggregation'
            company_response:
              $ref: '#/components/schemas/Aggregation'
            has_narrative:
              $ref: '#/components/schemas/Aggregation'
            issue:
              $ref: '#/components/schemas/MultiLevelAggregation'
            product:
              $ref: '#/components/schemas/MultiLevelAggregation'
            state:
              $ref: '#/components/schemas/Aggregation'
            submitted_via:
              $ref: '#/components/schemas/Aggregation'
            tags:
              $ref: '#/components/schemas/Aggregation'
            timely:
              $ref: '#/components/schemas/Aggregation'
            zip_code:
              $ref: '#/components/schemas/Aggregation'
        hits:
          $ref: '#/components/schemas/Hits'
    StatesResult:
      type: object
      properties:
        aggregations:
          type: object
          properties:
            issue:
              $ref: '#/components/schemas/MultiLevelAggregation'
            product:
              $ref: '#/components/schemas/MultiLevelAggregation'
            state:
              $ref: '#/components/schemas/MultiLevelAggregation'
    SuggestResult:
      type: array
      items:
        type: string
    TrendsResult:
      type: object
      properties:
        aggregations:
          type: object
          properties:
            company:
              $ref: '#/components/schemas/MultiLevelAggregation'
            issue:
              $ref: '#/components/schemas/MultiLevelAggregation'
            product:
              $ref: '#/components/schemas/MultiLevelAggregation'
            sub_issue:
              $ref: '#/components/schemas/MultiLevelAggregation'
            sub_product:
              $ref: '#/components/schemas/MultiLevelAggregation'
            tags:
              $ref: '#/components/schemas/MultiLevelAggregation'