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

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 filter, along with either a geographic or LEI filter, 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 filter, along with either a geographic or LEI filter, are required when calling this endpoint.

Supported Geographic Filters

HMDA Data Filters

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

Aggregation Example

Example Request and Response

Request:

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

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

CSV Example

Example Request and Response

Request:

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

CSV Response:

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

GET CSV file with the following parameters

HMDA Filers

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

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

HMDA Filer Parameters

HMDA Filers Example

Example Request and Response:

Request:

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

JSON Response:

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

The example to the right allows you to get a list of filers from 2018 that reported HMDA Data in Maryland and DC.

GET with the following parameters

HMDA Filing

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

Example Request

  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}}'

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.

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 incremented.
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 errors, syntactical edits 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

JSON Status Code 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": ""
}

In order to track the status of a filing for a financial institution, the following states are captured by the backend:

Endpoints

Start a Filing

Example Request and Response

Request:

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. In the production HMDA filing application this will have already been created. 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.

Get a Filing

Example Request and Response

Request:
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": []
}

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

Create a Submission

Example Request and Response

Request:

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

JSON Response:

{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2018",
        "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.

Get the Latest Submission

Example Request and Response

Request:

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": 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.

Upload a File

Example Request and Response

Request:

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

JSON Response:

{
    "id": {
        "lei": "B90YWS6AFX2LGWOXJ1LD",
        "period": "2018",
        "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.

View Parsing Errors

Example Request and Response

Request:

curl -X POST \
  "https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/2018/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/2018/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.

View All Edits

Example Request and Response

Request:

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

Returns a summary of all edits triggered by an upload in a submission.

View Edit Details

Example Request and Response

Request:

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"
   }
}

Returns more information about a specific edit including a list of lines that triggered the edit and the relevant fields from those lines.

Verify Quality Edits

Example Request and Response

Request:

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."
    }
}

Verify that the uploaded data is correct and that the reported quality edits are not relevent to the submission.

Verify Macro Edits

Example Request and Response

Request:

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."
    }
}

Verify that the uploaded data is correct and that the reported macro edits are not relevent to the submission.

Sign a Submission

Example Request and Response

Request:

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

Get Sign receipt

Example Request and Response

Request:

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

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."
    }
}

Quarterly Filing

Example Request and Request

Request:

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": "",
    "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.

Public Data Verification

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, the parsed TS object is returned in JSON format.

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.

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"
}'

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.

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.

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=<PATH>/<FILENAME>.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.

Validate a HMDA File

Example Request and Response

Request:

curl -X OPTIONS \
"https://ffiec.cfpb.gov/v2/public/hmda/validate" \
-F file=@<PATH>/<FILENAME>.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.

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.

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:

Batch Ratespreads

Example Request and Response

Request:

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

CSV Response:

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:

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 accepts multiple ULIs, with checkdigits, in CSV format and returns whether they are 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 generate a single check digit.

Batch Check Digit Generation

Example Request and Response

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

 Request Payload:

B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R87
95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS

 CSV Response:

loanId,checkDigit,uli
B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R87,51,B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R8751
95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS,92,95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92

POST request to generate batch check digits.

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.

Batch Check Digit Validation

Example Request and Response

Request:

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

Request Payload

95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92
B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89

CSV Response

uli,isValid
95GVQQ61RS6CWQF0SZD9F4VRXNN1OCVXHP1JURF9ZJS92,true
B90YWS6AFX2LGWOXJ1LDNIXOQ6O0000SLR6FSJJ5R89,false

POST request to batch validate check digits.