NAV Navbar

HMDA API Documentation

The HMDA Platform API helps to prepare and test your HMDA data by allowing you to calculate rate spread, check a single LAR for formatting errors, generate/validate a check digit, and more.

HMDA Platform Filing API

The following documentation outlines the submission of HMDA data using the Filing API.

This API powers the HMDA Filing application

Authorization

To file HMDA data using the Filing API, a bearer authorization token is required for all Filing API calls. To acquire an authorization token use the /auth endpoint with your username and password as payload.

For local development, no authorization is needed. See One-line Local Development Environment (No Auth) for more info.

Example

  curl -X POST \
  "https://ffiec.cfpb.gov/auth/realms/hmda2/protocol/openid-connect/token" \
  -d 'client_id=hmda2-api&grant_type=password&username={{username}}%40{{bank_domain}}&password={{password}}'
Method POST
URL https://ffiec.cfpb.gov/auth/realms/hmda2/protocol/openid-connect/token
Payload client_id=hmda2-api
grant_type=password
username={{username}}%40{{bank_domain}}
password={{password}}

Error Messages

error error_description explanation
invalid_grant Account is not fully set up Either the password needs to be reset or the email needs to be verified..
invalid_grant Account disabled Please contact HMDA Help (hmdahelp@cfpb.gov) in order to re-enable the account.
invalid_grant Invalid user credentials The username or password provided is incorrect.

Password Policy

Postman Collection

The HMDA Postman Collection has been prepared to simplify the process of using the HMDA Platform Filing APIs.

Postman is a client side application that allows users to easily construct API calls and import external API collections.

Filing Process

Submission of a HMDA file flows in the following steps which are mirrored in the Submission status codes:

  1. Create a Filing: There is one Filing per institution, per filing season. This Filing is created by the HMDA Operations team in preperation for each filing season.
  2. Create a Submission: Submissions are created within a Filing, each representing a single file upload. Many Submissions can be created for a Filing. Each new Submission is assigned a sequentially incremented ID.
  3. Upload a File: A file is then uploaded to the Submission that was created. Only one file can be uploaded per Submission. To upload a new file you must create a new Submission.
  4. Check the status of the Submission: If a Submission triggers Syntactical or Validity Edits, a corrected file must be uploaded.
  5. Validate Quality Edits: Review any Quality Edits that have been triggered and confirm that the submitted data are correct.
  6. Validate Macro Edits: Review any Macro Edits that have been triggered and confirm that the submitted data are correct.
  7. Sign the Submission: Perform final review of the data and complete the HMDA filing.

Object Hierarchy

Submission Status

The Submission status is the best way to check the state of a Filing. It will be useful to query the Submission status often throughout the process of file upload and Edit validation.

Submission Status Codes

Example

{
  "id": {
    "lei": "12345abc",
    "period": "2020",
    "sequenceNumber": 3
  },
  "status": {
    "code": 1,
    "message": "No data has been uploaded yet.",
    "description": "The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file."
  },
  "start": 0,
  "end": 0,
  "fileName": "test.txt",
  "receipt": ""
}

In order to track the status of a Filing for a financial institution, the following states are captured by the HMDA Platform:

Code Message Description
1 No data has been uploaded yet. The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file.
2 Your file is uploading. Your file is currently being uploaded to the HMDA Platform.
3 Your file has been uploaded. Your data is ready to be analyzed.
4 Checking the formatting of your data. Your file is being analyzed to ensure that it meets formatting requirements specified in the HMDA Filing Instructions Guide.
5 Your data has formatting errors. Review these errors and update your file. Then, upload the corrected file.
6 Your data is formatted correctly. Your file meets the formatting requirements specified in the HMDA Filing Instructions Guide. Your data will now be analyzed for any edits.
7 Your data is being analyzed. Your data has been uploaded and is being checked for any edits.
8 Your data has been analyzed for Syntactical and Validity Errors. Your file has been analyzed and does not contain any Syntactical or Validity errors.
9 Your data has syntactical and/or validity edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until the file is corrected and re-uploaded.
10 Your data has been analyzed for Quality Errors. Your file has been analyzed, and does not contain quality errors.
11 Your data has quality edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
12 Your data has been analyzed for macro errors. Your file has been analyzed, and does not contain macro errors.
13 Your data has macro edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
14 Your data is ready for submission. Your financial institution has certified that the data is correct, but it has not been submitted yet.
15 Your submission has been accepted. This completes your HMDA filing process for this year. If you need to upload a new HMDA file, the previously completed filing will not be overridden until all edits have been cleared and verified, and the new file has been submitted.
-1 An error occurred while submitting the data. Please re-upload your file.

Endpoints

Start a Filing

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}" \
  -H 'Authorization: Bearer  {{access_token}}' \



JSON Response:
{
    "filing": {
        "period": "2020",
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "status": {
            "code": 2,
            "message": "in-progress"
        },
        "filingRequired": true,
        "start": 1572378187454,
        "end": 0
    },
    "submissions": []
}

For every filing period, you must begin by starting a Filing. This only needs to be done once per filing season. On the official HMDA Platform this Filing will have already been created by the HMDA Operations team. The POST will result in a 200 only for the first time it's called. If the filing for the given filing period already exists, the POST will return a 400.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}
Headers Authorization: Bearer {{access_token}}

Get a Filing

This endpoint can be used to confirm that a Filing exists for the relevant period.

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}" \
  -H 'Authorization: Bearer  {{access_token}}' \



JSON Response:
{
    "filing": {
        "period": "2020",
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "status": {
            "code": 2,
            "message": "in-progress"
        },
        "filingRequired": true,
        "start": 1572378187454,
        "end": 0
    },
    "submissions": []
}

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}
Headers Authorization: Bearer {{access_token}}

Create a Submission

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions" \
  -H 'Authorization: Bearer {{access_token}}' \



A Submission must be created for each file upload. More than one Submission can be created for a filing period. The most recent Submission will be considered the Latest Submission. Each POST on the Submission endpoint will return a new Submission sequenceNumber.



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status": {
        "code": 1,
        "message": "No data has been uploaded yet.",
        "description": "The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file."
    },
    "start": 1572358820303,
    "end": 0,
    "fileName": "",
    "receipt": ""
}

A new Submission must be created for each file upload. More than one Submission can be created for a filing period. The most recent Submission will be considered the Latest Submission. Each POST on the Submission endpoint will return a new Submission sequenceNumber.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions
Headers {{access_token}}

Get the Latest Submission

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/latest" \
  -H 'Authorization: Bearer {{access_token}}' \



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    },
    "start": 1572372016130,
    "end": 0,
    "fileName": "clean_file_10.txt",
    "receipt": "",
    "qualityVerified": false,
    "macroVerified": false,
    "qualityExists": true,
    "macroExists": true
}

Returns details about the last created Submission including its sequence number and status.
Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/latest
Headers Authorization: Bearer {{access_token}}

Upload a File

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/10" \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F file=



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status":{
        "code": 3,
        "message": "Your file has been uploaded.",
        "description": "Your data is ready to be analyzed."
    },
    "start": 1572372016130,
    "end": 0,
    "fileName": "",
    "receipt": ""
}

Upload a file to a Submission.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}
Headers Authorization: Bearer {{access_token}}, 'Content-Type': multipart/form-data
Payload LAR file

