> ## 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.

# Lists

> Save search results as reusable snapshots

## What are Lists?

Lists are saved snapshots of property or people IDs from a search. Unlike searches (which are dynamic filters), a list captures specific records at a point in time.

## The Search -> List -> Export Workflow

```
Search -> find records matching your criteria
  |
List -> save those record IDs as a named list (up to 1M records)
  |
Export -> pull full data for the list whenever you need it
```

This avoids re-running expensive searches and gives you a stable dataset to work with across multiple exports or integrations.

## Creating a List

`POST /v1/lists` with your filters and locations. The response returns immediately with a `list_id` and status `"building"`.

```json theme={null}
POST /v1/lists
{
  "name": "High Value Properties in Miami",
  "source_type": "properties",
  "filters": [
    { "filter_id": "estimated_value", "operator": "between", "min": 500000, "max": 2000000 }
  ],
  "locations": [
    { "location_type": "city", "location_id": 12345 }
  ]
}
```

## Creating a List from Specific IDs

If you already know the exact property or person IDs you want, pass `record_ids` to create a pre-populated list synchronously (max 250 IDs):

```json theme={null}
POST /v1/lists
{
  "name": "My Selected Properties",
  "source_type": "properties",
  "record_ids": [101, 202, 303]
}
```

The response returns immediately with status `"completed"` and `total_count` reflecting the number of records added.

## Adding & Removing Items

You can add or remove items from any existing list:

```json theme={null}
POST /v1/lists/:id/items
{
  "ids": [101, 202, 303],
  "id_type": "internal_property_id"
}
```

```json theme={null}
DELETE /v1/lists/:id/items
{
  "ids": [101],
  "id_type": "internal_property_id"
}
```

Up to 10,000 IDs per request. Both operations are free.

## Polling for Completion

Lists build asynchronously. Poll `GET /v1/lists/:id` until status is `"completed"`.

Typical build times:

* 10K records: \~5 seconds
* 100K records: \~30 seconds
* 1M records: \~2-3 minutes

```json theme={null}
GET /v1/lists/abc-123

{
  "data": {
    "list_id": "abc-123",
    "status": "completed",
    "total_count": 45230,
    "progress": 100
  }
}
```

## Exporting from a List

Once a list is completed, export its items:

```json theme={null}
POST /v1/lists/abc-123/export
{
  "fields": ["property_full_address", "estimated_value", "owner_full_name"]
}
```

Credits are charged per record at export time. Creating and building lists is free.

## Filtering Searches By List Membership

Property and people search/count/export endpoints can include or exclude list membership directly:

```json theme={null}
{
  "locations": [],
  "include_lists": { "property_list_ids": [123] },
  "exclude_lists": { "property_list_ids": [456] }
}
```

Use `people_list_ids` for people lists. These fields use the Query Builder protocol; the API key's organization supplies the required organization and partition values automatically.

## Limits

| Constraint                | Value                      |
| ------------------------- | -------------------------- |
| Max items per list        | 1,000,000                  |
| Max lists per account     | Unlimited                  |
| List retention            | Indefinite (until deleted) |
| Concurrent builds per org | 1                          |

## Using Lists with Search

Lists can be used as include/exclude filters in searches:

* **Include**: only return records that are in the list
* **Exclude**: skip records that are in the list

This is useful for suppression (e.g., "exclude everyone I already exported").