REST API v1

API Documentation

Programmatic access to U.S. foreclosure and REO property data aggregated from hundreds of public records and auction sources nationwide. Search, filter, paginate, and retrieve listings via a simple REST API.

Base URL

https://api.foreclosuredatahub.com/api/v1

Authentication

API key setup

5 Endpoints

Search, counts, and more

Rate Limits

Usage limits per key

Authentication

Authenticate every request with your API key.

Include your API key in the x-api-key header on every request. Generate keys from your dashboard.

curl -H "x-api-key: fdh_ak_your_key_here" \
  https://api.foreclosuredatahub.com/api/v1/sources

API access requires a monthly or yearly subscription. Monthly and yearly trials include 150 total API requests; weekly plans do not include API access.

Rate Limits

Limits are enforced per API key. Exceeding returns 429 with a Retry-After header.

15 req/min

Data

30 req/min

Counts

15 req/min

Sources

10 req/min

Global

1,000 req/hr

Trial

150 total

These limits apply to standard subscription keys. Licensed keys run on negotiated monthly quotas with substantially higher ceilings. See licensing tiers.

Response Format

All responses use a consistent JSON envelope.

Success

Response

{
  "data": [ ... ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 25,
    "total_pages": 6
  }
}

Error

Response

{
  "error": "Description of what went wrong"
}

Property Enrichment Fields

Listings scraped from July 18, 2026 onward carry additional assessor and public record detail: building profile, the last recorded sale, and loan position. Older listings and a few sources omit these fields, so treat every one as optional.

Unified search (mode=unified)

Response

{
  "building_type": "Single Family",
  "build_quality": "Good",
  "num_bedrooms": "4",
  "living_sqft": "1,353",
  "assessor_year_built": "1973",
  "land_use": "Single Family Residence",
  "last_sold_price": "$78,000",
  "last_sold_date": "Oct, 10 2014",
  "mortgage_amount": "$76,587",
  "mortgage_date": "Oct, 10 2014",
  "mortgage_term": "30 years",
  "mortgage_maturity_date": "Nov, 01 2044",
  "estimated_equity": 367032
}

By-source search and /properties/data

Response

"enrichment": {
  "building_type": "Single Family",
  "build_quality": "Good",
  "bedrooms": "4",
  "living_sqft": "1,353",
  "building_sqft": "1,353",
  "year_built": "1973",
  "actual_year_built": "1980",
  "property_type": "Single Family Residence",
  "last_sold_price": "$78,000",
  "last_sold_date": "Oct, 10 2014",
  "loan_amount": "$76,587",
  "loan_origination_date": "Oct, 10 2014",
  "loan_term": "30 years",
  "loan_maturity_date": "Nov, 01 2044"
}

Note: the raw source column Mortgage amount due holds a date, not an amount: the date the mortgage amount falls due, which is the loan maturity date. enrichment.loan_maturity_date exposes the same value under a more explicit name. Both are returned.

estimated_equity (unified responses only) is the estimated value minus the original recorded loan principal, as a plain number. It is an approximation rather than a payoff figure: it ignores principal paid down since origination and any secondary liens, and it can be negative when a property is over-leveraged.

Endpoints

All endpoints use GET requests and return JSON.

List all available data sources with their supported filters.

Request

curl -H "x-api-key: fdh_ak_your_key_here" \
  https://api.foreclosuredatahub.com/api/v1/sources

Response

{
  "data": [
    {
      "id": "feed-01",
      "name": "Data Feed 01",
      "filters": { "county": true, "state": true, "sale_date": true, "owner_name": true, "est_value": true }
    },
    ...
  ]
}

Search across all data sources simultaneously. Returns up to 100 results per source, grouped by source. At least one location filter (county, state, zip, or address) is required.

Parameters

countystringOptional

County name filter. Can specify multiple (e.g., county=Cook&county=Lake).

statestringOptional

State name or abbreviation. Can specify multiple.

zipstringOptional

Zip code filter. Can specify multiple.

addressstringOptional

Property address filter (partial match). Can specify multiple.

sale_date_startdateOptional

Filter by sale date start (YYYY-MM-DD).

sale_date_enddateOptional

Filter by sale date end (YYYY-MM-DD).

owner_namestringOptional

Owner name filter (partial match on first or last name). Only applied to sources that expose owner fields.

est_value_minnumberOptional

Minimum estimated value (Market Valuation). Only applied to sources with an estimated value field.

est_value_maxnumberOptional

Maximum estimated value (Market Valuation). Only applied to sources with an estimated value field.

Request

curl -H "x-api-key: fdh_ak_..." \
  "https://api.foreclosuredatahub.com/api/v1/properties/search?state=FL&county=Miami-Dade"

