Home/API Docsv1

All Systems Operational

api.homebuyer.com

API Documentation

Access mortgage rates, economic calendar events, and market data programmatically through our REST API.

Introduction

The Homebuyer.com API provides programmatic access to mortgage rates, economic calendar data, and market statistics. Use this API to integrate rate information and upcoming economic events into your applications, newsletters, or data pipelines.

Beta: This API is in public beta. Some parameters are defined but not yet available. Rate limits and features may change.

Base URLs

The API is available at two endpoints that serve identical responses:

https://api.homebuyer.comRecommended

https://homebuyer.com/api/v1Alternative

Authentication

When an API key is configured, all requests must include it. You can pass it in any of these ways:

Header: X-API-Key: your-api-key
Header: Authorization: Bearer your-api-key
Query: ?api_key=your-api-key or ?secret=your-api-key

Request an API key from api@homebuyer.com. Missing or invalid keys receive 401 Unauthorized.

Rate Limits

100

requests per minute

1,000

requests per hour

Responses include cache headers allowing you to cache data for up to 1 hour.

API Reference

Parameters

statestringoptional

2-letter US state codeDefault: CO

ficostringoptional

FICO score tier (1-5)Default: 1

ltvstringoptional

Loan-to-Value tier (1-2)Default: 1

product_typestringoptional

Loan product typeDefault: conventional

occupancystringoptional

Property occupancy typeDefault: primary

property_typestringoptional

Type of propertyDefault: single_family

loan_termstringoptional

Loan term in yearsDefault: 30

loan_purposestringoptional

Purpose of the loanDefault: purchase

Response

rate_30yrnumber

30-year fixed mortgage rate as a percentage

parametersobject

Echo of request parameters with labels

rate_change_weeklynumber | null

Weekly rate change in percentage points

rate_change_linestring | null

Human-readable change line for newsletters (e.g. down 0.125% this week)

last_updatedstring

Date of last rate update (YYYY-MM-DD)

national_average_ratenumber | null

National average 30-year fixed rate (Freddie Mac PMMS); same as freddie_mac_rate

optimal_blue_ratenumber | null

FRED Optimal Blue 30-year rate, ≤80 LTV, 740+ FICO

optimal_blue_last_updatedstring | null

Date of Optimal Blue rate (YYYY-MM-DD)

freddie_mac_ratenumber | null

Freddie Mac PMMS 30-year fixed rate (national average)

freddie_mac_last_updatedstring | null

Date of Freddie Mac rate (YYYY-MM-DD)

disclaimerstring | null

Optional disclaimer for display

metadataobject

API version and documentation link

curl "https://api.homebuyer.com/rates?state=CA&fico=2"

Response

{
  "rate_30yr": 5.25,
  "parameters": {
    "state": "CA",
    "fico_tier": "Tier 2",
    "ltv_tier": "Tier 1",
    "product_type": "Conventional",
    "occupancy": "Primary Residence",
    "property_type": "Single Family",
    "loan_term": "30-Year Fixed",
    "loan_purpose": "Purchase"
  },
  "rate_change_weekly": -0.125,
  "rate_change_line": "down 0.125% this week",
  "last_updated": "2026-01-31",
  "national_average_rate": 6.75,
  "national_average_last_updated": "2026-01-30",
  "optimal_blue_rate": 5.994,
  "optimal_blue_last_updated": "2026-02-02",
  "freddie_mac_rate": 6.75,
  "freddie_mac_last_updated": "2026-01-30",
  "disclaimer": "Rates shown are for illustrative purposes. Your actual rate may vary based on credit, loan amount, and other factors.",
  "metadata": {
    "api_version": "v1",
    "documentation": "https://api.homebuyer.com/docs"
  }
}

Error Handling

The API uses standard HTTP status codes:

200

Success

400

Bad Request

429

Rate Limited

500

Server Error

503

Unavailable

Error Response

{
  "error": "Invalid state: \"XX\". Valid values: AK, AL, AR, ...",
  "status": 400
}

CORS Support

The API supports Cross-Origin Resource Sharing and can be called from any domain:

Response Headers

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Use Cases

Email Newsletters

Include current rates and upcoming events in newsletters

Real Estate Apps

Display rates alongside property listings

Financial Dashboards

Track mortgage rate trends and events

Rate Lock Timing

Alert users to events that may move rates

Market Alerts

Notify users before major economic releases

Data Pipelines

Collect data for analysis and forecasting

Support

Need help with the API? Here's how to get support:

Check this documentation for common questions and examples
Visit our contact page for general inquiries
For enterprise access or custom integrations, reach out directly

Introduction

Base URLs

Authentication

Rate Limits

API Reference

Parameters

Response

Error Handling

CORS Support

Use Cases

Email Newsletters

Real Estate Apps

Financial Dashboards

Rate Lock Timing

Market Alerts

Data Pipelines

Support

Get Mortgage Help Every Week. No Spam.