API Reference
Start typing to search…

Property Quickstart

Access real-time unit-level data

Welcome to the Parcl Labs Property-Level API Quickstart! This guide will help you access unit-level property data including physical characteristics, ownership insights, and event histories.

The Property API lets you pull everything from individual addresses to entire markets of homes, with real-time data on sales, listings, and rentals. For the full range of capabilities, check out our Property Overview.

Looking for market-level data instead? Review our API Quickstart.

Experienced developer? Jump straight to our API Reference.

Get Up and Running

In this guide, you'll learn how to:

  1. Create your Parcl Labs account and get an API key
  2. Make your first property search
    1. Find properties by location, physical attribute, ownership, and event criteria
    2. Retrieve property event histories
  3. Track your API usage
  4. Start building with real examples

1) Set Up Your API account

Create your Parcl Labs account to get started:

  1. Register for a free account here (or sign in if you have one)

  2. Navigate to the dashboard and copy your API key

  1. Store your key securely - you'll need it for all API requests

2) Access Property Data

The Property API lets you search for properties and their event histories across the US. This Quickstart focuses on the Property Search V2 endpoint - the most comprehensive and flexible way to filter properties by location, physical characteristics, ownership status, event histories, and more.

For address-based searches, check out our Address Search endpoint.

Setting Up Your Search

The Property Search V2 endpoint returns properties and their events based on your search criteria. Here's how to structure your search:

Required: Choose Your Search Method

  • parcl_id: Search within a specific market using its unique identifier
  • parcl_property_ids: Search specific properties using their unique identifiers
  • geo_coordinates: Search by latitude/longitude coordinates and radius

Optional: Add Filters

  • Property filters: Property type, year built, physical attributes, new construction, and more
  • Owner filters: Investor, owner-occupied, specific corporate entity owners, and more
  • Event filters: Event type, date range, price range, and more

Control Your Response Data 

These boolean parameters determine what data you'll receive:

  • include_property_details: Returns property metadata (address, size, bedrooms, etc.)
  • include_events: Returns event metadata (sales, listings, etc.)
  • include_full_event_history: Returns complete event history for each property

Make Your First Property Search Request

Let's make your first Property API call! We'll search for properties in Chicago, showing you how to use the search parameters and what kind of property data you'll get back.

Required Parameters

  • parcl_id: Specifies the market area you want to search (e.g., Brooklyn, NY). Learn how to find the parcl_id here.

Optional Filters

Here are examples of parameters you can use to refine your property search:

  • Physical characteristics:
    • Property type (property_type) allows you to filter by SINGLE_FAMILY, CONDO, TOWNHOUSE, or OTHER
    • Square footage range (square_footage_min, square_footage_max)
    • Number of bedrooms (bedrooms_min, bedrooms_max)
    • Year built (year_built_min, year_built_max)
  • Ownership status:
    • Current owner (current_entity_owner_name) - e.g., INVITATION_HOMES, TRICON
  • Event history of the property (i.e. props that only have sold in the last year):
    • Event name (event_names) - e.g. SOLD, LISTED_SALE, LISTED_FOR_RENT
    • Event date (min_event_date, ****max_event_date)
    • Price (min_price, max_price)

See the Property Search V2 documentation for the complete list of parameters to precisely target properties of interest.

Here's a sample request that finds Chicago properties (parcl_id: 5387853) matching these criteria:

  • Single-family homes
  • Built in 2023 or later
  • At least 4 bedrooms
  • Between 5,500-6,000 square feet
  • Was listed for sale in 2024
  • Only include property details, don’t return events

This very focused request will cost a small amount of credits (8 as of August 2025).

📘

Before running the command:

Replace {API_KEY} with your actual API key.

Example cURL request:

curl -X 'POST' \
  'https://api.dev.parcllabs.com/v2/property_search?limit=1000&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "parcl_ids": [
    5387853
  ],
  "property_filters": {
    "include_property_details": true,
    "property_types": [
      "SINGLE_FAMILY"
    ],
    "min_beds": 4,
    "min_sqft": 5500,
    "max_sqft": 6000,
    "min_year_built": 2023
  },
  "event_filters": {
    "event_names": [
      "LISTED_SALE"
    ],
    "min_event_date": "2024-01-01",
    "max_event_date": "2024-12-31",
    "include_events": false,
    "include_full_event_history": false
  }
}'

What to Expect in the Response

When you run this command:

  1. Sends a POST request to Property Search V2 using Chicago's parcl_id (5387853)
  2. Properties are filtered by your criteria (single-family, built since 2023, 4+ bedrooms, 5,500-6,000 sq ft, had a for-sale listing in 2024)
  3. You'll receive a JSON response containing matching properties with details like:
    • parcl_property_id (unique identifier)
    • Physical attributes (beds, baths, square footage)
    • Location (address, coordinates)
    • Event fields will be NULL since include_events is set to false

