NAV

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

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.

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.

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.

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

Geography Variable Name Format
MSA/MD msamds Five Digit MSA/MD Code
State states Two Letter State Abbreviation (Eg. AL for Alabama)
County counties Five Digit County FIPS Code

HMDA Data Filters

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

Variable Name Options
years 2018,2019
actions_taken 1,2,3,4,5,6,7,8
construction_methods 1,2
dwelling_categories Single Family (1-4 Units):Site-Built,
Multifamily:Site-Built,
Single Family (1-4 Units):Manufactured
Multifamily:Manufactured
ethnicities Hispanic or Latino
Not Hispanic or Latino,
Joint,
Ethnicity Not Available,
Free Form Text Only
lien_statuses 1,2
loan_products Conventional:First Lien,
FHA:First Lien,
VA:First Lien,
FSA/RHS:First Lien,
Conventional:Subordinate Lien,
FHA:Subordinate Lien,
VA:Subordinate Lien,
FSA/RHS:Subordinate Lien
loan_purposes 1,2,31,32,4,5
loan_types 1,2,3,4
races Asian,
Native Hawaiian or Other Pacific Islander,
Free Form Text Only,
Race Not Available,
American Indian or Alaska Native,
Black or African American,
2 or more minority races,
White,
Joint
sexes Male,
Female,
Joint,
Sex Not Available
total_units 1,2,3,4,5-24,25-49,50-99,100-149,>149

Aggregation Example

Example Request and Response

Request:

curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations?states=MD&years=2018&actions_taken=5,6&races=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

var value
years 2018
states MD
actions_taken 5,6
races Asian

CSV Example

Example Request and Response

Request:

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

CSV Response:


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

GET CSV file with the following parameters

var value
states CA, MD, DC
years 2018
action_taken 5

HMDA Filers

GET https://ffiec.cfpb.gov/v2/data-browser-api/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

Parameter Name Options
years CSV list of years (example: 2018,2019)
states two letter state code
msamds 5 digit integer code
counties 5 digit integer code

HMDA Filers Example

Example Request and Response:

Request:

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

JSON 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

var value
years 2018
states MD, DC

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.

Method POST
URL https://ffiec.cfpb.gov/auth/realms/hmda2/protocol/openid-connect/token
Payload client_id=hmda2-api
grant_type=password
username={{username}}%40{{bank_domain}}
password={{password}}

Postman Collection

The HMDA Postman Collection has been prepared to simplify the process of using the HMDA Platform Filing APIs.

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

Filing Process

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

  1. Create a Filing: These are unique per institution per filing season and are created by the HMDA-Ops teams in preperation for each filing season.
  2. Create a Submission: Submissions are the primary object in a HMDA Filing. They are created within a filing and each is able to accept a single file upload. Many submissions can be created for a filing and they carry an id which is 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:

Code Message Description
1 No data has been uploaded yet. The filing period is open and available to accept HMDA data. Make sure your data is in a pipe-delimited text file.
2 Your file is uploading. Your file is currently being uploaded to the HMDA Platform.
3 Your file has been uploaded. Your data is ready to be analyzed.
4 Checking the formatting of your data. Your file is being analyzed to ensure that it meets formatting requirements specified in the HMDA Filing Instructions Guide.
5 Your data has formatting errors. Review these errors and update your file. Then, upload the corrected file.
6 Your data is formatted correctly. Your file meets the formatting requirements specified in the HMDA Filing Instructions Guide. Your data will now be analyzed for any edits.
7 Your data is being analyzed. Your data has been uploaded and is being checked for any edits.
8 Your data has been analyzed for Syntactical and Validity Errors. Your file has been analyzed and does not contain any Syntactical or Validity errors.
9 Your data has syntactical and/or validity edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until the file is corrected and re-uploaded.
10 Your data has been analyzed for Quality Errors. Your file has been analyzed, and does not contain quality errors.
11 Your data has quality edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
12 Your data has been analyzed for macro errors. Your file has been analyzed, and does not contain macro errors.
13 Your data has macro edits that need to be reviewed. Your file has been uploaded, but the filing process may not proceed until edits are verified or the file is corrected and re-uploaded.
14 Your data is ready for submission. Your financial institution has certified that the data is correct, but it has not been submitted yet.
15 Your submission has been accepted. This completes your HMDA filing process for this year. If you need to upload a new HMDA file, the previously completed filing will not be overridden until all edits have been cleared and verified, and the new file has been submitted.
-1 An error occurred while submitting the data. Please re-upload your file.