View Parsing Errors

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/10/parseErrors" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response
{
    "transmittalSheetErrors": [],
    "larErrors": [],
    "count": 0,
    "total": 0,
    "status": {
        "code": 5,
        "message": "Your data has formatting errors.",
        "description": "Review these errors and update your file. Then, upload the corrected file."
    },
    "_links": {
        "href": "/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/24/parseErrors{rel}",
        "self": "?page=1",
        "first": "?page=1",
        "prev": "?page=1",
        "next": "?page=0",
        "last": "?page=0"
    }
}

Returns a list of all parsing errors triggered by the file uploaded to a Submission.
Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/parseErrors
Headers Authorization: Bearer {{access_token}}

View All Edits

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/24/edits" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "syntactical": {
        "edits": []
    },
    "validity": {
        "edits": []
    },
    "quality": {
        "edits": [
            {
                "edit": "Q630",
                "description": "If Total Units is greater than or equal to 5, then HOEPA Status generally should equal 3."
            },
            {
                "edit": "Q631",
                "description": "If Loan Type equals 2, 3 or 4, then Total Units generally should be less than or equal to 4."
            }
        ],
        "verified": false
    },
    "macro": {
        "edits": [
            {
                "edit": "Q637",
                "description": "No more than 15% of the loans in the file should report Action Taken equals 5. Your data indicates a percentage outside of this range."
            }
        ],
        "verified": false
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.",
        "qualityVerified": false,
        "macroVerified": false
    }
}

Returns a summary of all Edits triggered by an upload in a Submission.
Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits
Headers Authorization: Bearer {{access_token}}

View Edit Details

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/24/edits/Q631" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "edit": "Q631",
    "rows": [
        {
           "id": "B90YWS6AFX2LGWOXJ1LDHHXWCDPM0ZEHW08FFTXGRXT62",
           "fields": [
               {
                   "name": "Loan Type",
                   "value": "3"
               },
               {
                   "name": "Total Units",
                   "value": "16"
               }
           ]
       }
   ],
   "count": 20,
   "total": 54,
   "_links": {
       "href": "/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/24/edits/Q631{rel}",
       "self": "?page=1",
       "first": "?page=1",
       "prev": "?page=1",
       "next": "?page=2",
       "last": "?page=3"
   }
}

Returns detailed information about a specific Edit, including a list of lines that triggered the Edit and the relevant fields from those lines.
Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/{{edit_code}}
Headers Authorization: Bearer {{access_token}}

Verify Quality Edits

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/quality" \
  -H 'Authorization: Bearer {{access_token}}' \
  -d '{"verified": true}'



JSON Response:
{
    "verified": true,
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    }
}

Verify that the uploaded data is correct and that the reported Quality Edits are not relevent to the Submission.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/quality
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Verify Macro Edits

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/macro" \
  -H 'Authorization: Bearer {{access_token}}' \
  -d '{"verified": true}'



JSON Response:
{
    "verified": true,
    "status": {
        "code": 14,
        "message": "Your data is ready for submission.",
        "description": "Your financial institution has certified that the data is correct, but it has not been submitted yet."
    }
}

Verify that the uploaded data is correct and that the reported Macro Edits are not relevent to the Submission.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/macro
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Sign a Submission

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/sign" \
  -H 'Authorization: Bearer {{access_token}}' \
  -d '{"verified": true}'



JSON Response:
{
    "email": "user@example.com",
    "timestamp": 1572375004080,
    "receipt": "B90YWS6AFX2LGWOXJ1LD-{{year}}-10-1572375004080",
    "status": {
        "code": 15,
        "message": "Your submission has been accepted.",
        "description": "This completes your HMDA filing process for this year. If you need to upload a new HMDA file, the previously completed filing will not be overridden until all edits have been cleared and verified, and the new file has been submitted."
    }
}

Sign and complete a HMDA Submission.
Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/sign
Headers Authorization: Bearer {{access_token}}
Body {"signed": true}

Get Sign receipt

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/sign" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "email": "user@example.com",
    "timestamp": 1572375004080,
    "receipt": "B90YWS6AFX2LGWOXJ1LD-{{year}}-55-1572375004080",
    "status": {
        "code": 15,
        "message": "Your submission has been accepted.",
        "description": "This completes your HMDA filing process for this year. If you need to upload a new HMDA file, the previously completed filing will not be overridden until all edits have been cleared and verified, and the new file has been submitted."
    }
}

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/sign
Headers Authorization: Bearer {{access_token}}

Get Submission Summary

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/summary'" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "submission": {
        "id": {
            "lei": "B90YWS6AFX2LGWOXJ1LD",
            "period": {
                "year": "2020"
                "quarter": null
            },
            "sequenceNumber": 20
        },
        "status": {
            "code": 15,
            "message": "Your submission has been accepted.",
            "description": "This completes your HMDA filing process for this year. If you need to upload a new HMDA file, the previously completed filing will not be overridden until all edits have been cleared and verified, and the new file has been submitted."
        },
        "start": 1634228617589,
        "end": 1634229085705,
        "fileName": "clean_file_5_rows_Bank0_2020.txt",
        "receipt": "B90YWS6AFX2LGWOXJ1LD-2020-26-1634229085705",
        "signerUsername": "test@testerbank.com"
    },
    "ts": {
        "id": 1,
        "institutionName": "Bank0",
        "year": "2020"
        "quarter": 4,
        "contact": {
            "name": "Mr. Smug Pockets",
            "phone": "555-555-5555",
            "email": "pockets@ficus.com",
            "address": {
                "street": "1234 Hocus Potato Way",
                "city": "Tatertown",
                "state": "UT",
                "zipCode": "84096"
            }
        },
        "agency": 9,
        "totalLines": 5,
        "taxId": "01-0123456",
        "LEI": "B90YWS6AFX2LGWOXJ1LD"
    }
}

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/sign
Headers Authorization: Bearer {{access_token}}

Quarterly Filing

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/quarter/Q1/submissions/latest" \
  -H 'Authorization: Bearer {{access_token}}' \



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": {
            "year": "2020"
            "quarter": "Q1"
        },
        "sequenceNumber": 10
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    },
    "start": 1585750668652,
    "end": 0,
    "fileName": "",
    "receipt": "",
    "qualityVerified": false,
    "macroVerified": false,
    "qualityExists": true,
    "macroExists": false
}

All the endpoints are the same for quarterly filing with the addtion of quarter/Q1/, quarter/Q2/ or quarter/Q3/ after the filing parameter and before the submission parameter.

HMDA Beta Platform Filing API

The following documentation outlines the simulated submission of HMDA data using the Beta Filing API.

The HMDA Beta Platform is a test environment for pre-release builds of the HMDA Platform. No data submitted to the HMDA Beta Platform will be considered as evidence of regulatory compliance.

Authorization

To simulate filing of HMDA data using the Beta Filing API, a bearer authorization token is required for all Beta Filing API calls. To acquire an authorization token use the /auth endpoint with your username and password as payload.

For local development, no authorization is needed. See One-line Local Development Environment (No Auth) for more info.

Please note: The HMDA Beta Platform is for test purposes only. Any data submitted WILL NOT be considered as evidence of regulatory compliance. For official Submissions, please visit https://ffiec.cfpb.gov/filing.