Here's a sample property from the response:

      {
        "parcl_property_id": 63325076,
        "property_metadata": {
          "bathrooms": 6,
          "bedrooms": 4,
          "sq_ft": 5500,
          "year_built": 2024,
          "property_type": "SINGLE_FAMILY",
          "address1": "1225 W SCHOOL ST",
          "address2": null,
          "city": "CHICAGO",
          "state": "IL",
          "zip5": 60657,
          "latitude": 41.941385,
          "longitude": -87.660019,
          "city_name": "Chicago City",
          "county_name": "Cook County",
          "metro_name": null,
          "record_added_date": "2024-12-13",
          "current_on_market_flag": 0,
          "current_on_market_rental_flag": 0,
          "current_new_construction_flag": 1,
          "current_owner_occupied_flag": 1,
          "current_investor_owned_flag": 0,
          "current_entity_owner_name": null
        },
        "events": null
      },

Retrieve Property Events

Once you've found properties of interest, use the same Property Search V2 endpoint to get detailed sales, rental, and listing events for each property. Simply change the include_events parameter to true.

We'll make the same request as before, but with include_events set to true:

📘

Before running the command:

Replace {API_KEY} with your actual API key.

Example cURL request:

curl -X 'POST' \
  'https://api.dev.parcllabs.com/v2/property_search?limit=1000&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "parcl_ids": [
    5387853
  ],
  "property_filters": {
    "include_property_details": true,
    "property_types": [
      "SINGLE_FAMILY"
    ],
    "min_beds": 4,
    "min_sqft": 5500,
    "max_sqft": 6000,
    "min_year_built": 2023
  },
  "event_filters": {
    "event_names": [
      "LISTED_SALE"
    ],
    "min_event_date": "2024-01-01",
    "max_event_date": "2024-12-31",
    "include_events": true,
    "include_full_event_history": false
  }
}'

What to Expect in the Response

This request will return the same 8 properties as before, but now the events field will be populated with LISTED_SALE events from 2024 that match your event filters.

When you run this command:

  1. Sends a POST request to Property Search V2 using Chicago's parcl_id (5387853)
  2. Properties are filtered by your criteria (single-family, built since 2023, 4+ bedrooms, 5,500-6,000 sq ft, had a for-sale listing in 2024)
  3. You'll receive the same property details as before, plus event information showing 2024 LISTED_SALE events for each property

Here's the sample property from our new response. The owner listed this property twice in 2024:

      {
        "parcl_property_id": 63325076,
        "property_metadata": {
          "bathrooms": 6,
          "bedrooms": 4,
          "sq_ft": 5500,
          "year_built": 2024,
          "property_type": "SINGLE_FAMILY",
          "address1": "1225 W SCHOOL ST",
          "address2": null,
          "city": "CHICAGO",
          "state": "IL",
          "zip5": 60657,
          "latitude": 41.941385,
          "longitude": -87.660019,
          "city_name": "Chicago City",
          "county_name": "Cook County",
          "metro_name": null,
          "record_added_date": "2024-12-13",
          "current_on_market_flag": 0,
          "current_on_market_rental_flag": 0,
          "current_new_construction_flag": 1,
          "current_owner_occupied_flag": 1,
          "current_investor_owned_flag": 0,
          "current_entity_owner_name": null
        },
        "events": [
          {
            "event_type": "LISTING",
            "event_name": "LISTED_SALE",
            "event_date": "2024-07-22",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2699000,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "LISTED_SALE",
            "event_date": "2024-03-14",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2700000,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          }
        ]
      },

Retrieve The Full Property Event History

After finding properties that match your search criteria, you might want their complete transaction history - not just the events that matched your filters. For example, you could search for properties that had a listing in 2024, but retrieve their entire history of sales, rentals, and listings going back years. This gives you the full historical context for properties that meet your current criteria.

We'll make the same request as before, but with include_full_event_history set to true. Note that include_eventsmust also be set to true for the full event history to be returned:

📘

Before running the command:

Replace {API_KEY} with your actual API key.

Example cURL request:

curl -X 'POST' \
  'https://api.dev.parcllabs.com/v2/property_search?limit=1000&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "parcl_ids": [
    5387853
  ],
  "property_filters": {
    "include_property_details": true,
    "property_types": [
      "SINGLE_FAMILY"
    ],
    "min_beds": 4,
    "min_sqft": 5500,
    "max_sqft": 6000,
    "min_year_built": 2023
  },
  "event_filters": {
    "event_names": [
      "LISTED_SALE"
    ],
    "min_event_date": "2024-01-01",
    "max_event_date": "2024-12-31",
    "include_events": true,
    "include_full_event_history": true
  }
}'

