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

# Create List

> Create a new list, optionally building from search filters

Create a new saved list. Three modes:

1. **Filters/locations** — builds asynchronously from matching records. Poll `GET /v1/lists/:list_id` until status is `"completed"`.
2. **Record IDs** — pass up to 250 property or person IDs to create a pre-populated list synchronously. Returns with status `"completed"`.
3. **Empty** — no filters, locations, or record\_ids creates an empty list.

`record_ids` and `filters`/`locations` are mutually exclusive — providing both returns a 400 error.

<ParamField body="name" type="string" required>
  Display name for the list (1-255 characters).
</ParamField>

<ParamField body="source_type" type="string" default="properties">
  Type of records: `properties` or `people`.
</ParamField>

<ParamField body="filters" type="array">
  Search filters to build the list from. Same format as property/people search.
</ParamField>

<ParamField body="locations" type="array">
  Location filters. Same format as property/people search.
</ParamField>

<ParamField body="record_ids" type="array">
  Array of property or person IDs to pre-populate the list (1-250 IDs). Cannot be combined with `filters` or `locations`.
</ParamField>

<ResponseExample>
  ```json 202 Building theme={null}
  {
    "data": {
      "list_id": "abc-123-def-456",
      "name": "High Value Properties in Miami",
      "source_type": "properties",
      "build_type": "prospect",
      "status": "building",
      "total_count": 0,
      "progress": 0,
      "estimated_count": 45230,
      "created_at": "2026-02-18T14:30:00Z",
      "updated_at": "2026-02-18T14:30:00Z"
    }
  }
  ```

  ```json 200 Pre-populated theme={null}
  {
    "data": {
      "list_id": "abc-123-def-456",
      "name": "My Selected Properties",
      "source_type": "properties",
      "build_type": "import",
      "status": "completed",
      "total_count": 3,
      "progress": 100,
      "created_at": "2026-02-18T14:30:00Z",
      "updated_at": "2026-02-18T14:30:00Z"
    }
  }
  ```

  ```json 200 Empty List theme={null}
  {
    "data": {
      "list_id": "abc-123-def-456",
      "name": "My Empty List",
      "source_type": "properties",
      "build_type": "prospect",
      "status": "idle",
      "total_count": 0,
      "progress": 0,
      "created_at": "2026-02-18T14:30:00Z",
      "updated_at": "2026-02-18T14:30:00Z"
    }
  }
  ```

  ```json 400 Mutual Exclusivity theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Cannot provide both record_ids and filters/locations. Use record_ids for a pre-populated list or filters/locations for an async build."
    }
  }
  ```

  ```json 400 Limit Exceeded theme={null}
  {
    "error": {
      "code": "list_limit_exceeded",
      "message": "List limited to 1,000,000 records. Your query matches 1,234,567 records. Narrow your filters.",
      "details": {
        "record_count": 1234567,
        "limit": 1000000
      }
    }
  }
  ```
</ResponseExample>