Example

  curl -X POST \
  "https://ffiec.beta.cfpb.gov/auth/realms/hmda2/protocol/openid-connect/token" \
  -d 'client_id=hmda2-api&grant_type=password&username={{username}}%40{{bank_domain}}&password={{password}}'
Method POST
URL https://ffiec.beta.cfpb.gov/auth/realms/hmda2/protocol/openid-connect/token
Payload client_id=hmda2-api
grant_type=password
username={{username}}%40{{bank_domain}}
password={{password}}

Postman Collection

The HMDA Postman Collection has been prepared to simplify the process of using the HMDA Platform Filing APIs.

Postman is a client side application that allows users to easily construct Beta HMDA Platform API calls and import external Beta Platform API collections.

Filing Process

Submission of HMDA data follows these steps which are mirrored in the Submission status codes:

Please note: The HMDA Beta Platform is for test purposes only. Signing of Submissions on the Beta Platform is disabled, as any data submitted WILL NOT be considered as evidence of regulatory compliance.

  1. Create a Filing: There is one Filing per institution, per filing season. This Filing is created by the HMDA Operations team in preperation for each filing season.
  2. Create a Submission: Submissions are created within a Filing with each representing a single file upload. Many Submissions can be created for a Filing. Each new Submission is assigned a sequentially incremented ID.
  3. Upload a File: A file is then uploaded to the Submission that was created. Only one file can be uploaded per Submission. To upload a new file you must create a new Submission.
  4. Check the status of the Submission: If a Submission triggers Syntactical or Validity Edits, a corrected file must be uploaded.
  5. Validate Quality Edits: Review any Quality Edits that have been triggered and confirm that the submitted data are correct.
  6. Validate Macro Edits: Review any Macro Edits that have been triggered and confirm that the submitted data are correct.
  7. Simulation Complete: Signing is disabled for Beta Platform Submissions.

Object Hierarchy

Submission Status

The Submission status is the best way to check the state of a Filing. It will be useful to query the Submission status often throughout the process of file upload and Edit validation.

Submission Status Codes

Example

{
  "id": {
    "lei": "12345abc",
    "period": "2020",
    "sequenceNumber": 3
  },
  "status": {
    "code": 1,
    "message": "No data has been uploaded yet.",
    "description": "The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file."
  },
  "start": 0,
  "end": 0,
  "fileName": "test.txt",
  "receipt": ""
}

In order to track the status of a Filing for a financial institution, the following states are captured by the HMDA Platform:

Code Message Description
1 No data has been uploaded yet. The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file.
2 Your file is uploading. Your file is currently being uploaded to the HMDA Platform.
3 Your file has been uploaded. Your data is ready to be analyzed.
4 Checking the formatting of your data. Your file is being analyzed to ensure that it meets formatting requirements specified in the HMDA Filing Instructions Guide.
5 Your data has formatting errors. Review these errors and update your file. Then, upload the corrected file.
6 Your data is formatted correctly. Your file meets the formatting requirements specified in the HMDA Filing Instructions Guide. Your data will now be analyzed for any edits.
7 Your data is being analyzed. Your data has been uploaded and is being checked for any edits.
8 Your data has been analyzed for Syntactical and Validity Errors. Your file has been analyzed and does not contain any Syntactical or Validity errors.
9 Your data has syntactical and/or validity edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until the file is corrected and re-uploaded.
10 Your data has been analyzed for Quality Errors. Your file has been analyzed, and does not contain quality errors.
11 Your data has quality edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
12 Your data has been analyzed for macro errors. Your file has been analyzed, and does not contain macro errors.
13 Your data has macro edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
14 Your data is ready for submission. Your financial institution has certified that the data is correct, but it has not been submitted yet.
-1 An error occurred while submitting the data. Please re-upload your file.

Endpoints

Start a Filing

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}" \
  -H 'Authorization: Bearer  {{access_token}}' \



JSON Response:
{
    "filing": {
        "period": "2020",
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "status": {
            "code": 2,
            "message": "in-progress"
        },
        "filingRequired": true,
        "start": 1572378187454,
        "end": 0
    },
    "submissions": []
}

For every filing period, you must begin by starting a Filing. This only needs to be done once per filing season. On the official HMDA Platform this Filing will have already been created by the HMDA Operations team. The POST will result in a 200 only for the first time it's called. If the Filing for the given filing period already exists, the POST will return a 400.
Method POST
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}
Headers Authorization: Bearer {{access_token}}

Get a Filing

This endpoint can be used to confirm that a Filing exists for the relevant period.

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}" \
  -H 'Authorization: Bearer  {{access_token}}' \



JSON Response:
{
    "filing": {
        "period": "2020",
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "status": {
            "code": 2,
            "message": "in-progress"
        },
        "filingRequired": true,
        "start": 1572378187454,
        "end": 0
    },
    "submissions": []
}

Method GET
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}
Headers Authorization: Bearer {{access_token}}

Create a Submission

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions" \
  -H 'Authorization: Bearer {{access_token}}' \



A Submission must be created for each file upload. More than one Submission can be created for a filing period. The most recent Submission will be considered the Latest Submission. Each POST on the Submission endpoint will return a new Submission sequenceNumber.



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status": {
        "code": 1,
        "message": "No data has been uploaded yet.",
        "description": "The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file."
    },
    "start": 1572358820303,
    "end": 0,
    "fileName": "",
    "receipt": ""
}

A new Submission must be created for each file upload. More than one Submission can be created for a filing period. The most recent Submission will be considered the Latest Submission. Each POST on the Submission endpoint will return a new Submission sequenceNumber.
Method POST
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions
Headers {{access_token}}

Get the Latest Submission

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/latest" \
  -H 'Authorization: Bearer {{access_token}}' \



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    },
    "start": 1572372016130,
    "end": 0,
    "fileName": "clean_file_10.txt",
    "receipt": "",
    "qualityVerified": false,
    "macroVerified": false,
    "qualityExists": true,
    "macroExists": true
}

Returns details about the last created Submission including its sequence number and status.
Method GET
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/latest
Headers Authorization: Bearer {{access_token}}

Upload a File

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}" \
  -H 'Authorization: Bearer {{access_token}}' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F file=



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2020",
        "sequenceNumber": 10
    },
    "status":{
        "code": 3,
        "message": "Your file has been uploaded.",
        "description": "Your data is ready to be analyzed."
    },
    "start": 1572372016130,
    "end": 0,
    "fileName": "",
    "receipt": ""
}

Upload a file to a Submission.
Method POST
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}
Headers Authorization: Bearer {{access_token}}, 'Content-Type': multipart/form-data
Payload LAR file

View Parsing Errors

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/parseErrors" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response
{
    "transmittalSheetErrors": [],
    "larErrors": [],
    "count": 0,
    "total": 0,
    "status": {
        "code": 5,
        "message": "Your data has formatting errors.",
        "description": "Review these errors and update your file. Then, upload the corrected file."
    },
    "_links": {
        "href": "/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/24/parseErrors{rel}",
        "self": "?page=1",
        "first": "?page=1",
        "prev": "?page=1",
        "next": "?page=0",
        "last": "?page=0"
    }
}

Returns a list of all parsing errors triggered by the file uploaded to a Submission.
Method GET
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/parseErrors
Headers Authorization: Bearer {{access_token}}