Response

{
  "data": {
    "results": [
      {
        "source": "feed-01",
        "source_name": "Data Feed 01",
        "records": [ { ... }, ... ],
        "count": 45,
        "has_more": false
      },
      ...
    ]
  },
  "meta": { "total": 312 }
}

Search with mode=unified to get normalized, paginated results across all sources in a single flat list. Each record includes standardized fields (address, city, state, zip, county, sale_date, bid_amount, owner name, etc.) with a source field indicating origin.

Parameters

modestringRequired

Set to "unified" to enable unified mode.

countystringOptional

County name filter. Can specify multiple.

statestringOptional

State name or abbreviation. Can specify multiple.

zipstringOptional

Zip code filter. Can specify multiple.

addressstringOptional

Property address filter (partial match). Can specify multiple.

sale_date_startdateOptional

Filter by sale date start (YYYY-MM-DD).

sale_date_enddateOptional

Filter by sale date end (YYYY-MM-DD).

owner_namestringOptional

Owner name filter (partial match on first or last name).

est_value_minnumberOptional

Minimum estimated value (Market Valuation). Uses the unified zestimate_numeric column.

est_value_maxnumberOptional

Maximum estimated value (Market Valuation). Uses the unified zestimate_numeric column.

pageintegerOptional

Page number (default: 1).

page_sizeintegerOptional

Results per page, max 25 (default: 25).

Request

curl -H "x-api-key: fdh_ak_..." \
  "https://api.foreclosuredatahub.com/api/v1/properties/search?mode=unified&state=FL&page=1&page_size=25"

Response

{
  "data": {
    "records": [
      {
        "source": "feed-01",
        "address": "123 Main St",
        "city": "Miami",
        "state": "FL",
        "zip": "33101",
        "county": "Miami-Dade",
        "sale_date": "2026-04-15",
        "bid_amount": "250000",
        "owner_first_name": "John",
        "owner_last_name": "Doe",
        ...
      },
      ...
    ]
  },
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 25,
    "total_pages": 50
  }
}

Fetch paginated data from a single source. Max 25 records per page.

Parameters

sourcestringRequired

Data source ID (from /v1/sources).

pageintegerOptional

Page number (default: 1).

per_pageintegerOptional

Results per page, 1-25 (default: 25).

start_datedateOptional

Filter by date added start (YYYY-MM-DD).

end_datedateOptional

Filter by date added end (YYYY-MM-DD).

countystringOptional

County name filter.

statestringOptional

State name or abbreviation.

owner_namestringOptional

Owner name filter (partial match on first or last name). Only applied when the source exposes owner fields.

est_value_minnumberOptional

Minimum estimated value (Market Valuation). Only applied when the source exposes an estimated value field.

est_value_maxnumberOptional

Maximum estimated value (Market Valuation). Only applied when the source exposes an estimated value field.

Request

curl -H "x-api-key: fdh_ak_..." \
  "https://api.foreclosuredatahub.com/api/v1/properties/data?source=feed-01&state=TX&per_page=25"

Response

{
  "data": [
    { "Address": "123 Main St", "County": "Harris", ... },
    ...
  ],
  "meta": {
    "total": 1250,
    "page": 1,
    "per_page": 25,
    "total_pages": 25
  }
}

Get record counts per data source for a date or date range.

Parameters

datedateOptional

Single date (YYYY-MM-DD). Defaults to today.

start_datedateOptional

Range start (YYYY-MM-DD). Use with end_date.

end_datedateOptional

Range end (YYYY-MM-DD). Use with start_date.

Request

curl -H "x-api-key: fdh_ak_..." \
  "https://api.foreclosuredatahub.com/api/v1/properties/counts?start_date=2026-03-15&end_date=2026-03-22"

Response

{
  "data": {
    "start_date": "2026-03-15",
    "end_date": "2026-03-22",
    "sources": [
      {
        "id": "feed-01",
        "name": "Data Feed 01",
        "count": 523
      },
      ...
    ],
    "total": 4821
  }
}

Error Codes

Standard HTTP status codes with descriptive error messages.

400

Bad Request

Invalid parameters or missing required fields.

401

Unauthorized

Missing or invalid API key.

403

Forbidden

Subscription inactive or plan does not include API access.

404

Not Found

No data matches the query.

429

Rate Limited

Too many requests. Check Retry-After header.

500

Server Error

Something went wrong on our end.

Ready to get started?

Generate your API key from the dashboard and start building in minutes.

Get Your API Key View Pricing

Building a product on top of this data? Commercial licensing covers showing records to your own customers. Standard plans are internal use only.