Searching - DealMachine API

The DealMachine API lets you search for properties and people using a powerful combination of filters, field selection, pagination, and sorting. This page walks through the complete workflow.

The Search Workflow

Searching follows three steps:

Discover

Use the discovery endpoints to find available filters and fields: - List Filters — see what you can search by - List Fields — see what data you can return

Build

Construct your search request: - Pick filters and set their operators and values - Choose which fields to include in the response - Set pagination and sorting preferences

Send your request to the appropriate search endpoint: - Search Properties — POST /v1/properties/search - Search People — POST /v1/people/search

Search Endpoints

Endpoint	Method	Description
`/v1/properties/search`	POST	Search for properties
`/v1/people/search`	POST	Search for people/contacts

Both endpoints use POST because the filter arrays and request bodies are too complex for query parameters.

Request Structure

Every search request has the same structure:

{
  "locations": [
    { "type": "state", "code": "TX" },
    { "type": "zip_code", "code": "90210" }
  ],
  "filters": [
    {
      "filter_id": "estimated_value",
      "operator": "range",
      "value": { "min": 100000, "max": 500000 }
    },
    {
      "filter_id": "equity_percent",
      "operator": "greater_than",
      "value": 40
    }
  ],
  "fields": ["estimated_value", "equity_percent", "last_sale_date", "owner_name"],
  "page": 1,
  "per_page": 25,
  "sort": [{ "field_id": "estimated_value", "direction": "desc" }]
}

Parameter	Type	Required	Description
`locations`	array	Conditional	Array of location objects defining where to search (max 15, OR logic). Required unless filters or Query Builder protocol filters are provided.
`filters`	array	Conditional	Array of filter objects. Required unless locations or Query Builder protocol filters are provided.
`fields`	string[]	No	Field IDs to include in results. Omit for defaults.
`page`	integer	No	Page number (default: `1`)
`per_page`	integer	No	Results per page (default: `25`, max: `250`)
`sort`	array	No	Sort objects for ordering results
`include_lists`	object	No	Restrict results to records in list IDs for the searched entity (`property_list_ids`, `people_list_ids`, or `company_list_ids`).
`exclude_lists`	object	No	Exclude records in list IDs for the searched entity.
`exclude_previously_exported`	boolean/object	No	Exclude records already exported by your organization. Pass `true` for the default entity criteria or a full Query Builder object.
`bigquery_data_environment`	integer	No	Query Builder dataset environment: `1` production, `2` staging, `3` development.

Search Logic

Locations use OR logic — a record is included if it falls within any of the provided locations. Filters use AND logic — every filter must match for a record to be included.

{
  "locations": [
    { "type": "county", "code": "48201" },
    { "type": "zip_code", "code": "78704" }
  ],
  "filters": [
    {
      "filter_id": "estimated_value",
      "operator": "range",
      "value": { "min": 200000, "max": 600000 }
    },
    { "filter_id": "is_absentee_owner", "value": true }
  ]
}

This finds properties that are:

In Harris County, TX OR ZIP 78704 (locations — OR)
AND valued between $200k–$ 600k (filter — AND)
AND owned by an absentee owner (filter — AND)

There is no OR grouping or nesting for filters. To achieve OR-like behavior for a single filter field, use operators like contains_any or any_of. For geographic OR logic, use multiple locations.

List And Export Protocol Filters

Search, count, and export endpoints also accept the Query Builder protocol fields for list membership and previous-export exclusion. The API fills organization_id and organization_partition_key from your API key, so most requests only need list IDs or true for export exclusion:

{
  "locations": [],
  "include_lists": { "property_list_ids": [123, 456] },
  "exclude_lists": { "property_list_ids": [789] },
  "exclude_previously_exported": true,
  "bigquery_data_environment": 3
}

For people endpoints, use people_list_ids; for property endpoints, use property_list_ids. You may also pass the full exclude_previously_exported object when you need date, source, export type, credit type, or credits_used criteria.

Field Selection

Use the fields array to control which data points appear in the response:

{ "fields": ["estimated_value", "equity_percent", "last_sale_date"] }

Pass an array of field_id strings from the List Fields endpoint.
Omit fields or pass an empty array to get the default set of fields.
Some base fields (address, internal ID) are always included regardless. See Response Format.

Complete Example

Here’s a full end-to-end example: find high-equity absentee-owned single-family homes across Harris County and Dallas County in Texas, sorted by value.

curl -X POST "https://api.v2.dealmachine.com/v1/properties/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "type": "county", "code": "48201" },
      { "type": "county", "code": "48113" }
    ],
    "filters": [
      {
        "filter_id": "property_type_id",
        "operator": "contains_any",
        "value": [1]
      },
      {
        "filter_id": "equity_percent",
        "operator": "greater_than_or_equal",
        "value": 40
      },
      {
        "filter_id": "is_absentee_owner",
        "value": true
      }
    ],
    "fields": [
      "estimated_value",
      "equity_percent",
      "last_sale_date",
      "owner_name",
      "bedrooms",
      "bathrooms",
      "square_footage"
    ],
    "page": 1,
    "per_page": 25,
    "sort": [
      { "field_id": "estimated_value", "direction": "desc" }
    ]
  }'

Example Response

{
  "data": [
    {
      "dm_property_id": "prop_a1b2c3",
      "address": "1200 Barton Springs Rd",
      "city": "Austin",
      "state": "TX",
      "code": "78704",
      "estimated_value": 875000,
      "equity_percent": 72,
      "last_sale_date": "2015-08-20",
      "owner_name": "Johnson Family Trust",
      "bedrooms": 4,
      "bathrooms": 3,
      "square_footage": 2800
    },
    {
      "dm_property_id": "prop_d4e5f6",
      "address": "4500 Oak Lawn Ave",
      "city": "Dallas",
      "state": "TX",
      "zip": "75219",
      "estimated_value": 650000,
      "equity_percent": 55,
      "last_sale_date": "2018-03-10",
      "owner_name": "Robert Chen",
      "bedrooms": 3,
      "bathrooms": 2,
      "square_footage": 2100
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 3412,
    "total_pages": 137,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Locations

Define where to search — states, counties, ZIP codes, radius, and polygons.

Filter Values

Complete reference for every operator and its expected value shape.

Pagination & Sorting

Control page size, navigate results, and sort by multiple fields.

Response Format

Understand the data + pagination response envelope.

Filters

Learn about filter types, operators, and categories.

Fields

Explore available data fields and their capabilities.

Credits

Understand how search requests consume credits.

​The Search Workflow

​Search Endpoints

​Request Structure

​Search Logic

​List And Export Protocol Filters

​Field Selection

​Complete Example

​Example Response

​Related Guides