Endpoints

Start a Filing

Example Request and Response

Request:

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

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

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.

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}
Headers Authorization: Bearer {{access_token}}

Create a Submission

Example Request and Response

Request:

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

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

Get the Latest Submission

Example Request and Response

Request:

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

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/latest
Headers Authorization: Bearer {{access_token}}

Upload a File

Example Request and Response

Request:

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

Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}
Headers Authorization: Bearer {{access_token}}, 'Content-Type': multipart/form-data
Payload LAR file

View Parsing Errors

Example Request and Response

Request:

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

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/parseErrors
Headers Authorization: Bearer {{access_token}}

View All Edits

Example Request and Response

Request:

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

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/edits
Headers Authorization: Bearer {{access_token}}

View Edit Details

Example Request and Response

Request:

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

Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/edits/{{edit_code}}
Headers Authorization: Bearer {{access_token}}

Verify Quality Edits

Example Request and Response

Request:

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

Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/edits/quality
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Verify Macro Edits

Example Request and Response

Request:

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

Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/edits/macro
Headers Authorization: Bearer {{access_token}}
Body {"verified": true}

Sign a Submission

Example Request and Response

Request:

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

Method POST
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/sign
Headers Authorization: Bearer {{access_token}}
Body {"signed": true}

Get Sign receipt

Example Request and Response

Request:

curl -X GET \
  "https://ffiec.cfpb.gov/v2/filing/institutions/B90YWS6AFX2LGWOXJ1LD/filings/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."
    }
}
Method GET
Endpoint https://ffiec.cfpb.gov/v2/filing/{{year}}/submissions/{{sequenceNumber}}/sign
Headers Authorization: Bearer {{access_token}}

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.

Method POST
URL https://ffiec.cfpb.gov/v2/public/ts/parse
Payload Pipe delimited TS
Return JSON

Validate TS

Example Request and Response

Request:

  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/ts/validate/2018" \
  -H 'Content-Type: application/json' \
  -d '{
  "ts" : "1|Bank 0|2018|4|Jane|111-111-1111|janesmith@bank.com|123 Main St|Washington|DC|20001|9|100|99-999999|10Bx939c5543TqA1144M"
}'

JSON Response:

{
    "syntactical": {
        "errors": []
    },
    "validity": {
        "errors": []
    },
    "quality": {
        "errors": []
    }
}

This endpoint runs parsing and a specific year's edit checks on a Transmittal Sheet (TS). It returns edit details if the TS is able to be parsed or parsing errors if not.

Note: Some edit checks require institution data. These checks are not run in any public APIs.

Method POST
URL https://ffiec.cfpb.gov/v2/public/ts/validate/{{year}}
Payload Pipe delimited TS
Return JSON

Single LAR Verification

These endpoints are used to parse and and run edits on a LAR. Use parse to check for parsing errors and validate/{{year}} to check for syntactical, validity, and quality edits.

Parse a LAR

Example Request and Response

Request:

  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/lar/parse" \
  -H 'Content-Type: application/json' \
  -d '{ "lar": "2|10Bx939c5543TqA1144M|10Bx939c5543TqA1144M999143X38|20180721|1|1|1|1|1|110500|1|20180721|123 Main St|Beverly Hills|CA|90210|06037|06037264000|1|1|1|1|1||1|1|1|1|1||3|3|5|7|7|7|7||||5|7|7|7|7||||3|3|1|1|3|3|30|30|36|1|0.428|1|1|750|750|1|9|1|9|10|10|10|10||2399.04|NA|NA|NA|NA|4.125|NA|42.95|80.05|360|NA|1|2|1|1|350500|1|1|5|NA|1|1|12345|1|1|1|1|1||1|1|1|1|1||1|1|1"
}'