View All Edits

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "syntactical": {
        "edits": []
    },
    "validity": {
        "edits": []
    },
    "quality": {
        "edits": [
            {
                "edit": "Q630",
                "description": "If Total Units is greater than or equal to 5, then HOEPA Status generally should equal 3."
            },
            {
                "edit": "Q631",
                "description": "If Loan Type equals 2, 3 or 4, then Total Units generally should be less than or equal to 4."
            }
        ],
        "verified": false
    },
    "macro": {
        "edits": [
            {
                "edit": "Q637",
                "description": "No more than 15% of the loans in the file should report Action Taken equals 5. Your data indicates a percentage outside of this range."
            }
        ],
        "verified": false
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.",
        "qualityVerified": false,
        "macroVerified": false
    }
}

Returns a summary of all Edits triggered by an upload in a Submission.
Method GET
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits
Headers Authorization: Bearer {{access_token}}

View Edit Details

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/Q631" \
  -H 'Authorization: Bearer {{access_token}}'



JSON Response:
{
    "edit": "Q631",
    "rows": [
        {
           "id": "B90YWS6AFX2LGWOXJ1LDHHXWCDPM0ZEHW08FFTXGRXT62",
           "fields": [
               {
                   "name": "Loan Type",
                   "value": "3"
               },
               {
                   "name": "Total Units",
                   "value": "16"
               }
           ]
       }
   ],
   "count": 20,
   "total": 54,
   "_links": {
       "href": "/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/Q631{rel}",
       "self": "?page=1",
       "first": "?page=1",
       "prev": "?page=1",
       "next": "?page=2",
       "last": "?page=3"
   }
}

Returns detailed information about a specific Edit, including a list of lines that triggered the Edit and the relevant fields from those lines.
Method GET
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/{{edit_code}}
Headers Authorization: Bearer {{access_token}}

Verify Quality Edits

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/quality" \
  -H 'Authorization: Bearer {{access_token}}' \
  -d '{"verified": true}'



JSON Response:
{
    "verified": true,
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    }
}

Verify that the uploaded data is correct and that the reported Quality Edits are not relevent to the Submission.
Method POST
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/quality
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Verify Macro Edits

Example Request and Response


Request:
curl -X POST \
  "https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/submissions/{{sequenceNumber}}/edits/macro" \
  -H 'Authorization: Bearer {{access_token}}' \
  -d '{"verified": true}'



JSON Response:
{
    "verified": true,
    "status": {
        "code": 14,
        "message": "Your data is ready for submission.",
        "description": "Your financial institution has certified that the data is correct, but it has not been submitted yet."
    }
}

Verify that the uploaded data is correct and that the reported Macro Edits are not relevent to the Submission.
Method POST
Endpoint https://ffiec.beta.cfpb.gov/v2/filing/institutions/{{lei}}/filings/{{year}}/submissions/{{sequenceNumber}}/edits/macro
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Quarterly Filing

Example Request and Response


Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/{{lei}}/institutions/B90YWS6AFX2LGWOXJ1LD/filings/{{year}}/quarter/Q1/submissions/latest" \
  -H 'Authorization: Bearer {{access_token}}' \



JSON Response:
{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": {
            "year": "2020"
            "quarter": "Q1"
        },
        "sequenceNumber": 10
    },
    "status": {
        "code": 13,
        "message": "Your data has macro edits that need to be reviewed.",
        "description": "Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded."
    },
    "start": 1585750668652,
    "end": 0,
    "fileName": "",
    "receipt": "",
    "qualityVerified": false,
    "macroVerified": false,
    "qualityExists": true,
    "macroExists": false
}

All the endpoints are the same for quarterly filing with the addtion of quarter/Q1/, quarter/Q2/ or quarter/Q3/ after the filing parameter and before the submission parameter.

HMDA Public Verification API

The following are HMDA Public API endpoints that do not require authentication. You may use these public endpoints to help prepare your data for sumbission.

Single TS Verification

These endpoints are used to parse and run edits on a TS. Use parse to check for parsing errors and validate/{{year}} to check for syntactical, validity, and quality edits.

Parse TS

Example Request and Response


  Request:



curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/ts/parse" \
  -H 'Content-Type: application/json' \
  -d '{
  "ts" : "1|Bank 0|2018|4|Jane|111-111-1111|janesmith@bank.com|123 Main St|Washington|DC|20001|9|100|99-999999|10Bx939c5543TqA1144M"
}'



JSON Response:
  {
      "id": 1,
      "institutionName": "Bank 0",
      "year": 2018,
      "quarter": 4,
      "contact": {
          "name": "Jane",
          "phone": "111-111-1111",
          "email": "janesmith@bank.com",
          "address": {
              "street": "123 Main St",
              "city": "Washington",
              "state": "DC",
              "zipCode": "20001"
          }
      },
      "agency": 9,
      "totalLines": 100,
      "taxId": "99-999999",
      "LEI": "10Bx939c5543TqA1144M"
  }

This endpoint runs parsing on a Transmittal Sheet (TS). The endpoint returns a list of parsing errors in JSON format. If the TS is valid it the parsed TS object in JSON format.
Method POST
URL https://ffiec.cfpb.gov/v2/public/ts/parse
Payload Pipe delimited TS
Return JSON

Validate TS

Example Request and Response


  Request:



curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/ts/validate/2018" \
  -H 'Content-Type: application/json' \
  -d '{
  "ts" : "1|Bank 0|2018|4|Jane|111-111-1111|janesmith@bank.com|123 Main St|Washington|DC|20001|9|100|99-999999|10Bx939c5543TqA1144M"
}'



JSON Response:
    {
        "syntactical": {
            "errors": []
        },
        "validity": {
            "errors": []
        },
        "quality": {
            "errors": []
        }
    }

This endpoint runs parsing and a specific year's edit checks on a Transmittal Sheet (TS). It returns edit details if the TS is able to be parsed or parsing errors if not.

Note: Some edit checks require institution data. These checks are not run in any public APIs.
Method POST
URL https://ffiec.cfpb.gov/v2/public/ts/validate/{{year}}
Payload Pipe delimited TS
Return JSON

Single LAR Verification

These endpoints are used to parse and and run edits on a LAR. Use parse to check for parsing errors and validate/{{year}} to check for syntactical, validity, and quality edits.

Parse a LAR

Example Request and Response


Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/lar/parse" \
  -H 'Content-Type: application/json' \
  -d '{ "lar": "2|10Bx939c5543TqA1144M|10Bx939c5543TqA1144M999143X38|20180721|1|1|1|1|1|110500|1|20180721|123 Main St|Beverly Hills|CA|90210|06037|06037264000|1|1|1|1|1||1|1|1|1|1||3|3|5|7|7|7|7||||5|7|7|7|7||||3|3|1|1|3|3|30|30|36|1|0.428|1|1|750|750|1|9|1|9|10|10|10|10||2399.04|NA|NA|NA|NA|4.125|NA|42.95|80.05|360|NA|1|2|1|1|350500|1|1|5|NA|1|1|12345|1|1|1|1|1||1|1|1|1|1||1|1|1"
}'



