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
- Users must reset their password every 90 days. This 90 days is from when the account's password was last set.
- Passwords must:
- Be at least 12 characters
- Have at least 1 uppercase character
- Have at least 1 lowercase character
- Have at least 1 numerical character
- Have at least 1 special character
- Not be the same as your username
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:
- 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.
- 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.
- 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.
- Check the status of the Submission: If a Submission triggers Syntactical or Validity Edits, a corrected file must be uploaded.
- Validate Quality Edits: Review any Quality Edits that have been triggered and confirm that the submitted data are correct.
- Validate Macro Edits: Review any Macro Edits that have been triggered and confirm that the submitted data are correct.
- 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.
- 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.
- 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.
- 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.
- Check the status of the Submission: If a Submission triggers Syntactical or Validity Edits, a corrected file must be uploaded.
- Validate Quality Edits: Review any Quality Edits that have been triggered and confirm that the submitted data are correct.
- Validate Macro Edits: Review any Macro Edits that have been triggered and confirm that the submitted data are correct.
- 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:
- Documentation
- Modified LAR
- Institution Register Summaries
- Dynamic National Loan-Level Dataset
- Snapshot National Loan-Level Dataset
- Disclosure Reports
- Aggregate Reports
- 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
- Nationwide Aggregations
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.
- Aggregations
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.
- Nationwide CSV
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.
- CSV
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 = Originated2 = Approved Not Accepted8 = Pre-approval request approved but not Accepted3 , 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 = false1 = 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
series
xLabel
yLabel
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? |