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

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

1234567891011POST /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):

123456POST /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:

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

12345DELETE /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

12345678910GET /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:

1234POST /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:

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