JSON Response:
  {
    "larIdentifier": {
        "id": 2,
        "LEI": "10BX939C5543TQA1144M",
        "NMLSRIdentifier": "12345"
    },
    "loan": {
        "ULI": "10Bx939c5543TqA1144M999143X38",
        "applicationDate": "20180721",
        "loanType": 1,
        "loanPurpose": 1,
        "constructionMethod": 1,
        "occupancy": 1,
        "amount": 110500.0,
        "loanTerm": "360",
        "rateSpread": "0.428",
        "interestRate": "4.125",
        "prepaymentPenaltyTerm": "NA",
        "debtToIncomeRatio": "42.95",
        "combinedLoanToValueRatio": "80.05",
        "introductoryRatePeriod": "NA"
    },
    "larAction": {
        "preapproval": 1,
        "actionTakenType": 1,
        "actionTakenDate": 20180721
    },
    "geography": {
        "street": "123 Main St",
        "city": "Beverly Hills",
        "state": "CA",
        "zipCode": "90210",
        "county": "06037",
        "tract": "06037264000"
    },
    "applicant": {
        "ethnicity": {
            "ethnicity1": 1,
            "ethnicity2": 1,
            "ethnicity3": 1,
            "ethnicity4": 1,
            "ethnicity5": 1,
            "otherHispanicOrLatino": "",
            "ethnicityObserved": 3
        },
        "race": {
            "race1": 5,
            "race2": 7,
            "race3": 7,
            "race4": 7,
            "race5": 7,
            "otherNativeRace": "",
            "otherAsianRace": "",
            "otherPacificIslanderRace": "",
            "raceObserved": 3
        },
        "sex": {
            "sex": 1,
            "sexObserved": 3
        },
        "age": 30,
        "creditScore": 750,
        "creditScoreType": 1,
        "otherCreditScoreModel": "9"
    },
    "coApplicant": {
        "ethnicity": {
            "ethnicity1": 1,
            "ethnicity2": 1,
            "ethnicity3": 1,
            "ethnicity4": 1,
            "ethnicity5": 1,
            "otherHispanicOrLatino": "",
            "ethnicityObserved": 3
        },
        "race": {
            "race1": 5,
            "race2": 7,
            "race3": 7,
            "race4": 7,
            "race5": 7,
            "otherNativeRace": "",
            "otherAsianRace": "",
            "otherPacificIslanderRace": "",
            "raceObserved": 3
        },
        "sex": {
            "sex": 1,
            "sexObserved": 3
        },
        "age": 30,
        "creditScore": 750,
        "creditScoreType": 1,
        "otherCreditScoreModel": "9"
    },
    "income": "36",
    "purchaserType": 1,
    "hoepaStatus": 1,
    "lienStatus": 1,
    "denial": {
        "denialReason1": 10,
        "denialReason2": 10,
        "denialReason3": 10,
        "denialReason4": 10,
        "otherDenialReason": ""
    },
    "loanDisclosure": {
        "totalLoanCosts": "2399.04",
        "totalPointsAndFees": "NA",
        "originationCharges": "NA",
        "discountPoints": "NA",
        "lenderCredits": "NA"
    },
    "nonAmortizingFeatures": {
        "balloonPayment": 1,
        "interestOnlyPayment": 2,
        "negativeAmortization": 1,
        "otherNonAmortizingFeatures": 1
    },
    "property": {
        "propertyValue": "350500.0",
        "manufacturedHomeSecuredProperty": 1,
        "manufacturedHomeLandPropertyInterest": 1,
        "totalUnits": 5,
        "multiFamilyAffordableUnits": "NA"
    },
    "applicationSubmission": 1,
    "payableToInstitution": 1,
    "AUS": {
        "aus1": 1,
        "aus2": 1,
        "aus3": 1,
        "aus4": 1,
        "aus5": 1,
        "otherAUS": ""
    },
    "ausResult": {
        "ausResult1": 1,
        "ausResult2": 1,
        "ausResult3": 1,
        "ausResult4": 1,
        "ausResult5": 1,
        "otherAusResult": ""
    },
    "reverseMortgage": 1,
    "lineOfCredit": 1,
    "businessOrCommercialPurpose": 1
}

This endpoint runs parsing on a single Loan Application Register (LAR). The endpoint returns a list of parsing errors in JSON format. If the LAR is valid it returns the parsed LAR object in JSON format.
Method POST
URL https://ffiec.cfpb.gov/v2/public/lar/parse
Payload Pipe delimited LAR
Return JSON

Validate a LAR

Example Request and Response


  Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/lar/validate/2018" \
  -H 'Content-Type: application/json' \
  -d '{"lar": ""2|B90YWS6AFX2LGWOXJ1LD|B90YWS6AFX2LGWOXJ1LD0KQ78F1Q02LVT4VCYK1G3D253|20180613|3|2|2|2|3|218910|5|20181031|1234 Hocus Potato Way|Tatertown|NM|14755|35003|35003976400|1|13||11||KE0NW|1|||||NA2IJJ7VBBQ15DTFRNK1PVWOPOXL3NH1PHUMN7S2J4|2|2|7|||||E120FYAU7BTSC3P51IL87C97W3N9VT791BMJI57RLJQSHOFDTUD7PQSPGHQ69D7I2P8JBDCBUIGRLX2BUS7SJR|DOOOI8UXY9PZDSRVFKP91CUQG95E88Y22KDR1AI3|1K1JINAYSIHCWBGJW3KOHU5D5TSK1Z61SUT5M9WQVWOHX|27|24|41|43|2|MS1LKLX7XZRKL23TV01I49RADZGUN0QY5AG9H4BJCVFTA4ZQ1EJUS1376QJXD87ZZDN5EFZIUWB8SK5EU34RVGOVTE|Y083OZN1VFT6B2XGL397ABL0Z4EV4CD45I7ZJ7FRSXXL4BRMKVPR5UCVV0K6IDLP7WLCBZAQ5KXT69PNE9PWQKCPKJB|UV0FTHG00G8WM65I7591IJYP9TEMXMDCVGZYRJTBUBBKEZI65HGL9ML|3|2|2|2|1|1|75|4|NA|0|NA|3|2|8888|8888|9||9||10|||||NA|NA|NA|NA|NA|NA|32|NA|NA|256|29|1111|1111|1111|1111|NA|3|2|16|Exempt|2|2|NA|3|1|5|1||DOREBESQSW1QT58SD2OZTHQUGXLSKCAJYZ63NJE2MUIAFQL4KW6PU26YSU786GT0IMCWWKCN25Y7KU0VLU0PPKWR8G6DKWI9BANPIE9I2ZZ5XDUX0TBAY4XFRFQZF087WS9ESTAKIV5V9HSZ2VXW7J5JMGPP4CGYA51BK68T57NN4KTKJVXIQMFXBTN5E3LGKKX3LITQ4C7OPFJ|7|6|5|5|||1111|2|1111""
}'



JSON Response:
  {
    "syntactical": {
        "errors": []
    },
    "validity": {
        "errors": []
    },
    "quality": {
        "errors": [
            {
                "edit": "Q618",
                "description": "\"If Construction Method equals 2, then Manufactured Home Secured Property Type generally should not be 3.\""
            },
            {
                "edit": "Q631",
                "description": "\"If Loan Type equals 2, 3 or 4, then Total Units generally should be less than or equal to 4.\""
            },
            {
                "edit": "Q632",
                "description": "\"If Automated Underwriting System: 1; Automated Underwriting System: 2; Automated Underwriting System: 3; Automated Underwriting System: 4; or Automated Underwriting System: 5 equals 3, then the corresponding Automated Underwriting System Result: 1; Automated Underwriting System Result: 2; Automated Underwriting System Result: 3; Automated Underwriting System Result: 4; or Automated Underwriting System Result: 5 should equal 8 or 13.\""
            }
        ]
    }
}

