Lists

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

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):

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:

POST /v1/lists/:id/items
{
  "ids": [101, 202, 303],
  "id_type": "internal_property_id"
}

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

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:

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:

{
  "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”).

Getting Started

Searching

Data & Fields

Responses

Usage

CLI

Reference

AI Assistants

What are Lists?

The Search -> List -> Export Workflow

Creating a List

Creating a List from Specific IDs

Adding & Removing Items

Polling for Completion

Exporting from a List

Filtering Searches By List Membership

Limits

Using Lists with Search

​What are Lists?

​The Search -> List -> Export Workflow

​Creating a List

​Creating a List from Specific IDs

​Adding & Removing Items

​Polling for Completion

​Exporting from a List

​Filtering Searches By List Membership

​Limits

​Using Lists with Search

What are Lists?

The Search -> List -> Export Workflow

Creating a List

Creating a List from Specific IDs

Adding & Removing Items

Polling for Completion

Exporting from a List

Filtering Searches By List Membership

Limits

Using Lists with Search