Your guide to the Moov Fed API
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.
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.
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
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
- Sets the
FEDACH_DATA_PATHenvironmental variable to a data file named
- Sets the
FEDWIRE_DATA_PATHenvironmental variable to a data file named
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 (
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
To look up a FedACH institution by the routing number
To look up a Fedwire institution by the routing number
123456789 and name
Lincoln Bank, use:
& separates search parameters and
+ represents a space within parameter values in the search query.
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.