This endpoint runs parsing and a specific year's edit checks on a Loan Application Register (LAR). It returns edit details if the LAR is able to be parsed or parsing errors if not.

Note: Some edit checks require institution data. These checks are not run in any public APIs. Macro edits are also not run this endpoint checks only a single LAR.
Method POST
URL https://ffiec.cfpb.gov/v2/public/lar/validate/{{year}}
Payload Pipe delimited LAR
Return JSON

Full HMDA File Verification

The following endpoints can be used to parse and run edit checks on a full HMDA file.

Parse a HMDA File

Example Request and Response


  Request:
  curl -X OPTIONS \
  "https://ffiec.cfpb.gov/v2/public/hmda/parse" \
  -F file=@/.txt



JSON Response:
  {
    "validated": []
  }

This endpoint runs parsing on a HMDA file. The endpoint returns a list of parsing errors in JSON format. If the file is valid it returns and empty list.
Method OPTIONS
URL https://ffiec.cfpb.gov/v2/public/hmda/parse
Payload HMDA file
Return JSON

Validate a HMDA File

Example Request and Response


  Request:
  curl -X OPTIONS \
  "https://ffiec.cfpb.gov/v2/public/hmda/validate" \
  -F file=@/.txt



JSON Response: 
  {
    "parserErrors": [
        {
            "rowNumber": 1,
            "estimatedULI": "Transmittal Sheet",
            "errorMessages": [
                {
                    "fieldName": "Calendar Quarter",
                    "inputValue": "a",
                    "validValues": "Integer"
                }
            ]
        }
    ],
    "validationErrors": [
        [
            {
                "uli": "B90YWS6AFX2LGWOXJ1LDNIXOQ6OO7BRA5SLR6FSJJ5R89",
                "editName": "V619-2",
                "editDescription": "\"The Action Taken Date must be in the reporting year.\"",
                "fields": {
                    "Action Taken Date": "20180908",
                    "Application Date": "NA"
                }
            }
        ]
    ]
  }

This endpoint runs parsing and a specific year's edit checks on a HMDA file. This endpoint runs checks row by row and so can return both parsing and edit check information if some rows pass parsing and others do not.

Note: Some edit checks require institution data. These checks are not run in any public APIs. Macro edits are also not run as the check runs line by line.
Method OPTIONS
URL https://ffiec.cfpb.gov/v2/public/hmda/validate/{{year}}
Payload HMDA file
Return JSON

HMDA File Serving

The HMDA Platform serves a number of files including:

  1. Documentation
  2. Modified LAR
  3. Institution Register Summaries
  4. Dynamic National Loan-Level Dataset
  5. Snapshot National Loan-Level Dataset
  6. Disclosure Reports
  7. Aggregate Reports
  8. Rate Spread Data

The HMDA Platform serves these files in three seperate ways, through the HMDA File api, Githhub, and S3.

The HMDA File api is used to serve the Modfied LAR and Institution Register Summaries. Github is used to serve documentation in the form of markdown files which are formatted by the HMDA-Frontend. S3 is used to serve all other files

HMDA File API

The HMDA File API is used for accessing the Modified LAR and Institution Register Summaries.

Get Modified LAR Pipe Delimited .txt File
Method GET
Endpoint https://ffiec.cfpb.gov/file/modifiedLar/year/{{year}}/institution/{{lei}}/txt

Get Modified LAR Pipe Delimited .txt File with Header
Method GET
Endpoint https://ffiec.cfpb.gov/file/modifiedLar/year/{{year}}/institution/{{lei}}/txt/header

Get Modified LAR .csv File
Method GET
Endpoint https://ffiec.cfpb.gov/file/modifiedLar/year/{{year}}/institution/{{lei}}/csv

Get Modified LAR .csv File with Header
Method GET
Endpoint https://ffiec.cfpb.gov/file/modifiedLar/year/{{year}}/institution/{{lei}}/csv/header

Get Institution Register Summary (IRS)

Example Request and Response


Request:

curl -X POST "https://ffiec.cfpb.gov/public/rateSpread/reports/irs/year/2019/institution/B90YWS6AFX2LGWOXJ1LD" \
-H 'Authorization: Bearer  {{access_token}}'

