Skip to main content

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.

VariableTypeAccepted Values
action_taken_typeinteger1 = Originated
2 = Approved Not Accepted
8 = Pre-approval request approved but not Accepted
3, 4, 5, 6 or 7 will result in NA
loan_termintegerRange from 1 - 50
amortization_typeStringFixedRate or VariableRate
aprdoubleThe annual Percentage Rate on the loan, eg 6.0
lock_in_datedateYYYY-MM-DD
reverse_mortgageinteger2 = false
1 = true, will result in NA

Single Ratespread

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

Method: POST
Endpoint: https://ffiec.cfpb.gov/public/rateSpread
Payload: { "actionTakenType": "{{actionTakenType}}", "loanTerm": "{{loanTer}}", "amortizationType": "{{FixedRate/VariableRate}}", "apr": "{apr}", "lockInDate": "{{yyyy-mm-dd}}", "reverseMortgage": "{1/2}" }

Example

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": "2023-11-20", "reverseMortgage": 2 }'

JSON Response:

{"rateSpread":"-1.420"}

Batch Ratespreads

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.

Method: POST 
Endpoint: https://ffiec.cfpb.gov/public/rateSpread/csv`
Payload: CSV File as shown below

Example

Request:

echo "1,30,FixedRate,6.0,2023-11-20,2
1,30,VariableRate,6.0,2023-11-20,2" > exampleFile.csv

curl -X POST "https://ffiec.cfpb.gov/public/rateSpread/csv" --form 'file=@"exampleFile.csv"'

The CSV file example contains the following contents:

130FixedRate6.02023-11-202
130VariableRate6.02023-11-202

Response:

1,30,FixedRate,6.0,2023-11-20,2,-1.420
1,30,VariableRate,6.0,2023-11-20,2,-1.250

ffiec.cfpb.gov

An official website of the CFPB's HMDA  v3.1.1b

Looking for U.S. government information and services?  
Visit USA.gov