Response:

  {
    "larIdentifier": {
        "id": 2,
        "LEI": "10BX939C5543TQA1144M",
        "NMLSRIdentifier": "12345"
    },
    "loan": {
        "ULI": "10Bx939c5543TqA1144M999143X38",
        "applicationDate": "20180721",
        "loanType": 1,
        "loanPurpose": 1,
        "constructionMethod": 1,
        "occupancy": 1,
        "amount": 110500.0,
        "loanTerm": "360",
        "rateSpread": "0.428",
        "interestRate": "4.125",
        "prepaymentPenaltyTerm": "NA",
        "debtToIncomeRatio": "42.95",
        "combinedLoanToValueRatio": "80.05",
        "introductoryRatePeriod": "NA"
    },
    "larAction": {
        "preapproval": 1,
        "actionTakenType": 1,
        "actionTakenDate": 20180721
    },
    "geography": {
        "street": "123 Main St",
        "city": "Beverly Hills",
        "state": "CA",
        "zipCode": "90210",
        "county": "06037",
        "tract": "06037264000"
    },
    "applicant": {
        "ethnicity": {
            "ethnicity1": 1,
            "ethnicity2": 1,
            "ethnicity3": 1,
            "ethnicity4": 1,
            "ethnicity5": 1,
            "otherHispanicOrLatino": "",
            "ethnicityObserved": 3
        },
        "race": {
            "race1": 5,
            "race2": 7,
            "race3": 7,
            "race4": 7,
            "race5": 7,
            "otherNativeRace": "",
            "otherAsianRace": "",
            "otherPacificIslanderRace": "",
            "raceObserved": 3
        },
        "sex": {
            "sex": 1,
            "sexObserved": 3
        },
        "age": 30,
        "creditScore": 750,
        "creditScoreType": 1,
        "otherCreditScoreModel": "9"
    },
    "coApplicant": {
        "ethnicity": {
            "ethnicity1": 1,
            "ethnicity2": 1,
            "ethnicity3": 1,
            "ethnicity4": 1,
            "ethnicity5": 1,
            "otherHispanicOrLatino": "",
            "ethnicityObserved": 3
        },
        "race": {
            "race1": 5,
            "race2": 7,
            "race3": 7,
            "race4": 7,
            "race5": 7,
            "otherNativeRace": "",
            "otherAsianRace": "",
            "otherPacificIslanderRace": "",
            "raceObserved": 3
        },
        "sex": {
            "sex": 1,
            "sexObserved": 3
        },
        "age": 30,
        "creditScore": 750,
        "creditScoreType": 1,
        "otherCreditScoreModel": "9"
    },
    "income": "36",
    "purchaserType": 1,
    "hoepaStatus": 1,
    "lienStatus": 1,
    "denial": {
        "denialReason1": 10,
        "denialReason2": 10,
        "denialReason3": 10,
        "denialReason4": 10,
        "otherDenialReason": ""
    },
    "loanDisclosure": {
        "totalLoanCosts": "2399.04",
        "totalPointsAndFees": "NA",
        "originationCharges": "NA",
        "discountPoints": "NA",
        "lenderCredits": "NA"
    },
    "nonAmortizingFeatures": {
        "balloonPayment": 1,
        "interestOnlyPayment": 2,
        "negativeAmortization": 1,
        "otherNonAmortizingFeatures": 1
    },
    "property": {
        "propertyValue": "350500.0",
        "manufacturedHomeSecuredProperty": 1,
        "manufacturedHomeLandPropertyInterest": 1,
        "totalUnits": 5,
        "multiFamilyAffordableUnits": "NA"
    },
    "applicationSubmission": 1,
    "payableToInstitution": 1,
    "AUS": {
        "aus1": 1,
        "aus2": 1,
        "aus3": 1,
        "aus4": 1,
        "aus5": 1,
        "otherAUS": ""
    },
    "ausResult": {
        "ausResult1": 1,
        "ausResult2": 1,
        "ausResult3": 1,
        "ausResult4": 1,
        "ausResult5": 1,
        "otherAusResult": ""
    },
    "reverseMortgage": 1,
    "lineOfCredit": 1,
    "businessOrCommercialPurpose": 1
}

This endpoint runs parsing on a single Loan Application Register (LAR). The endpoint returns a list of parsing errors in JSON format. If the LAR is valid it returns the parsed LAR object in JSON format.

Method POST
URL https://ffiec.cfpb.gov/v2/public/lar/parse
Payload Pipe delimited LAR
Return JSON

Validate a LAR

Example Request and Response

