
What foreclosure data covers
Say you build a deal-finder app for investors and want distressed properties in it. Foreclosure moves through public stages, and each stage leaves a different record.
Federal rules set the start line. A servicer cannot make the first foreclosure notice or filing until the loan is more than 120 days delinquent, under 12 CFR 1024.41(f). Missed payments before that point leave no public record.
- Pre-foreclosure: The period after the first public notice and before the sale. The owner can still pay, sell or settle.
- Notice of default (NOD): The first public notice where a state forecloses without a court. It is recorded with the county and starts the clock to a sale.
- Trustee sale: The auction in those states, run by the trustee named in the deed of trust. Court-based states hold a court or sheriff's sale instead.
- REO: Real estate owned, a property the lender took back when no bidder bought it at the sale. Most people call it bank-owned.
For a national count, the New York Fed's Household Debt and Credit report for 2026 Q2 is the public benchmark. About 55,000 people had a new foreclosure on their credit report that quarter, a slight improvement on the quarter before. It counts people, not properties.
A real example from a Homesage.ai API call
We ran both calls on Atlanta, Georgia on 2026-11-07. The first preview sent only the auction and sale_type filters. It came back as a 400 error and cost 0 credits.
{ "error": "Required filters missing", "code": "search_obligation_unmet", "missing": ["investment_lens"] } Adding property_type=detached fixed it. The auction search then counted 52 detached properties, 50 at foreclosure and 2 bank-owned, plus 4 of type other. The default for-sale search held 1,844 detached listings in the same city.

Only 8 of the 52 carried a published bid. A price filter drops the other 44, so it hides most of the auction list. We set opening bids from $110,000 to $300,000, which left 3 properties for 3 credits.
| What the calls returned | Property 1 | Property 2 | Property 3 |
|---|---|---|---|
| Sale type | Foreclosure | Foreclosure | Bank-owned |
| Opening bid | $110,000 | $130,000 | $170,000 |
| Estimated ARV | $351,809 | $271,332 | $262,202 |
| Estimated renovation cost | $63,974 | $42,040 | $55,292 |
| Condition basis | Inside photos (10) | Inside photos (13) | Assumed |
| In pre-foreclosure (lien call) | true | not checked | not checked |

The search returned no current estimated value for any of the 3, so the table shows the estimated ARV. Property 3 had no inside photos, so its condition is assumed. The lien call on Property 1 cost 5 credits and returned is_in_pre_foreclosure as true, which fits its upcoming foreclosure sale.
44 of 52 Atlanta auction properties had no published bid, so any price filter hides them.
How to get foreclosure data with the API
The 2 calls answer different questions. The search lists properties headed to auction or already bank-owned in an area. The lien call tells you whether one address is in pre-foreclosure.

- Preview the count. Call the search preview with a city, county or ZIP code and the status active. Add a property type and a sale_type. It returns a count and a cost and charges 0 credits.
- Narrow the filters. Add auction_within_days, published_bid_only or a price band until the cost fits. The paid search has no row limit, so the filters set its size.
- Run the search. Send the same filters to the paid search. It charges 1 credit per property, all or nothing, and returns 402 with nothing charged when the balance falls short.
- Check pre-foreclosure by address. Call the mortgage and lien analysis and read pre_foreclosure.is_in_pre_foreclosure. A fresh call costs 5 credits, and a repeat within 7 days costs 0.
- Handle the miss. An address with no record returns 404 and costs 0 credits. A matched property with nothing recorded still costs 5, and data_quality.coverage_notes says so.
Here is the preview call that worked for Atlanta. The location value is a JSON array of area objects.
curl -G 'https://api.homesage.ai/api/workspace/search/count/' \ -H "Authorization: Bearer $HOMESAGE_API_KEY" \ --data-urlencode 'location=[{"type":"city","city":"Atlanta","state_code":"GA"}]' \ --data-urlencode 'property_status=active' \ --data-urlencode 'property_type=detached' \ --data-urlencode 'auction=off_mls' \ --data-urlencode 'sale_type=foreclosure|bank_owned' | Field name | Call | What it holds |
|---|---|---|
| auction | Search | Set to off_mls, it searches auction-only properties instead of the default for-sale listings |
| sale_type | Search | foreclosure (trustee and foreclosure sales), bank_owned (REO) or other |
| auction_within_days | Search | Keeps properties whose next auction falls in the next 7, 30 or 90 days |
| published_bid_only | Search | Drops properties whose opening bid is not published yet |
| bid, bid_basis | Search | The published bid and which bid it is, for example opening_bid |
| condition_basis | Search | inside_photos when the auction listing had inside photos, else assumed |
| occupancy | Search | Occupancy when known, else null |
| pre_foreclosure.is_in_pre_foreclosure | Lien | true or false for the address |
| pre_foreclosure.nod_date, auction_date | Lien | Notice of default date and scheduled sale date, or null |
| data_quality.coverage_notes | Lien | Why a field is empty, for example nothing on record |
What foreclosure data cannot tell your app
Recordings lag the event. Our API docs put the lag for mortgage recordings at days to weeks, which is why lien results are cached for 7 days.
Auction and for-sale results are 2 separate searches. The docs say never to merge or rank them in one list. Auction returns are worked out at an expected winning bid.
Some filters return nothing in the auction search. property_condition and pfs_min drop every auction property. A state-wide area times out, so loop over cities, counties or ZIP codes for wider coverage.
Common mistakes to avoid
- Searching auctions with no investment filter: The preview returns 400 with search_obligation_unmet. Add a property type, as in the Atlanta call.
- Filtering auction properties by price: In Atlanta, 44 of 52 had no published bid and fell out of every price filter. Run one search without a price band to see them.
- Coding for a field that is not there: occupancy was null on 2 of our 3 properties. The pre-foreclosure dates return null when nothing is on record, so handle null before your app sorts or alerts.
- Paying twice for one address: A repeat lien call within 7 days costs 0 credits. Store each response by address and reuse it.
Estimated values. Not investment advice. Data as of 2026-11-07.
Frequently asked questions
Is foreclosure data public record?
Where can I get a list of bank-owned properties?
What is the difference between pre-foreclosure and foreclosure?
How current is foreclosure data from an API?
How many foreclosures are there in the US?
Try the call
Run the Atlanta preview above with your own key, then point it at your city. The API docs list every parameter, field and error code for both endpoints.
- Homesage.ai auction search and one mortgage and lien analysis for Atlanta, Georgia, pulled 2026-11-07.
- Homesage.ai API docs for the search preview, read 2026-11-07.
- Homesage.ai API docs for the property search, read 2026-11-07.
- Homesage.ai API docs for the mortgage and lien analysis, read 2026-11-07.
- Federal Reserve Bank of New York Household Debt and Credit report for 2026 Q2, released August 2026.
- 12 CFR 1024.41, paragraph (f), Legal Information Institute text.