API Reference

The Foreclosure Atlas API provides programmatic access to verified foreclosure case data across multiple U.S. states. The API follows RESTful conventions, returns JSON responses, and uses API key authentication.

Currently covering Georgia, Tennessee, Alabama, and Ohio, with additional states in the pipeline.

Don't have an API key yet? Request access and we'll provision one within 24 hours.

Authentication

All API requests require authentication via an API key. Include the following header with every request:

x-api-key: <your-api-key>

Your API key is tied to the states you have purchased access to. If you request data for a state your key does not cover, the API will return a 403 Forbidden response.

Example Authenticated Request

# Using curl
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.the1416group.com/foreclosures?state=GA

Header	Type	Required	Description
x-api-key	string	Required	Your API key for authentication.

Base URL

All API requests should be made to:

https://api.the1416group.com

Pagination

List endpoints return paginated results. Use the page and limit query parameters to control pagination. Results are ordered by uploaded date, newest first.

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed). Minimum value: 1.
limit	integer	50	Number of items per page. Maximum: 50.

Pagination Response Fields

Field	Type	Description
page	integer	Current page number.
last_page	integer	Total number of pages available.
limit	integer	Items per page for this request.
total_items	integer	Total number of matching records.

GET /client/states

Returns the list of states your API key is authorized to access. Use this endpoint to discover which state codes you can pass to the /foreclosures endpoint.

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your API key for authentication.

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.the1416group.com/client/states

Example Response (200 OK)

{
  "client_name": "Acme Proptech",
  "states": [
    {
      "state_code": "GA",
      "state_name": "Georgia"
    },
    {
      "state_code": "FL",
      "state_name": "Florida"
    }
  ]
}

Response Fields

Field	Type	Description
client_name	string \| null	The name of the authenticated client, or null if no access records exist.
states	array	List of state objects the client can access.
states[].state_code	string	Two-letter state code (e.g., GA, FL, NY).
states[].state_name	string	Full state name in title case.

Status Codes

200	Success. Returns the client name and authorized states.
401	Unauthorized. Missing or invalid API key.

GET /foreclosures

Returns a paginated list of foreclosure cases with optional filtering by geography and status. Results are ordered by uploaded date (newest first). By default, historical foreclosure cases are excluded unless a specific status filter is provided.

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your API key for authentication.

Query Parameters

Parameter	Type	Required	Description
state	string	Required	Two-letter state code (e.g., GA, FL, NY). Must be a state your API key is authorized to access.
county	string	Optional	Filter by auction county. Accepts slug format (e.g., `st-clair`) or display name (e.g., `St. Clair`, URL-encoded).
city	string	Optional	Filter by city. Accepts slug format (e.g., `new-york`) or display name (e.g., `New York`, URL-encoded).
status	string	Optional	Comma-separated list of statuses to include. See Status Lifecycle for valid values. If omitted, all non-HISTORICAL cases are returned.
page	integer	Optional	Page number for pagination. Defaults to 1.
limit	integer	Optional	Number of items per page. Defaults to 50. Maximum: 50.

Default Behavior: When no status filter is provided, the API automatically excludes cases with a HISTORICAL status. To include historical cases, explicitly pass status=HISTORICAL or include it in a comma-separated list.

County Filter Note: The county filter matches against the auction county (where the foreclosure sale takes place), not the property county (where the property is physically located). These may differ in some jurisdictions.

Slug Format

Slug format means dashes (-) replace spaces. The slug may not start or end in a dash, and all punctuation (such as periods) is removed.

Example Requests

# Basic state query
GET /foreclosures?state=GA

# Filter by county (slug format)
GET /foreclosures?state=MI&county=st-clair

# Filter by county (display name, URL-encoded)
GET /foreclosures?state=MI&county=St.%20Clair

# Filter by city
GET /foreclosures?state=NY&city=new-york

# Filter by multiple statuses with pagination
GET /foreclosures?state=FL&status=ACTIVE,LIKELY_ACTIVE&page=2&limit=25

Example Response (200 OK)

{
  "data": [
    {
      "property": {
        "state_code": "GA",
        "auction_county": "Fulton",
        "county": "Fulton",
        "city": "Atlanta",
        "address_line_1": "123 Main Street",
        "address_line_2": null,
        "zip_code": "30301",
        "parcel_number": "14-0001-0012"
      },
      "principal_amount_owed": "$185,000.00",
      "date_of_debt": "2023-06-15",
      "foreclosure_sale_date": "2026-04-01",
      "foreclosure_sale_location": "Fulton County Courthouse",
      "opening_bid": "$150,000.00",
      "subject_to": null,
      "deed_book_page": "Book 123, Page 456",
      "law_firm_foreclosure_number": "FC-2026-00123",
      "district_land_lot": "Land Lot 50, 14th District",
      "legal_considerations": null,
      "summary": "Foreclosure on residential property...",
      "parties": [
        {
          "role": "BORROWER",
          "party": {
            "name": "John Doe",
            "phone": null,
            "email": null
          }
        },
        {
          "role": "LENDER",
          "party": {
            "name": "First National Bank",
            "phone": "555-0100",
            "email": "servicing@fnb.com"
          }
        }
      ],
      "law_firms": [
        {
          "name": "Smith & Associates",
          "phone": "555-0200",
          "url": "https://smithlaw.example.com"
        }
      ],
      "verification": {
        "foreclosure_status": "ACTIVE",
        "current_bid": "$155,000.00",
        "source": "ATTORNEY",
        "updated_at": "2026-02-20T14:30:00Z"
      }
    }
  ],
  "page": 1,
  "last_page": 5,
  "limit": 50,
  "total_items": 237
}