Request
  curl -X POST \
  "https://ffiec.cfpb.gov/v2/public/lar/validate/2018" \
  -H 'Content-Type: application/json' \
  -d '{"lar": "2|B90YWS6AFX2LGWOXJ1LD|B90YWS6AFX2LGWOXJ1LD0KQ78F1Q02LVT4VCYK1G3D253|20180613|3|2|2|2|3|218910|5|20181031|1234 Hocus Potato Way|Tatertown|NM|14755|35003|35003976400|1|13||11||KE0NW|1|||||NA2IJJ7VBBQ15DTFRNK1PVWOPOXL3NH1PHUMN7S2J4|2|2|7|||||E120FYAU7BTSC3P51IL87C97W3N9VT791BMJI57RLJQSHOFDTUD7PQSPGHQ69D7I2P8JBDCBUIGRLX2BUS7SJR|DOOOI8UXY9PZDSRVFKP91CUQG95E88Y22KDR1AI3|1K1JINAYSIHCWBGJW3KOHU5D5TSK1Z61SUT5M9WQVWOHX|27|24|41|43|2|MS1LKLX7XZRKL23TV01I49RADZGUN0QY5AG9H4BJCVFTA4ZQ1EJUS1376QJXD87ZZDN5EFZIUWB8SK5EU34RVGOVTE|Y083OZN1VFT6B2XGL397ABL0Z4EV4CD45I7ZJ7FRSXXL4BRMKVPR5UCVV0K6IDLP7WLCBZAQ5KXT69PNE9PWQKCPKJB|UV0FTHG00G8WM65I7591IJYP9TEMXMDCVGZYRJTBUBBKEZI65HGL9ML|3|2|2|2|1|1|75|4|NA|0|NA|3|2|8888|8888|9||9||10|||||NA|NA|NA|NA|NA|NA|32|NA|NA|256|29|1111|1111|1111|1111|NA|3|2|16|Exempt|2|2|NA|3|1|5|1||DOREBESQSW1QT58SD2OZTHQUGXLSKCAJYZ63NJE2MUIAFQL4KW6PU26YSU786GT0IMCWWKCN25Y7KU0VLU0PPKWR8G6DKWI9BANPIE9I2ZZ5XDUX0TBAY4XFRFQZF087WS9ESTAKIV5V9HSZ2VXW7J5JMGPP4CGYA51BK68T57NN4KTKJVXIQMFXBTN5E3LGKKX3LITQ4C7OPFJ|7|6|5|5|||1111|2|1111"
}'

JSON Response
  {
    "syntactical": {
        "errors": []
    },
    "validity": {
        "errors": []
    },
    "quality": {
        "errors": [
            {
                "edit": "Q618",
                "description": "\"If Construction Method equals 2, then Manufactured Home Secured Property Type generally should not be 3.\""
            },
            {
                "edit": "Q631",
                "description": "\"If Loan Type equals 2, 3 or 4, then Total Units generally should be less than or equal to 4.\""
            },
            {
                "edit": "Q632",
                "description": "\"If Automated Underwriting System: 1; Automated Underwriting System: 2; Automated Underwriting System: 3; Automated Underwriting System: 4; or Automated Underwriting System: 5 equals 3, then the corresponding Automated Underwriting System Result: 1; Automated Underwriting System Result: 2; Automated Underwriting System Result: 3; Automated Underwriting System Result: 4; or Automated Underwriting System Result: 5 should equal 8 or 13.\""
            }
        ]
    }
}

This endpoint runs parsing and a specific year's edit checks on a Loan Application Register (LAR). It returns edit details if the LAR is able to be parsed or parsing errors if not.

Note: Some edit checks require institution data. These checks are not run in any public APIs. Macro edits are also not run this endpoint checks only a single LAR.

Method POST
URL https://ffiec.cfpb.gov/v2/public/lar/validate/{{year}}
Payload Pipe delimited LAR
Return JSON

Full HMDA File Verification

The following endpoints can be used to parse and run edit checks on a full HMDA file.

Parse a HMDA File

Example Request and Response

Request:

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

Method OPTIONS
URL https://ffiec.cfpb.gov/v2/public/hmda/parse
Payload HMDA file
Return JSON

Validate a HMDA File

Example Request and Response

Request:

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

