Your guide to the Moov Fed API

May 20, 2021

Education 4 minute read

The Moov Fed project provides search functionality over Fedwire and FedACH participant data, which includes financial institution routing information.

While the project’s primary API documentation contains plenty of technical details and examples, the purpose of this guide is to serve as a launching point for new users. We’ll cover how to mount your own data files and perform a few basic searches using our API service.

Background

The U.S. Federal Reserve manages directories of receiving depository financial institutions (RDFIs) that are qualified to receive Fedwire and FedACH entries. These participant lists are synced with the Fed’s internal databases daily. Each participant entry follows a standard format with fields such as name, location, and routing number. Our API parses this information and outputs search results in JSON format.

Both participant directories used to be publicly available, but the Fed limited download access in late 2018. As a result, our project contains outdated data files and we are unable to share more recent directory data due to licensing restrictions. However, you can still retrieve up-to-date files for use in our project, either from Accuity or your financial institution. The Fed offers a routing directory FAQ page with more information.

Be sure to check out our Fed API video tutorial!

Initial setup

If you’d like to use our default (outdated) data files with the Fed API, the easiest way to get started is to install Docker on your system and run the latest Fed image in your terminal with docker run -p 8086:8086 -p 9096:9096 moov/fed:latest.

In production, you’ll want to supply your own up-to-date data files instead of using our outdated ones by default. If you have new Fedwire and FedACH data files saved locally, you can set environmental variables to their file paths when you run the API. Ensure your terminal’s current directory includes both data files. Assuming your new files are named newACH.json and newWire.json, run the following command:

docker run -v "$(pwd)":/src -e FEDACH_DATA_PATH=./src/newACH.json -e FEDWIRE_DATA_PATH=./src/newWire.json -p 8086:8086 -p 9096:9096 moov/fed:latest

This accomplishes the following:

Mounts our current working directory as src
Sets the FEDACH_DATA_PATH environmental variable to a data file named newACH.json
Sets the FEDWIRE_DATA_PATH environmental variable to a data file named newWire.json

Another option is to download data files directly from the Fed’s API with a routing number and valid download code. In this case, run the following command:

docker run -e FRB_ROUTING_NUMBER=<INSERT-ROUTING-NUMBER> -e FRB_DOWNLOAD_CODE=<INSERT-DOWNLOAD-CODE> -p 8086:8086 -p 9096:9096 moov/fed:latest

In all scenarios, docker run automatically pulls the latest image and runs the API on port 8086 with Prometheus metrics on 9096. To ensure the service is active, you can ping it with curl localhost:8086/ping. If it’s up and running, you’ll receive an HTTP 200 status with PONG as the response body. Otherwise, you’ll see something like Failed to connect to localhost port 8086: Connection refused.

Searching FedACH and Fedwire directories

To conduct a search, specify the desired participant list (ach, wire) and a query string containing search parameters. Submitting invalid search parameter values (i.e., a routing number with non-numeric characters) will return a descriptive error. A list of valid parameters is available in our Fed API documentation.

Behind the scenes, the API uses a variety of search algorithms from smetrics. Searches are case insensitive and all search parameters must match an entry for it to be considered a match. Search results are ordered by how closely they match the query, not the order in which they appear in the data file. If the search query has no matching results, you will receive a null response.

To look up a FedACH institution by the routing number 123456789, use:

curl "localhost:8086/fed/ach/search?routingNumber=123456789"

To look up a Fedwire institution by the routing number 123456789 and name Lincoln Bank, use:

curl "localhost:8086/fed/wire/search?routingNumber=123456789&name=Lincoln+Bank"

Notice & separates search parameters and + represents a space within parameter values in the search query.

Summary

We hope this walkthrough helps you get started with Fed and serves as a quick refresher for current users. The API is only a fraction of the entire project, so we encourage you to visit Fed on GitHub too! If you have any questions or suggestions for Fed, please contact the Moov team on Slack (#fed channel) or submit an issue.