NAV Navbar

HMDA API Documentation

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

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.

The aggregation endpoint can be used to generated JSON reports.

The csv endpoint can be used to generate CSV reports. The file will be streamed.

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

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