What to Expect in the Response

This request will return the same 8 properties as before, but now the events field will be populated with the entire event history for these properties.

When you run this command:

  1. Sends a POST request to Property Search V2 using Chicago's parcl_id (5387853)
  2. Properties are filtered by your criteria (single-family, built since 2023, 4+ bedrooms, 5,500-6,000 sq ft, had a for-sale listing in 2024)
  3. You'll receive the same property details as before, plus the complete event history for each property (not just 2024 LISTED_SALE events)

Here's the same sample property from our newest response:

      {
        "parcl_property_id": 63325076,
        "property_metadata": {
          "bathrooms": 6,
          "bedrooms": 4,
          "sq_ft": 5500,
          "year_built": 2024,
          "property_type": "SINGLE_FAMILY",
          "address1": "1225 W SCHOOL ST",
          "address2": null,
          "city": "CHICAGO",
          "state": "IL",
          "zip5": 60657,
          "latitude": 41.941385,
          "longitude": -87.660019,
          "city_name": "Chicago City",
          "county_name": "Cook County",
          "metro_name": null,
          "record_added_date": "2024-12-13",
          "current_on_market_flag": 0,
          "current_on_market_rental_flag": 0,
          "current_new_construction_flag": 1,
          "current_owner_occupied_flag": 1,
          "current_investor_owned_flag": 0,
          "current_entity_owner_name": null
        },
        "events": [
          {
            "event_type": "SALE",
            "event_name": "SOLD",
            "event_date": "2024-12-20",
            "entity_owner_name": null,
            "true_sale_index": 3,
            "price": 2645000,
            "transfer_index": 3,
            "investor_flag": 0,
            "owner_occupied_flag": 1,
            "new_construction_flag": 1,
            "current_owner_flag": 1,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "PRICE_CHANGE",
            "event_date": "2024-10-09",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2659999,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "PRICE_CHANGE",
            "event_date": "2024-09-17",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2669999,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "LISTED_SALE",
            "event_date": "2024-07-22",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2699000,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "LISTING_REMOVED",
            "event_date": "2024-07-05",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 0,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "LISTED_SALE",
            "event_date": "2024-03-14",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 2700000,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "SALE",
            "event_name": "SOLD",
            "event_date": "2023-10-02",
            "entity_owner_name": null,
            "true_sale_index": 2,
            "price": 925000,
            "transfer_index": 2,
            "investor_flag": 0,
            "owner_occupied_flag": 0,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "SALE",
            "event_name": "SOLD",
            "event_date": "2023-07-19",
            "entity_owner_name": null,
            "true_sale_index": 1,
            "price": 890000,
            "transfer_index": 1,
            "investor_flag": null,
            "owner_occupied_flag": null,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "PENDING_SALE",
            "event_date": "2023-06-29",
            "entity_owner_name": null,
            "true_sale_index": 0,
            "price": 975000,
            "transfer_index": 0,
            "investor_flag": null,
            "owner_occupied_flag": null,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          },
          {
            "event_type": "LISTING",
            "event_name": "LISTED_SALE",
            "event_date": "2023-02-27",
            "entity_owner_name": null,
            "true_sale_index": 0,
            "price": 975000,
            "transfer_index": 0,
            "investor_flag": null,
            "owner_occupied_flag": null,
            "new_construction_flag": 1,
            "current_owner_flag": 0,
            "record_updated_date": "2025-07-23"
          }
        ]
      },

The response includes complete property history - sales, rentals, and listings - plus ownership details like investor_flagand owner_occupied status.

3. Manage Your Property API Usage and Credits

Parcl Labs uses a simple credit-based consumption model: 1 credit = 1 property returned.

Learn more in our Credits Guide.

4. Start Building

Now that you have tried the property endpoint, explore what else is possible:

  1. Check out the API Cookbook - You'll find code examples showing how to analyze properties and create visualizations. We also provide a property data downloader tool that lets you export property data to CSV in bulk.
  2. Install the Parcl Labs Python SDK to efficiently pull property data at scale. The SDK simplifies the process of querying, retrieving, parsing, and formatting the data for you.
  3. Review the API Reference to explore all available endpoints in the Parcl Labs API.
  4. Get inspired by reviewing our research.
  5. Got questions or feedback? Head to our Developer Forum.

Stay Updated

The property-level API is continuously evolving. Keep an eye on the Parcl Labs changelog for updates, including new features and extended data coverage.

For any questions or feedback, please visit our forum or email us at [email protected].