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 Filing API

The following documentation addresses the process for filing a HMDA file and the associated APIs.

This API is what powers the HMDA Filing Platform application

Authorization

To file HMDA data using the API, a bearer authorization token is required for all 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}}

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 mirriored in the submission status codes:

1. Create a Filing: These are unique per institution per filing season and are created by the HMDA-Ops teams in preperation for each filing season.
2. Create a Submission: Submissions are the primary object in a HMDA Filing. They are created within a filing and each is able to accept a single file upload. Many submissions can be created for a filing and they carry an id which is incrimented.
3. Upload a File: A file is then uploaded to the submission which was created. Only one file can be uploaded to a submission. To upload a new file you must create a new submission.
4. Check the status of the Submission the file was uploaded to: If parsing syntactical or validity edits are triggered a new file must be uploaded.
5. Validate Quality Edits: Review triggered Quality Edits and confirm the submitted data are correct.
6. Validate Macro Edits: Review triggered Macro Edits and confirm the submitted data are correct.
7. Sign the Submission: Perform final review of the data and complete the HMDA filing.

Object Hierarchy

Submission Status

As a submission represents a HMDA filing the submission status is the best way to see the state of a HMDA filing. It will be useful to query for the submission status often throughout the process of uploading and checking edits for a submission.

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 backend:

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/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 evey filing period, you must begin by starting a filing. This only needs to be done once per filing season. In the production HMDA filing application this will have already been creaed. 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/{{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/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/{{year}}
Headers	Authorization: Bearer {{access_token}}

Create a Submission

Example Request and Response

Request:
curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/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 number.

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 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 number.

Method	POST
Endpoint	https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions
Headers	{{access_token}}

Get the Latest Submission

Example Request and Response

Request:
curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/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 it's sequence number and status.

Method	GET
Endpoint	https://ffiec.cfpb.gov/v2/filing/{{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/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/{{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/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/{{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/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/{{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/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 more 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/{{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/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/{{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/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/{{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/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/{{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/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/{{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/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/{{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/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.

Beta HMDA Filing API

The following documentation addresses the process for testing in the HMDA Platform Beta environment and the associated Beta APIs.

The HMDA Beta Filing Platform serves as a test environment for the latest builds of the Hmda Platform backend service and Frontend UI. It is in no way linked to the official submission of filing data.

Authorization

To test a HMDA filing using the Beta API, a bearer authorization token is required for all Beta 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: When testing the filing process via the HMDA Beta platform, this filing process is for test purposes only and is NOT acknowledged as an official filing. If you wish to submit official data to the HMDA Platform, please use the production platform application: 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 Beta APIs.

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

Filing Process

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

Please note: When testing the filing process via the HMDA Beta platform, the signing of submissions via the HMDA Beta platform is prohibted as it is not considered an official submission of data and to avoid any confusion in this regard.

1. Create a Filing: These are unique per institution per filing season and are created by the HMDA-Ops teams in preperation for each filing season.
2. Create a Submission: Submissions are the primary object in a HMDA Filing. They are created within a filing and each is able to accept a single file upload. Many submissions can be created for a filing and they carry an id which is incrimented.
3. Upload a File: A file is then uploaded to the submission which was created. Only one file can be uploaded to a submission. To upload a new file you must create a new submission.
4. Check the status of the Submission the file was uploaded to: If parsing syntactical or validity edits are triggered a new file must be uploaded.
5. Validate Quality Edits: Review triggered Quality Edits and confirm the submitted data are correct.
6. Validate Macro Edits: Review triggered Macro Edits and confirm the submitted data are correct.

Object Hierarchy

Submission Status

As a submission represents a HMDA filing the submission status is the best way to see the state of a HMDA filing. It will be useful to query for the submission status often throughout the process of uploading and checking edits for a submission.

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 backend:

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/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 evey filing period, you must begin by starting a filing. This only needs to be done once per filing season. In the production HMDA filing application this will have already been creaed. 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/{{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/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/{{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/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 number.

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 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 number.

Method	POST
Endpoint	https://ffiec.beta.cfpb.gov/v2/filing/{{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/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 it's sequence number and status.

Method	GET
Endpoint	https://ffiec.beta.cfpb.gov/v2/filing/{{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/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/{{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/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/{{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/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/{{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/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 more 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/{{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/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/{{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/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/{{year}}/submissions/{{sequenceNumber}}/edits/macro
Headers	Authorization: Bearer {{access_token}}
Body	{"verified": true}

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

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/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/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/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/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/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/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/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/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/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