Your guide to the Moov Metro2 API
The Moov Metro2 project offers an API with several operations for Metro 2 credit reporting files, including bidirectional conversion between plaintext and JSON formats. 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 run through a few basic examples of converting and validating Metro 2 files.
Background
Metro 2 is a data specification created by the Consumer Data Industry Association (CDIA) that allows data furnishers to report consumer credit history in a standard format electronically. It’s the current industry standard for credit reporting and is accepted by all U.S. consumer reporting agencies. However, direct access to official documentation on the Metro 2 format is only available to data furnishers, consumer reporting agencies, and certain software vendors.
A Metro 2 file consists of three record types—header, data, and trailer.
| Type | Purpose |
|---|---|
| Header Record | Holds file metadata and information about the reporting party. |
| Data Record | Includes a required base segment followed by several optional segments. The base segment contains account information for the primary consumer, such as account creation date, credit limit, and current balance. Optional segments contain more specific data like employment information. |
| Trailer Record | Lists various data totals present in the file, which verify that all records have been processed. |
Our API handles all record and segment types outlined by the CDIA. It also supports Metro 2 files in packed format, which is a condensed version of the more common unpacked (character) format.
Initial setup
The easiest way to get started with the Metro2 API is to install Docker on your system and run the latest Metro2 image with docker run -p 8080:8080 moov/metro2:latest in your terminal. This step automatically pulls the latest image and runs the API on port 8080.
To ensure the service is active, you can ping it with curl localhost:8080/health. If it’s up and running, you’ll receive an HTTP 200 status with {"status":"alive"} as the response body. Otherwise, you’ll see something like Failed to connect to localhost port 8080: Connection refused.
Converting file formats
With the /convert endpoint, you can convert plaintext Metro 2 files to JSON and vice versa. Simply supply the file you wish to convert and the format you’d like to convert to (json or metro). If the operation is successful, you will receive a response with the converted file contents. Please note that validation checks occur during conversion—invalid or missing values will be replaced by placeholder values or trigger parsing errors.
We have many sample files in the test/testdata directory of our project and refer to these examples throughout this article. To convert a file from JSON to the raw Metro format, use:
curl -X POST --form "file=@packed_file.json" --form "format=metro" localhost:8080/convert
To convert a file from the raw Metro format to JSON, use:
curl -X POST --form "file=@packed_file.dat" --form "format=json" localhost:8080/convert
Unlike some of our other APIs, Metro2 does not store files in memory of the API process. If you’d like to save converted files locally, use the cURL -o flag.
Validating files
We offer Metro 2 validation for both plaintext and JSON files via the /validator endpoint. If a file is valid, you’ll receive a response that looks like {"status":"valid file"}. Otherwise, the response will describe the issue. For example, a missing social security number in the base segment would return social_security_number in base segment has a required field. To validate a file, use:
curl -X POST --form "file=@packed_file.json" localhost:8080/validator
Summary
We hope this walkthrough helps you get started with Metro2 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 Metro2 on GitHub too! If you have any questions or suggestions for Metro2, please contact the Moov team on Slack (#metro2 channel) or submit an issue.