Method OPTIONS
URL https://ffiec.cfpb.gov/v2/public/hmda/validate/{{year}}
Payload HMDA file
Return JSON

Rate Spread

Rate Spread API

The following endpoints allow users to provide loan information and returns the associated ratespread either one at a time in JSON format or in a batch in CSV format.

This API is what powers the Rate Spread Calculator application.

Note: The response is either a number representing the rate spread or "NA".

Rate Spread Parameters

The following parameters must be provided when using any ratespread API. These are provided in either JSON or CSV format.

Variable Type Accepted Values
action_taken_type integer 1 = Originated
2 = Approved Not Accepted
8 = Pre-approval request approved but not Accepted
3, 4, 5, 6 or 7 will result in NA
loan_term integer Range from 1 - 50
amortization_type String FixedRate or VariableRate
apr double The annual Percentage Rate on the loan, eg 6.0
lock_in_date date YYYY-MM-DD
reverse_mortgage integer 2 = false
1 = true, will result in NA

Single Ratespread

Example Request and Response

Request:

curl -X POST "https://ffiec.cfpb.gov/public/rateSpread" -H "Content-Type: application/json" -d '{ "actionTakenType": 1, "loanTerm": 30, "amortizationType": "FixedRate", "apr": 6.0, "lockInDate": "2017-11-20", "reverseMortgage": 2 }'

JSON Response:

{"rateSpread":"2.010"}

This endpoint accepts loan data in JSON format and returns a JSON object containing the associated ratespread.

POST https://ffiec.cfpb.gov/public/rateSpread

The JSON example contains the following parameters:

Variable Value
actionTakenType 1
loanTerm 30
amortizationType FixedRate
apr 6.0
lockInDate 2017-11-20
reverseMortgage 2

Batch Ratespreads

Example Request and Response

Request:

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

CSV Response:

action_taken_type,loan_term,amortization_type,apr,lock_in_date,reverse_mortgage,rate_spread
1,30,FixedRate,6.0,2017-11-20,2,2.010
1,30,VariableRate,6.0,2017-11-20,2,2.150

In order to batch caluculate ratespreads the csv endpoint can be used. This endpoint accepts a CSV file of ratespread data and returns a CSV file with a new column for the ratespread.

POST https://ffiec.cfpb.gov/public/rateSpread/csv

The CSV file example contains the following contents:

1 30 FixedRate 6.0 2017-11-20
1 30 VariableRate 6.0 2017-11-20

Check Digit

The following endpoints allow users to generate and validate check digits either one at a time in JSON format or in a batch in CSV format.

This API is what powers the Check Digit Tool.

Check Digit Endpoints

Single Checkdigit Generation

POST https://ffiec.cfpb.gov/v2/public/uli/checkDigit

This endpoint takes a single ULI in JSON format and returns a single two-digit check digit in JSON format.

Batch Checkdigit Generation

POST https://ffiec.cfpb.gov/v2/public/uli/checkDigit/csv

This endpoint takes multiple ULIs in CSV format and returns two-digit check digits in CSV format.

Single Checkdigit Validation

POST https://ffiec.cfpb.gov/v2/public/uli/validate

This endpoint takes a single ULI with check digits in JSON format and returns whether it is valid in JSON format.

Batch Checkdigit Validation

POST https://ffiec.cfpb.gov/v2/public/uli/validate/csv

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

Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/checkDigit
Payload JSON
Return JSON

Batch Check Digit Generation

Example Request and Response

 Request:
curl -X POST \
"https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
-F file=@<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.

Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/checkDigit/csv
Payload CSV file as shown bellow
Return CSV

Single Check Digit Validation

Example Request and Response

Request:

curl POST 'https://ffiec.cfpb.gov/v2/public/uli/validate' \
--header 'Content-Type: application/json' \
--data-raw '{"uli": "EILKZAIZF6TX4HB8ZDX33H54"}'

JSON Response:

{
  "isValid": true
}

POST request to validate a single check digit.

Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/validate
Payload JSON
Return JSON

Batch Check Digit Validation

Example Request and Response

Request:

curl -X POST \
"https://ffiec.cfpb.gov/v2/public/uli/validate/csv" \
-F file=@<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.

Method POST
URL https://ffiec.cfpb.gov/v2/public/uli/validate/csv
Payload CSV file as shown bellow
Return CSV