openapi: 3.0.0
info:
  description: API to serve banking industry data to the public.
  version: 0.1.0
  title: FDIC Bank Data API (Beta) Demographics Structure API
  contact:
    email: PublicDataFeedback@fdic.gov
servers:
- description: API to serve banking industry data to the public.
  url: /banks
tags:
- name: Structure
  description: Financial institution demographic and location information
paths:
  /institutions:
    get:
      tags:
      - Structure
      security:
      - ApiKeyAuth: []
      summary: Get Financial Institutions
      operationId: searchInstitutions
      description: Returns a list of financial institutions.
      parameters:
      - in: query
        name: api_key
        description: Api key used for api.fdic.gov
        required: false
        schema:
          type: string
      - in: query
        name: filters
        description: "The filter for the bank search. All values must be entered in UPPERCASE.\nExamples:\n* Filter by State name  \n`STNAME:\"West Virginia\"`    \n* Filter for any one of multiple State names  \n`STNAME:(\"West Virginia\",\"Delaware\")`\n* Filter all but a specified value  \n`!(STNAME:\"Virginia\")`  \n* Filter by last updated within an inclusive date range  \n`DATEUPDT:[\"2010-01-01\" TO \"2010-12-31\"]`\n* Filter for deposits over 50,000,000 (50000 thousands of dollars)  \n`DEP:[50000 TO *]`\n"
        required: false
        example: STALP:IA AND ACTIVE:1
        schema:
          type: string
      - in: query
        name: search
        description: "Flexible text search against institution records - currently only supporting name search. \nSearch supports text search and fuzzy matching, as opposed to filters that are exact matches. All values must be entered in UPPERCASE.\nExamples:\n* Search by name\n`NAME: Island`\n* Search by name (fuzzy match)\n`NAME: Iland`\n"
        required: false
        schema:
          type: string
      - in: query
        name: fields
        description: Comma delimited list of fields to search. All values must be entered in UPPERCASE.
        required: false
        example: ZIP,OFFDOM,CITY,COUNTY,STNAME,STALP,NAME,ACTIVE,CERT,CBSA,ASSET,NETINC,DEP,DEPDOM,ROE,ROA,DATEUPDT,OFFICES
        schema:
          type: string
      - in: query
        name: sort_by
        description: Field name by which to sort returned data. All values must be entered in UPPERCASE.
        required: false
        example: OFFICES
        schema:
          type: string
          default: NAME
      - in: query
        name: sort_order
        description: Indicator if ascending (ASC) or descending (DESC). All values must be entered in UPPERCASE.
        required: false
        example: DESC
        schema:
          type: string
          default: ASC
      - in: query
        name: limit
        description: The number of records to return. Default is 10 and maximum is 10,000.
        required: false
        example: 10
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 10
      - in: query
        name: offset
        description: The offset of page to return.
        required: false
        example: 0
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/fileFormat'
      - $ref: '#/components/parameters/fileDownload'
      - $ref: '#/components/parameters/fileName'
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/metadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/institution'
            text/csv:
              schema:
                type: string
                format: csv
        '400':
          description: bad input parameter
  /locations:
    get:
      tags:
      - Structure
      security:
      - ApiKeyAuth: []
      summary: Get Institution Locations
      operationId: searchLocations
      description: Returns locations/branches of financial institutions.
      parameters:
      - in: query
        name: api_key
        description: Api key used for api.fdic.gov
        required: false
        schema:
          type: string
      - in: query
        name: filters
        description: The filter for the location search. All values must be entered in UPPERCASE.
        examples:
          statename:
            value: STNAME:"West Virginia"
            summary: Filter by state name
          statenames:
            value: STNAME:("West Virginia","Delaware")
            summary: Filter by multiple State names
          twofields:
            value: STNAME:Oregon AND SERVTYPE:11
            summary: Filter by two fields
          daterange:
            value: RUNDATE:["2015-01-01" TO "2015-01-06"]
            summary: Filter by last updated within an inclusive date range
          numberrange:
            value: OFFNUM:[0 TO 10]
            summary: Filter by Locations where the office number is between 0 and 10
        required: false
        schema:
          type: string
      - in: query
        name: fields
        description: Comma delimited list of fields to return. All values must be entered in UPPERCASE.
        required: false
        example: NAME,UNINUM,SERVTYPE,RUNDATE,CITY,STNAME,ZIP,COUNTY
        schema:
          type: string
      - in: query
        name: sort_by
        description: Field name by which to sort returned data. All values must be entered in UPPERCASE.
        required: false
        example: NAME
        schema:
          type: string
          default: NAME
      - in: query
        name: sort_order
        description: Indicator if ascending (ASC) or descending (DESC). All values must be entered in UPPERCASE.
        required: false
        example: DESC
        schema:
          type: string
          default: ASC
      - in: query
        name: limit
        description: The number of records to return. Default is 10 and maximum is 10,000.
        required: false
        example: 10
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 10
      - in: query
        name: offset
        description: The offset of page to return.
        required: false
        example: 0
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/fileFormat'
      - $ref: '#/components/parameters/fileDownload'
      - $ref: '#/components/parameters/fileName'
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/metadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/location'
            text/csv:
              schema:
                type: string
                format: csv
        '400':
          description: bad input parameter
components:
  schemas:
    institution:
      type: object
      allOf:
      - $ref: institution_properties.yaml
    location:
      type: object
      allOf:
      - $ref: location_properties.yaml
    metadata:
      type: object
      properties:
        total:
          type: integer
          description: Total query result count
        parameters:
          type: object
          description: Query parameters supplied
        index:
          type: object
          properties:
            name:
              type: string
              description: name of index used to retrieve data
            createTimestamp:
              type: string
              format: date-time
              description: date/time index was created
  parameters:
    fileName:
      in: query
      name: filename
      description: The filename to use when downloading data.
      required: false
      example: data_file
      schema:
        type: string
    fileDownload:
      in: query
      name: download
      description: Whether the data should be downloaded as a file.
      required: false
      example: false
      schema:
        type: boolean
        enum:
        - false
        - true
    fileFormat:
      in: query
      name: format
      description: The format of the data to return.
      required: false
      example: json
      schema:
        type: string
        enum:
        - json
        - csv