Skip to main content

​
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

ConstraintValue
Max items per list1,000,000
Max lists per accountUnlimited
List retentionIndefinite (until deleted)
Concurrent builds per org1
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”).