Segments are saved filtered views of your portfolio. Each segment has a filter_backend that defines which listings belong to it — Wheelhouse evaluates the filter dynamically, so membership updates automatically as listing data changes. Use segments to scope bulk operations and reporting to a subset of your portfolio.
GET /segments
List all portfolio segments for the authenticated user.
curl "https://api.usewheelhouse.com/ss_api/v1/segments" \
-H "X-Integration-Api-Key: your_api_key_here"
Response
Returns a flat array of segment objects:
[
{
"id": 1001,
"name": "Beach Properties",
"description": "All oceanfront listings",
"is_default": false,
"created_at": "2025-06-01T10:00:00Z",
"updated_at": "2026-01-15T08:30:00Z"
},
{
"id": 1002,
"name": "Mountain Cabins",
"description": null,
"is_default": true,
"created_at": "2025-09-10T14:00:00Z",
"updated_at": "2026-02-20T11:00:00Z"
}
]
Response fields
id— Wheelhouse's internal segment ID (integer)name— the segment namedescription— optional description (nullable)filter_backend— the filter object defining which listings belong to this segment (see POST /segments for filter reference)is_default— whether this is the user's default segmentcreated_at/updated_at— ISO 8601 timestamps
POST /segments
Create a new portfolio segment.
curl -X POST "https://api.usewheelhouse.com/ss_api/v1/segments" \
-H "X-Integration-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Beach Properties",
"description": "All oceanfront listings",
"filter_backend": {
"bedrooms_gte": 2,
"source": "A",
"listings.title": "Beach,Ocean"
}
}'
Request body fields
name(string, required) — name of the segmentdescription(string, optional) — optional descriptionfilter_backend(object, optional) — filter definition controlling which listings belong to this segment (see below)is_default(boolean, optional) — set as the user's default segment; any existing default is cleared
filter_backend structure
The filter_backend is a flat object where each key is a listing attribute path with an optional operator suffix, and the value is the match criterion. All conditions are ANDed — a listing must match every condition to be included. Boolean filters (no suffix, accept true/false):
is_live— listing is live on its channellistings.is_active— listing is active in Wheelhouselisting_preferences.automatic_rate_posting_enabled— auto rate posting is on
Numeric range filters (suffixes: none =, _ne ≠, _lt <, _gt >, _lte ≤, _gte ≥):
bedrooms,bathrooms,sleeps,bedslisting_preferences.base_price,listing_preferences.weekly_discount,listing_preferences.monthly_discountPerformance:
listing_stats.{revenue|occupancy|booking_count}_{days_ahead}_{days_behind}(e.g.listing_stats.revenue_0_30_gte)
Enumeration filters (suffixes: none =, _ne ≠):
source— channel ID:"A"(Airbnb),"V"(Vrbo),"B"(Booking.com)market_id— Wheelhouse market ID (integer)country_code— ISO 3166-1 alpha-2 (e.g."US")listings.currency— ISO 4217 currency code
String match filters (suffixes: none contains, _not does not contain; comma-separate for OR):
listings.title,listing_views.display_name,source_address
Tag filters:
tags.id— listing has any of the listed tag IDs (OR)tags.id_ne— listing has none of the listed tag IDstags.id_and— listing has all of the listed tag IDs
Date range filters (same suffixes as numeric; values are ISO 8601 date strings or integers for rolling days):
listings.created_at,listing_stats.last_booked_at
Membership filters:
listings.id_in/listings.id_not_in— include/exclude specific listing IDslatlong_distance_from_lte— value format:"latitude,longitude,meters"
Example:
{
"is_live": true,
"bedrooms_gte": 2,
"source": "A",
"listings.title": "Beach,Ocean",
"tags.id_pool": [12],
"listings.created_at_gte": "2025-01-01"
}
Status codes
201— segment created; response is the new segment object400— invalid request body (e.g.nameis missing)403— read-only API key cannot create segments
PUT /segments/:segment_id
Update an existing portfolio segment. All fields are optional — omitted fields are left unchanged.
curl -X PUT "https://api.usewheelhouse.com/ss_api/v1/segments/1001" \
-H "X-Integration-Api-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Beachfront Properties",
"is_default": true
}'
Path parameters
segment_id(integer, required) — Wheelhouse internal segment ID
Request body fields
name(string, optional) — new name for the segmentdescription(string, optional) — new descriptionfilter_backend(object, optional) — updated filter definition (same structure as POST)is_default(boolean, optional) — promote to default segment; any existing default is cleared
Status codes
200— updated segment returned403— read-only API key cannot update segments404— segment not found or does not belong to the authenticated user
GET /segments/:segment_id/listings
List the listings that belong to a portfolio segment. The segment's filter criteria are evaluated at request time.
curl "https://api.usewheelhouse.com/ss_api/v1/segments/1001/listings" \
-H "X-Integration-Api-Key: your_api_key_here"
Path parameters
segment_id(integer, required) — Wheelhouse internal segment ID
Query parameters
exclude_inactive(boolean, optional, default:true) — exclude inactive listings from the responseper_page(integer, optional, default:50) — number of listings per pagepage(integer, optional) — page numberoffset(integer, optional) — number of items to skip; alternative topage
Response Returns a flat array of listing objects in the same format as GET /listings. Status codes
200— array of listings404— segment not found
Related
Dynamic Sets: Competitive Benchmarking
Tags & Flags: Custom labels and system indicators
How to organize and filter listings (tags, segments, dynamic sets)