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.
Data Browser API
The data browser api enables developers to interact with HMDA data. The API will return the data in JSON or CSV.
Note: depending on the query, files might take a while to generate and may not open using conventional spread sheet applications.
Endpoints
Use data-browser-api/view/
for the endpoints below. Each endpoint could be called on nationwide data or on specific states/msamds/counties/ageapplicant. If nationwide
is not specified, state(s) or msamds or counties or ageapplicant must be selected. A call made with the nationwide endpoint will discard any state(s) or msamds if present. For state, use 2 character state name. For msamd use a 5 digit integer. For counties use 5 digit county code.
- Aggregations
The aggregation
endpoint can be used to generated JSON reports.
- CSV
The csv
endpoint can be used to generate CSV reports. The file will be streamed.
- Institutions
The filers
endpoint will show a list of all institutions available.
Filters
Data request could be filtered based on the following parameters. Multiple options are acceptable.
Variable Name | Options |
---|---|
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
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": {
"year": "2018",
"state": "MD",
"actions_taken": "5,6",
"races": "White,Asian,Joint"
},
"aggregations": [
{
"count": 243,
"sum": 9.4325E7,
"actions_taken": "6",
"races": "Joint",
"state": "MD",
"year": "2018"
},
{
"count": 716,
"sum": 2.5435E8,
"actions_taken": "6",
"races": "Asian",
"state": "MD",
"year": "2018"
},
{
"count": 7505,
"sum": 2.323145E9,
"actions_taken": "6",
"races": "White",
"state": "MD",
"year": "2018"
},
{
"count": 165,
"sum": 4.7595E7,
"actions_taken": "5",
"races": "Joint",
"state": "MD",
"year": "2018"
},
{
"count": 679,
"sum": 1.90835E8,
"actions_taken": "5",
"races": "Asian",
"state": "MD",
"year": "2018"
},
{
"count": 5237,
"sum": 1.241115E9,
"actions_taken": "5",
"races": "White",
"state": "MD",
"year": "2018"
}
]
}
GET
JSON with the following parameters
var | value |
---|---|
years | 2018 |
states | MD |
actions_taken | 5,6 |
races | White, Asian, Joint |
CSV Example
Example
curl -L "https://ffiec.cfpb.gov/v2/data-browser-api/view/csv?states=CA,MD,DC&years=2018&actions_taken=5"
CSV file
GET
CSV file with the following parameters
var | value |
---|---|
states | CA, MD, DC |
years | 2018 |
action_taken | 5 |
Filers
The filers
endpoint takes the following 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 |
Filers Example
Example
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
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.
HMDA Filing API
The following are HMDA Filling API endpoints
Authorization
To file HMDA data using the API, an 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.
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}} |
Return | JSON with access_token |
Postman Collection
The HMDA Postman Collection can be used to file via HMDA Filing API.
Endpoints
Use https://ffiec.cfpb.gov/v2/filing/institutions/{lei}/filings
as a prefix for the following endpoints.
Start a Filing
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2019" \
-H 'Authorization: Bearer {{access_token}}' \
JSON Response
{
"filing": {
"period": "2018",
"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. 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 | /{{year}} |
Get a Filing
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2019" \
-H 'Authorization: Bearer {{access_token}}' \
JSON Response
{
"filing": {
"period": "2018",
"lei": "B90YWS6AFX2LGWOXJ1LD",
"status": {
"code": 2,
"message": "in-progress"
},
"filingRequired": true,
"start": 1572378187454,
"end": 0
},
"submissions": []
}
Method | GET |
Endpoint | /{{year}} |
Create Submission
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/submissions" \
-H 'Authorization: Bearer {{access_token}}' \
More than one submissions 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": "2018",
"sequenceNumber": 4
},
"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": ""
}
Method | POST |
Endpoint | /{{year}}/submissions |
Payload | {{access_token}} |
Return | Returns JSON with {{sequenceNumber}} |
Get latest submission
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/submissions/latest" \
-H 'Authorization: Bearer {{access_token}}' \
JSON Response
{
"id": {
"lei": "B90YWS6AFX2LGWOXJ1LD",
"period": "2018",
"sequenceNumber": 1520
},
"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
}
Method | GET |
Endpoint | /{{year}}/submissions/latest |
Return | Details for the latest submission |
Upload File
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2019/submissions/13" \
-H 'Authorization: Bearer {{access_token}}' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file=<file.csv>
JSON Response
{
"id": {
"lei": "B90YWS6AFX2LGWOXJ1LD",
"period": "2018",
"sequenceNumber": 55
},
"status":{
"code": 3,
"message": "Your file has been uploaded.",
"description": "Your data is ready to be analyzed."
},
"start": 1572372016130,
"end": 0,
"fileName": "",
"receipt": ""
}
Method | POST |
Endpoint | /{{year}}/submissions/{{sequenceNumber}} |
Headers | 'Content-Type': multipart/form-data |
Payload | LAR file |
View parse errors
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/submissions/24/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/2018/submissions/24/parseErrors{rel}",
"self": "?page=1",
"first": "?page=1",
"prev": "?page=1",
"next": "?page=0",
"last": "?page=0"
}
}
Method | GET |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/parseErrors |
View all edits
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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
}
}
Method | GET |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/edits |
View edit details
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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/2018/submissions/24/edits/Q631{rel}",
"self": "?page=1",
"first": "?page=1",
"prev": "?page=1",
"next": "?page=2",
"last": "?page=3"
}
}
Method | GET |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/edits/{{edit_code}} |
Verify Quality Edits
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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."
}
}
Method | POST |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/edits/quality |
Body | {"verified": true} |
Verify Macro Edits
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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."
}
}
Method | POST |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/edits/macro |
Body | {"verified": true} |
Sign a Submission
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/submissions/55/sign" \
-H 'Authorization: Bearer {{access_token}}' \
-d '{"verified": true}'
JSON Response
{
"email": "user@example.com",
"timestamp": 1572375004080,
"receipt": "B90YWS6AFX2LGWOXJ1LD-2018-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 | POST |
Endpoint | /{{year}}/submissions/{{sequenceNumber}}/sign |
Body | {"signed": true} |
Get Sign receipt
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/submissions/1520/sign" \
-H 'Authorization: Bearer {{access_token}}' \
-d '{"verified": true}'
JSON Response
{
"email": "user@example.com",
"timestamp": 1572375004080,
"receipt": "B90YWS6AFX2LGWOXJ1LD-2018-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 | /{{year}}/submissions/{{sequenceNumber}}/sign |
Submission Status
Structure
Example
{
"id": {
"lei": "12345abc",
"period": "2018",
"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": ""
}
Every submission will store a SubmissionStatus
object with the following structure:
Key | Type |
---|---|
code | Integer |
message | String |
description | String |
Status Codes
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. |
Quarterly Filing
Example
curl -X GET \
"https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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": "<file_name>",
"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/
.
HMDA Public API
The following are HMDA Public API endpoints that do not require authorization. You may use these public endpoints to help prepare your data for sumbission.
Use public/
for all the follwing endpoints.
TS and LAR Endpoints
Use ts/
and lar/
for the endpoints bellow. Each endpoint could be called to parse and validate TS and LAR respectfully. Use parse
to check for parsing errors and validate/<year>
to check for SVQ (syntactical, validity, quality) errors.
Parse TS Example
Example
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"
}'
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"
}
Method | POST |
URL | https://ffiec.cfpb.gov/v2/public/ts/parse |
Payload | Pipe delimited TS |
Return | JSON |
Validate TS Example
Example
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"
}'
Response
{
"syntactical": {
"errors": []
},
"validity": {
"errors": []
},
"quality": {
"errors": []
}
}
Method | POST |
URL | https://ffiec.cfpb.gov/v2/public/ts/validate/2018 |
Payload | Pipe delimited TS |
Return | JSON |
Parse a LAR Example
Example
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"
}'
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
}
Method | POST |
URL | https://ffiec.cfpb.gov/v2/public/lar/parse |
Payload | Pipe delimited TS |
Return | JSON |
Validate a LAR Example
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/public/lar/validate/2018" \
-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"
}'
Response
{
"syntactical": {
"errors": []
},
"validity": {
"errors": [
"V614-3",
"V614-4",
"V615-2",
"V615-3",
"V628-3",
"V631-3",
"V635-2",
"V635-3",
"V638-2",
"V638-3",
"V657-3",
"V662-1",
"V662-2",
"V667-1",
"V667-2",
"V669-2",
"V669-3",
"V669-4",
"V672-3",
"V672-4",
"V672-5",
"V682-2",
"V689-3",
"V690-3"
]
},
"quality": {
"errors": [
"Q608",
"Q612",
"Q622",
"Q630"
]
}
}
Method | POST |
URL | https://ffiec.cfpb.gov/v2/public/lar/validate/2018 |
Payload | Pipe delimited TS |
Return | JSON |
HMDA Parse
To parse a file, use the hmda/parse
endpoint and a file.
HMDA Parse Example
Example
curl -X OPTIONS \
"https://ffiec.cfpb.gov/v2/public/hmda/parse" \
-F file=@<PATH>/<FILENAME>.txt
Response
{
"validated": []
}
Method | OPTIONS |
URL | https://ffiec.cfpb.gov/v2/public/hmda/parse |
Payload | LAR file |
Return | JSON |
HMDA Validate
To parse and validate a file, use the hmda/validate
endpoint and a file.
HMDA Validate Example
Example
curl -X OPTIONS \
"https://ffiec.cfpb.gov/v2/public/hmda/validate" \
-F file=@<PATH>/<FILENAME>.txt
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"
}
}
]
]
}
Method | OPTIONS |
URL | https://ffiec.cfpb.gov/v2/public/hmda/validate |
Payload | LAR file |
Return | JSON |
Check Digit
To use check digit on a csv file, use the uli/validate/csv
and upload a csv. The respose will list the ULIs along with true
/false
.
Check Digit Example
Example
curl -X POST \
"https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
-F file=@<PATH>/check_digit_sample_file.csv
Response
uli,isValid
95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92,true
B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89,false
Method | POST |
URL | https://ffiec.cfpb.gov/v2/public/validate/csv |
Payload | CSV file as shown bellow |
Return | JSON |
check_digit_sample_file.csv
95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92 |
B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89 |
Rate Spread
Rate Spread API
The /rateSpread
endpoint you can provide information about a loan and have the rate spread calculated via POST
.
Note: The response is either a number representing the rate spread or "NA".
Endpoints
Rate spread has 2 API endpoints, one for submitting JSON and one for CSV.
POST
https://ffiec.cfpb.gov/public/rateSpread
POST
https://ffiec.cfpb.gov/public/rateSpread/csv
JSON Example
Example
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"}
JSON with the following parameters
var | value |
---|---|
actionTakenType | 1 |
loanTerm | 30 |
amortizationType | FixedRate |
apr | 6.0 |
lockInDate | 2017-11-20 |
reverseMortgage | 2 |
CSV File Format
The contents of this file must include the following information:
var | 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 |
CSV Example
Example
curl -X POST "https://ffiec.cfpb.gov/public/rateSpread/csv" -F file=<file.csv>
CSV 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
Example CSV file with contents:
1 | 30 | FixedRate | 6.0 | 2017-11-20 |
1 | 30 | VariableRate | 6.0 | 2017-11-20 |