Skip to main content
POST
/
v1
/
lists
Create List
curl --request POST \
  --url https://api.example.com/v1/lists \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "source_type": "<string>",
  "filters": [
    {}
  ],
  "locations": [
    {}
  ],
  "record_ids": [
    {}
  ]
}
'
{
  "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"
  }
}
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.
​
name
string
required
Display name for the list (1-255 characters).
​
source_type
string
default:"properties"
Type of records: properties or people.
​
filters
array
Search filters to build the list from. Same format as property/people search.
​
locations
array
Location filters. Same format as property/people search.
​
record_ids
array
Array of property or person IDs to pre-populate the list (1-250 IDs). Cannot be combined with filters or locations.
{
  "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"
  }
}