CSV Response:
MSA/MD, MSA/MD Name, Total Lars, Total Amount ($000's), CONV, FHA, VA, FSA, Site Built, Manufactured, 1-4 units, 5+ units, Home Purchase, Home Improvement, Refinancing, Cash-out Refinancing, Other Purpose, Purpose N/A
16984,"Chicago-Naperville, IL-IN-WI", 1, 135, 0, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 0, 0, 0
27260,"Jacksonville-St. Marys-Palatka, FL-GA", 1, 445, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0

The IRS is a summary of a institution's HMDA submission to be used by the filing institution to confirm that they are submitting the correct data.

As such, access to each IRS is restricted to users associated with the institution. Users must be authenticated using the HMDA authentication system and include a bearer token with their request.

(More information on authentication can be found above in the Authorization section in the HMDA Platform Filing API section of these docs)
Method GET
Endpoint https://ffiec.cfpb.gov/file/reports/irs/year/{{year}}/institution/{{lei}}
Headers Authorization: Bearer {{access_token}}

Github File Service

Documentation served from github can be found on the HMDA Frontend github repository

S3 File Service

All other files are accessed through direct links to the HMDA Platform's public S3 bucket. These S3 links are all prefixed with: https://s3.amazonaws.com/cfpb-hmda-public/prod.

Data Browser API

The data browser api enables developers to interact with HMDA data. The API will return either a JSON report of the data or CSV of the raw data.

This API is what powers the HMDA Data Browser application

Note: depending on the query, queries may take a while to return and data may be too large for conventional spread sheet applications.

HMDA Data Endpoints

HMDA Data Endpoints

GET https://ffiec.cfpb.gov/v2/data-browser-api/data-browser-api/view/nationwide/aggregations

This endpoint is used to generated JSON reports on the full dataset. The year parameter is required when calling this endpoint.

GET https://ffiec.cfpb.gov/v2/data-browser-api/data-browser-api/view/aggregations

This endpoint is used to generated JSON reports on an LEI and/or geography subset. The year parameter as well at least of a geographic and/or LEI parameter are required when calling this endpoint.

GET https://ffiec.cfpb.gov/v2/data-browser-api/data-browser-api/view/nationwide/csv

This endpoint is used to download raw HMDA data given the applied filters in csv format. The file will be streamed. The year parameter is required when calling this endpoint.

GET https://ffiec.cfpb.gov/v2/data-browser-api/data-browser-api/view/csv

This endpoint is used to download raw HMDA data given the applied filters in csv format. The file will be streamed. The year parameter as well at least of a geographic and/or LEI parameter are required when calling this endpoint.

Supported Geographic Filters

Geography Format
MSA/MD Five Digit MSA/MD Code
State Two Letter State Abbreviation (Eg. AL for Alabama)
County Five Digit County FIPS Code

HMDA Data Filters

HMDA Data requests support the following filtering parameters. Multiple options are acceptable.

Variable Name Options
years 2018,2019
actions_taken 1,2,3,4,5,6,7,8
construction_methods 1,2
dwelling_categories Single Family (1-4 Units):Site-Built
Multifamily:Site-Built
Single Family (1-4 Units):Manufactured
Multifamily:Manufactured
ethnicities Hispanic or Latino
Not Hispanic or Latino
Joint
Ethnicity Not Available
Free Form Text Only
lien_statuses 1,2
loan_products Conventional:First Lien
FHA:First Lien
VA:First Lien
FSA/RHS:First Lien
Conventional:Subordinate Lien
FHA:Subordinate Lien
VA:Subordinate Lien
FSA/RHS:Subordinate Lien
loan_purposes 1,2,31,32,4,5
loan_types 1,2,3,4
races Asian
Native Hawaiian or Other Pacific Islander
Free Form Text Only
Race Not Available
American Indian or Alaska Native
Black or African American
2 or more minority races
White
Joint
sexes Male
Female
Joint
Sex Not Available
total_units 1,2,3,4,5-24,25-49,50-99,100-149,>149

Aggregation Example

Example Request and Response


  Request:
  curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations?states=MD&years=2018&actions_taken=5,6&races=White,Asian,Joint"

  JSON Response:
  {
    "parameters": {
        "state": "MD",
        "actions_taken": "5,6",
        "races": "Asian"
    },
    "aggregations": [
        {
            "count": 679,
            "sum": 1.90835E8,
            "actions_taken": "5",
            "races": "Asian",
            "state": "MD"
        },
        {
            "count": 716,
            "sum": 2.5435E8,
            "actions_taken": "6",
            "races": "Asian",
            "state": "MD"
        }
    ],
    "servedFrom": "cache"
}

Get an aggregation, in JSON format, of HMDA Data reported in 2018 in Maryland, with action takens 5 - File closed for incompleteness, or 6 - Purchased loan, where the reported race was Asian.

GET JSON with the following parameters

var value
years 2018
states MD
actions_taken 5,6
races Asian

CSV Example

Example Request and Response


  Request:
  curl -L "https://ffiec.cfpb.gov/v2/data-browser-api/view/csv?states=CA,MD,DC&years=2018&actions_taken=5"

  CSV Response:

Get a CSV containing all HMDA data reported in 2018 in California, Maryland, or DC, with action taken 5 - File closed for incompleteness.

GET CSV file with the following parameters

var value
states CA, MD, DC
years 2018
action_taken 5

HMDA Filers

GET https://ffiec.cfpb.gov/v2/data-browser-api/data-browser-api/view/filers

This endpoint can be used to fetch list of financial instituions present in the HMDA dataset. The year parameter is required when calling this endpoint.

HMDA Filer Parameters

Parameter Name Options
years CSV list of years (example: 2018,2019)
states two letter state code
msamds 5 digit integer code
counties 5 digit integer code

HMDA Filers Example

Example Request and Response


  Request:
  curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/filers?states=MD,DC&years=2018"

  JSON Format Response:
  {
    "institutions":[
      {
          "lei":"lei",
          "name":"institution name",
          "period":2018
      },
      {
          "lei":"lei",
          "name":"institution name",
          "period":2018
      }
    ]
  }

GET with the following parameters

var value
years 2018
states MD, DC

Errors

Example Request and Response


  Request:
  curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/csv"

  JSON Response:
  {
      "errorType": "provide-atleast-msamds-or-states",
      "message": "Provide year and either states or msamds or both"
  }

Incorrect calls will result in an error. For example the following call will result in an error since there is no state(s)/msamds and years provided.


Rate Spread

Rate Spread API

The following endpoints allow users to provide loan information and returns the associated ratespread either one at a time in JSON format or in a batch in CSV format.

This API is what powers the Rate Spread Calculator application.

Note: The response is either a number representing the rate spread or "NA".

Rate Spread Parameters

The following parameters must be provided when using any ratespread API. These are provided in either JSON or CSV format.

Variable Type Accepted Values
action_taken_type integer 1 = Originated
2 = Approved Not Accepted
8 = Pre-approval request approved but not Accepted
3, 4, 5, 6 or 7 will result in NA
loan_term integer Range from 1 - 50
amortization_type String FixedRate or VariableRate
apr double The annual Percentage Rate on the loan, eg 6.0
lock_in_date date YYYY-MM-DD
reverse_mortgage integer 2 = false
1 = true, will result in NA

Single Ratespread

Example Request and Response


  Request:



curl -X POST "https://ffiec.cfpb.gov/public/rateSpread" -H "Content-Type: application/json" -d '{ "actionTakenType": 1, "loanTerm": 30, "amortizationType": "FixedRate", "apr": 6.0, "lockInDate": "2017-11-20", "reverseMortgage": 2 }'



JSON Response:



{"rateSpread":"2.010"}

This endpoint accepts loan data in JSON format and returns a JSON object containing the associated ratespread.

POST https://ffiec.cfpb.gov/public/rateSpread

The JSON example contains the following parameters:

Variable Value
actionTakenType 1
loanTerm 30
amortizationType FixedRate
apr 6.0
lockInDate 2017-11-20
reverseMortgage 2

Batch Ratespreads

Example Request and Response


Request:

curl -X POST "https://ffiec.cfpb.gov/public/rateSpread/csv" -F file=

CSV Response file with an added column for rate_spread calculated for each row:

action_taken_type,loan_term,amortization_type,apr,lock_in_date,reverse_mortgage,rate_spread
1,30,FixedRate,6.0,2017-11-20,2,2.010
1,30,VariableRate,6.0,2017-11-20,2,2.150

In order to batch caluculate ratespreads the csv endpoint can be used. This endpoint accepts a CSV file of ratespread data and returns a CSV file with a new column for the ratespread.

POST https://ffiec.cfpb.gov/public/rateSpread/csv

The CSV file example contains the following contents:
1 30 FixedRate 6.0 2017-11-20
1 30 VariableRate 6.0 2017-11-20

Check Digit

The following endpoints allow users to generate and validate check digits either one at a time in JSON format or in a batch in CSV format.

This API is what powers the Check Digit Tool.

Check Digit Endpoints

Single Checkdigit Generation

POST https://ffiec.cfpb.gov/v2/public/uli/checkDigit

This endpoint takes a single ULI in JSON format and returns a single two digit check digit in JSON format.

Batch Checkdigit Generation

POST https://ffiec.cfpb.gov/v2/public/uli/checkDigit/csv

This endpoint takes multiple ULIs in CSV format and returns two digit check digits in CSV format.

Single Checkdigit Validation

POST https://ffiec.cfpb.gov/v2/public/uli/validate

This endpoint takes a single ULI with check digits in JSON format and returns whether it is valid in JSON format.

Batch Checkdigit Validation

POST https://ffiec.cfpb.gov/v2/public/uli/validate/csv

This endpoint multiple ULIs with check digits in CSV format and returns whether they is valid in CSV format.

Single Check Digit Generation

Example Request and Response


  Request:
  curl POST 'https://ffiec.cfpb.gov/v2/public/uli/checkDigit' \
  --header 'Content-Type: application/json' \
  --data-raw '{loanId: "EILKZAIZF6TX4HB8ZDX33H"}'

  JSON Response:
  {
    "loanId":"EILKZAIZF6TX4HB8ZDX33H",
    "checkDigit":"54",
    "uli":"EILKZAIZF6TX4HB8ZDX33H54"
  }

POST request to get a single check digit.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/checkDigit
Payload JSON
Return JSON

Batch Check Digit Generation

Example Request and Response


  Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
  -F file=@/check_digit_sample_file.csv

  Request Payload:
  B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R87
  95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS

  CSV Response:
  loanId,checkDigit,uli
  B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R87,51,B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R8751
  95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS,92,95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92

POST request to get batch check digits.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/checkDigit/csv
Payload CSV file as shown bellow
Return CSV

Batch Check Digit Generation (Bad Request)

Example Request and Response


  Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
  -F file=@/check_digit_sample_file.csv

  Request Payload:
  BANK1LTEST123451150
  BANK1LEIFORTEST123458001
  BANK1LEIFORTEST123458003
  BANK1LEIFO!TEST123458234
  BANK343434733473438000034343473347343800000
  TESTT343434_3347343800001


  CSV Response:
  loanId,checkDigit,uli
  BANK1LTEST123451150,Error,Loan ID is not between 21 and 43 characters long
  BANK1LEIFORTEST123458001,26,BANK1LEIFORTEST12345800126
  BANK1LEIFORTEST123458003,20,BANK1LEIFORTEST12345800320
  BANK1LEIFO!TEST123458234,Error,Loan ID is not alphanumeric
  BANK343434733473438000034343473347343800000,79,BANK34343473347343800003434347334734380000079
  TESTT343434_3347343800001,Error,Loan ID is not alphanumeric

POST request to get batch check digits.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/checkDigit/csv
Payload CSV file as shown bellow
Return CSV

Single Check Digit Validation

Example Request and Response


  Request:
  curl POST 'https://ffiec.cfpb.gov/v2/public/uli/validate' \
  --header 'Content-Type: application/json' \
  --data-raw '{"uli": "EILKZAIZF6TX4HB8ZDX33H54"}'

  JSON Response:
  {
    "isValid": true
  }

POST request to validate a single check digit.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/validate
Payload JSON
Return JSON

Batch Check Digit Validation

Example Request and Response


  Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
  -F file=@/check_digit_sample_file.csv
  
  Request Payload:
  95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92
  B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89
  
  CSV Response:
  uli,isValid
  95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92,true
  B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89,false

POST request to batch validate check digits.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/validate/csv
Payload CSV file as shown bellow
Return CSV

Batch Check Digit Validation(Bad Request)

Example Request and Response


  Request:
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
  -F file=@/check_digit_sample_file.csv
  
  Request Payload:
  BANK1LEIF345115014
  BANK1LEIFORTEST12345800126
  BANK1LEIFOR@#EST12345800320
  BANK1LEIFORTEST12345823406
  BANK34343473*4734380000037
  BANK3434347334734380000131BANK3434347334734380000131BANK3434347334734380000131
  
  CSV Response:
  uli,isValid
  BANK1LEIF345115014,ULI is not between 23 and 45 characters long
  BANK1LEIFORTEST12345800126,true
  BANK1LEIFOR@#EST12345800320,ULI is not alphanumeric
  BANK1LEIFORTEST12345823406,true
  BANK34343473*4734380000037,ULI is not alphanumeric
  BANK3434347334734380000131BANK3434347334734380000131BANK3434347334734380000131,ULI is not between 23 and 45 characters long

POST request to batch validate check digits.
Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/validate/csv
Payload CSV file as shown bellow
Return CSV

Quarterly Data Graph API

This API is what powers the Data Browser's Quarterly Graphs

Quarterly Data Endpoints

Graph Data Summary

Example


Request:
curl "https://ffiec.cfpb.gov/quarterly-data/graphs" -H 'Content-Type: application/json'

JSON Response:
{
  "graphs": [
    {
      "category": "Loan & Application Counts",
      "endpoint": "applications",
      "title": "How has the number of applications changed?"
    },
    {
      "category": "Loan & Application Counts",
      "endpoint": "loans",
      "title": "How has the number of loans changed?"
    },
    ...
  ]
}
Method GET
URL https://ffiec.cfpb.gov/quarterly-data/graphs
Return JSON

This endpoint lists out all the available graph data accessible through the API. The returned graphs field is a list of metadata consisting of title, category, and endpoint; by appending the endpoint field of the desired graph metadata to the API root url of https://ffiec.cfpb.gov/quarterly-data/graphs/, the full graph data is retrieved.

Specific Graph Data

Example


Request:
curl "https://ffiec.cfpb.gov/quarterly-data/graphs/applications" -H 'Content-Type: application/json'

JSON Response:
{
  "series": [
    {
      "coordinates": [
        {
          "x": "2019-Q3",
          "y": 1167382.0
        },
        {
          "x": "2019-Q4",
          "y": 1258227.0
        },
        {
          "x": "2020-Q1",
          "y": 1301157.0
        },
        ...
      ],
      "name": "Conventional Conforming",
    },
    ...
  ],
  "subtitle": "Conventional conforming applications dramatically increased since 2019. FHA loans temporarily moved higher in 2020 Q3.",
  "title": "How has the number of applications changed?",
  "xLabel": "Year Quarter",
  "yLabel": "Application Count"
}
Method GET
URL https://ffiec.cfpb.gov/quarterly-data/graphs/{endpoint}
Return JSON

To get the specific graph data, append the endpoint value from the above Graph Data Summary section example response to the base url of https://ffiec.cfpb.gov/quarterly-data/graphs/, e.g. https://ffiec.cfpb.gov/quarterly-data/graphs/applications.

The response contains the following sections:

title, subtitle, xLabel, and yLabel are text fields providing some contexts of what the data represents.

series section is a list of data representing each line within the graph; each element within series will include xy coordinates, and name of the line. In general, the x coordinates represents the time period (e.g. 2021-Q3), y coordinates are numeric values.

Available Graph Data

At the time of publication, below are the data available with their endpoints. To get the most up-to-date list, refer to Graph Data Summary section.
Endpoint Description
applications How has the number of applications changed?
all-applications How much of the total loan/application count do quarterly filers account for?
loans How has the number of loans changed?
credit-scores How have median credit scores changed?
credit-scores-cc-re For conventional conforming loans, how have median credit scores differed by race/ethnicity?
credit-scores-fha-re For FHA loans, how have median credit scores differed by race/ethnicity?
ltv How has median CLTV changed?
ltv-cc-re For conventional conforming loans, how has median CLTV differed by race/ethnicity?
ltv-fha-re For FHA loans, how has median CLTV differed by race/ethnicity?
dti How has median DTI changed?
dti-cc-re For conventional conforming loans, how has median DTI differed by race/ethnicity?
dti-fha-re For FHA loans, how has median DTI differed by race/ethnicity?
denials How have denial rates changed?
denials-cc-re For conventional conforming loans, how have denial rates differed by race/ethnicity?
denials-fha-re For FHA loans, how have denial rates differed by race/ethnicity?
interest-rates How have median interest rates changed?
interest-rates-cc-re For conventional conforming loans, how have median interest rates differed by race/ethnicity?
interest-rates-fha-re For FHA loans, how have median interest rates differed by race/ethnicity?
tlc How have median total loan costs changed?
tlc-cc-re For conventional conforming loans, how have median total loan costs differed by race/ethnicity?
tlc-fha-re For FHA loans, how have median total loan costs differed by race/ethnicity?