Status Codes

200	Success. Returns paginated foreclosure data.
400	Bad Request. Invalid status value(s) provided.
401	Unauthorized. Missing or invalid API key.
403	Forbidden. API key does not have access to the requested state.
404	Not Found. The specified state, county, or city was not found.
500	Internal Server Error. An unexpected error occurred.

Foreclosure Case Object

The central entity returned by the /foreclosures endpoint. Each case is linked to exactly one Property and can have multiple Parties and Law Firms.

Field	Type	Description
property	object	The property associated with this foreclosure case. See Property Object.
principal_amount_owed	string \| null	Formatted dollar amount of the principal debt (e.g., "$185,000.00").
date_of_debt	string \| null	ISO 8601 date when the debt originated.
foreclosure_sale_date	string \| null	ISO 8601 date of the scheduled foreclosure sale.
foreclosure_sale_location	string \| null	Location where the foreclosure sale will take place.
opening_bid	string \| null	Formatted opening bid amount.
subject_to	string \| null	Any conditions the sale is subject to.
deed_book_page	string \| null	Deed book and page reference.
law_firm_foreclosure_number	string \| null	The law firm's internal case reference number.
district_land_lot	string \| null	District and land lot identifier for the property.
legal_considerations	string \| null	Any additional legal notes or considerations.
summary	string \| null	Brief text summary of the foreclosure case.
parties	array \| absent	List of parties involved (borrowers, lenders, etc.). See Party Object. Only present if parties exist.
law_firms	array \| absent	List of law firms handling the case. See Law Firm Object. Only present if law firms exist.
verification	object \| absent	Current verification/status information. See Verification Object. Only present if verification data exists.

Property Object

Describes the physical property associated with a foreclosure case.

Field	Type	Description
state_code	string	Two-letter state code.
auction_county	string	County where the auction is held.
county	string \| null	County where the property is located (may differ from auction county).
city	string \| null	City where the property is located.
address_line_1	string	Primary street address.
address_line_2	string \| null	Secondary address (apt, suite, etc.).
zip_code	string \| null	ZIP or postal code.
parcel_number	string \| null	County parcel/tax ID number.

Party Object

Represents a party involved in a foreclosure case. Each party has a role and contact information.

Roles

Valid party roles: BORROWER, OWNER, LENDER, ATTORNEY.

Structure

Field	Type	Description
role	string	Role in the case: BORROWER, OWNER, LENDER, or ATTORNEY.
party.name	string	Name of the party.
party.phone	string \| null	Phone number, if available.
party.email	string \| null	Email address, if available.

Law Firm Object

Represents a law firm handling a foreclosure case.

Field	Type	Description
name	string	Name of the law firm.
phone	string \| null	Law firm phone number.
url	string \| null	Law firm website URL.

Verification Object

Contains the current verification status and metadata for a foreclosure case.

Field	Type	Description
foreclosure_status	string	Current status of the foreclosure. See Status Lifecycle.
current_bid	string \| null	Current bid amount, if available (e.g., "$155,000.00").
source	string \| null	Verification source: `ATTORNEY` or `INTERNAL`.
updated_at	string	ISO 8601 timestamp of last verification update.

Status Lifecycle

The following foreclosure statuses track the lifecycle of each case from initial posting through resolution.

UNKNOWN → ACTIVE → LIKELY_ACTIVE → LIKELY_CANCELLED → CANCELLED → HISTORICAL

ACTIVE → RESCHEDULED | ACTIVE → REDEEMED

Status Definitions

UNKNOWN	Default status when the case is first created and has not yet been verified.
ACTIVE	Foreclosure case is recent and the notice is currently posted.
LIKELY_ACTIVE	Notice has been posted but the case is not confirmed as active on the attorney's website.
LIKELY_CANCELLED	The case shows signs of cancellation but has not been formally confirmed.
RESCHEDULED	The foreclosure sale date has been rescheduled to a new date.
CANCELLED	The foreclosure has been cancelled. A new notice has not been received in 10 days for this property address.
REDEEMED	The borrower has redeemed the property by paying off the debt before the sale.
HISTORICAL	The foreclosure sale date has passed (before current date). These are excluded from results by default.

Error Handling

All error responses follow a consistent JSON structure with an error type and a human-readable message.

Error Response Format

{
  "error": "Error Type",
  "message": "A human-readable description of what went wrong."
}

HTTP Status Codes

200	Success.
400	Bad Request. Invalid parameters (e.g., invalid status values).
401	Unauthorized. Missing or invalid API key.
403	Forbidden. API key does not have access to the requested resource.
404	Not Found. The specified state, county, or city was not found.
500	Internal Server Error. An unexpected error occurred.

Example Error Responses

Invalid Status Value (400)

{
  "error": "Bad Request",
  "message": "Invalid status value(s): INVALID_STATUS. Valid values are: ACTIVE, CANCELLED, HISTORICAL, LIKELY_ACTIVE, LIKELY_CANCELLED, REDEEMED, RESCHEDULED, UNKNOWN"
}

State Not Found (404)

{
  "error": "Not Found",
  "message": "State 'XX' not found"
}

County Not Found (404)

{
  "error": "Not Found",
  "message": "County 'nonexistent' not found in state 'GA'"
}

City Not Found (404)

{
  "error": "Not Found",
  "message": "City 'nonexistent' not found in state 'GA'"
}