FDIC

Current API Status

The FDIC lets you find information on FDIC-insured banking institutions. Their site uses a JSON API to look up financial information, branch information, etc.

This gem is a ruby client to that API. It's totally unaffiliated with the FDIC. It's open source, so anyone can use it, and anyone can help maintain it. At this point, it's maintained by the developers at Continuity.

If you need help understanding the data returned by that API, and this gem, it can help to look at the FDIC's BankFind glossary of terms.

Installation

Add this line to your application's Gemfile:

gem 'fdic'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fdic

Usage

Currently all of our features are namespaced under the FDIC::BankFind module

The FDIC API lets you find an Institution if you have its FDIC Certificate Number:

institution = FDIC::BankFind.find_institution(26588)  #=> FDIC::BankFind::Institution

If your certificate number is incorrect, this will raise an exception:

institution = FDIC::BankFind.find_institution(26588)  #=> FDIC::BankFind::Institution
# raises FDIC::Exceptions::RecordNotFound

Note, sometimes seemingly "valid" parameters will cause the FDIC to return a 500 error code.

institution = FDIC::BankFIND.find_institution("DOG") # Not a number
institution = FDIC::BankFIND.find_institution(1234567898798) # a number with more than 10 digits
# the FDIC returns 500

When this happens, the gem will catch the error and raise an exception:

institution = FDIC::BankFIND.find_institution(1234567898798) # a number with more than 10 digits
# raises FDIC::Exceptions::ServerError

If you don't have the certificate number, you can search for a Bank by name, and get back all matching Banks:

banks = FDIC::BankFind.find_bank('Dedicated Community Bank')  #=> [FDIC::BankFind::Bank, FDIC::BankFind::Bank, ...]

Once you have a Bank, you can get its Institution, which has much more data available:

institution = banks.first.find_institution!  # Bang, because it's another network request

The API also exposes information about an Institution's branches, and its history. You can query both of these on the FDIC::BankFind module directly, or on the Institution:

institution.find_branches!  #=> [FDIC::BankFind::Branch, FDIC::BankFind::Branch, ...]
FDIC::BankFind.find_branches(25688)   #=> [FDIC::BankFind::Branch, FDIC::BankFind::Branch, ...]

institution.find_history_events!                              #=> [FDIC::BankFind::HistoryEvent, ...]
FDIC::BankFind.find_history_events('Dedicated Community Bank', 26588)   #=> [FDIC::BankFind::HistoryEvent, ...]

Since a Bank knows its certificate number, it can look up its branch and history information, too.

# These work just like they do on Institutions:
bank.find_branches!
bank.find_history_events!

There are more fields exposed in the Institution API than what we've exposed. Where the field names are obscure or acronym-y, we'd like to clarify them; since we're pre-1.0, if we haven't looked up a field's meaning quite yet, we're holding off. (You can still get all the fields via #attributes.)

Schema Validation

This gem heavily depends on the schema of an unpublished government API. As such, it's liable to break. To help prevent against this we've provided a top level FDIC::BankFind.validate_schema? method, returning true if the schema of the FDIC's unpublished API has changed. We also expose a similar method FDIC::BankFind.validate_schema! which will raise a meaningful exception if the schema is invalid.

The gem provides an internal rake task, rake fdic:validate_schema! which calls FDIC::BankFind.validate_schema!. For the convenience of Rails users, we have used a Railtie to automatically provide this rake task in your application.

Because the schema may change more suddenly than developers can check for, we've created a very small application that validates the schema of this gem and its sister gem, ncua.

The api_schema_validator application checks daily to see if the schema is invalid. It exposes a few handy endpoints, notably /fdic/status, which returns the follwing JSON:

  {
    "schema_good" : true
  }
  // OR
  {
    "schema_good" : false
  }

and /fdic/badge which returns an svg status badge. In fact, you saw that badge at the top of this readme!

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ContinuityControl/fdic.

License

The gem is available as open source under the terms of the MIT License.