> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.dealmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> How to query properties and contacts using filters

The core query mechanism in DealMachine. They let you search for properties and contacts using criteria like location, property type, owner demographics, equity, and hundreds of other data points.

## How Filters Work

Each filter represents a single criterion — a data point combined with an operator and a value. DealMachine has over 200 filterable fields organized into groups.

## Source Types

Filters are scoped to a source type:

| Source Type  | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `properties` | Property-level data (address, value, equity, lot size, etc.)      |
| `people`     | Contact/owner-level data (name, phone, email, demographics, etc.) |

## Filter Types

Each filter has a data type that determines which operators you can use:

| Type           | Description                                    | Example                      |
| -------------- | ---------------------------------------------- | ---------------------------- |
| `NUMBER`       | Numeric values with range/comparison operators | Equity % between 40-80       |
| `STRING`       | Text values with match operators               | Owner name contains "Smith"  |
| `DATE`         | Date values with range/comparison operators    | Purchased after 2015-01-01   |
| `MULTI_SELECT` | Predefined option sets                         | Property type in \[SFR, MFR] |
| `BOOLEAN`      | True/false values                              | Is absentee owner?           |

## Operators

Each filter type supports specific operators:

### NUMBER Operators

| Operator                | Description                       |
| ----------------------- | --------------------------------- |
| `range`                 | Value falls between min and max   |
| `greater_than`          | Value is greater than             |
| `greater_than_or_equal` | Value is greater than or equal to |
| `less_than`             | Value is less than                |
| `less_than_or_equal`    | Value is less than or equal to    |
| `equals`                | Exact numeric match               |
| `not_equals`            | Does not equal                    |

### STRING Operators

| Operator       | Description                        |
| -------------- | ---------------------------------- |
| `contains`     | Text contains substring            |
| `any_of`       | Matches any of the provided values |
| `starts_with`  | Text starts with prefix            |
| `ends_with`    | Text ends with suffix              |
| `equals`       | Exact text match                   |
| `not_equals`   | Does not equal                     |
| `not_contains` | Text does not contain substring    |

### DATE Operators

| Operator        | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `date_range`    | Falls between start and end date                                         |
| `is_after`      | Date is after a given date                                               |
| `is_before`     | Date is before a given date                                              |
| `equals`        | Exact date match                                                         |
| `relative_time` | Relative time comparison (e.g., within last 6 months)                    |
| `is_known`      | Has any export activity or has none. Available only for `last_exported`. |

### MULTI\_SELECT Operators

| Operator        | Description                          |
| --------------- | ------------------------------------ |
| `contains_any`  | Matches any of the selected options  |
| `contains_none` | Matches none of the selected options |
| `contains_all`  | Matches all of the selected options  |

### BOOLEAN

Boolean filters do not require an operator — just pass a `filter_id` and `value`. The operator is automatically inferred.

## Filter Groups

Filters are organized into [groups](/concepts/groups). Use the `group_id` to browse filters by category:

```bash theme={null}
curl "https://api.v2.dealmachine.com/v1/filters?source_type=properties&group_id=owner_type" \
  -H "Authorization: Bearer dm_sk_live_xxx"
```

See the [Groups](/concepts/groups) page for the complete list of all group IDs.

## Discovering Filters

Use the [List Filters](/api-reference/filters/list-filters) endpoint to discover all available filters:

```bash theme={null}
curl "https://api.v2.dealmachine.com/v1/filters?source_type=properties" \
  -H "Authorization: Bearer dm_sk_live_xxx"
```

This returns every filter with its:

* Display name and description
* Data type
* Available options (for `MULTI_SELECT` filters)
* Allowed operators
* Group ID (location, financial, ownership, etc.)

You can also search by name:

```bash theme={null}
# Search for equity-related filters
curl "https://api.v2.dealmachine.com/v1/filters?search=equity" \
  -H "Authorization: Bearer dm_sk_live_xxx"
```

## Using Filters in Queries

When searching, each filter you apply is a JSON object with these keys:

```json theme={null}
{
  "filter_id": "estimated_value",
  "operator": "range",
  "value": { "min": 100000, "max": 500000 }
}
```

| Key         | Description                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `filter_id` | The filter slug (from the discovery endpoint above)                                                                |
| `operator`  | One of the filter's `allowed_operators`. **Optional for BOOLEAN filters**; automatically defaults to `is_boolean`. |
| `value`     | The filter value. Its shape depends on the operator                                                                |

Pass an array of these objects in your search request. All filters are combined with **AND** logic — every filter must match.

```json theme={null}
{
  "filters": [
    { "filter_id": "state", "operator": "equals", "value": "TX" },
    {
      "filter_id": "estimated_value",
      "operator": "range",
      "value": { "min": 200000, "max": 600000 }
    },
    { "filter_id": "is_absentee_owner", "value": true }
  ]
}
```

For the complete reference of every operator and its expected value shape, see [Filter Values](/concepts/filter-values). For the full search workflow, see [Searching](/concepts/searching).

## Filters vs Fields

* **Filters** describe how you can query data (search criteria with operators)
* **Fields** describe what data is available (columns in your results)

Every filter corresponds to a field, but not every field is filterable. Use the [List Fields](/api-reference/fields/list-fields) endpoint to see all available data fields and their capabilities.