listUsers
Get a paginated list of all members with filtering by user fields and sorting. Use for reports, CSV exports, and bulk status updates.
Instructions
List members/users - Get a paginated list of all members. Supports filtering by any user field and sorting.
Lean-by-default keep-list: rows return only identity + routing + location core: user_id, first_name, last_name, email, company, phone_number, subscription_id, profession_id, active, status, city, state_code, country_code, filename, image_main_file, signup_date, last_login, modtime. Everything else stripped — restore via flags: include_password=1, include_subscription=1 (full subscription_schema), include_clicks=1 (full click array), include_photos=1 (full photos_schema), include_transactions=1, include_profession=1 (profession_schema), include_tags=1, include_services=1 (services_schema), include_seo_hidden=1, include_about=1 (about_me HTML bio), include_legacy_fields=1 (image-import state on photos, requires include_photos), include_extras=1 (everything else — billing/analytics rollups like revenue/card_info/total_clicks/total_photos, duplicate location fields state_ln/country_ln/full_name/user_location/zip_code/lat/lon, plus social URLs, awards, credentials, position, quote, work_experience, rep_matters, cv, gmap, no_geo, user_consent, sign_up_origin, listing_type, profession_name, ref_code, booking_link, bitly, cookie, token, verified, featured, parent_id, clientid, etc.).
Use when: enumerating members for reports, CSV exports, bulk status updates, analytics, or pagination through the full member base. Also used for lookups by field - pass property=email + property_value=<email> to find a single user by email. For keyword/text search use searchUsers; for a single user by known user_id use getUser. Do NOT bulk-list users to enumerate cities the site has on file — use listCities (lean, BD-curated, surfaces only cities where members exist).
Pagination: cursor-based. Pass limit (default 25, max 100) and page token from the previous response's next_page. Do not assume integer offsets.
Filter/sort: property+property_value+property_operator, order_column+order_type. See Rule: Filter operators for the verified-working operator set, silent-drop detection, and derived-field unfilterability.
Enums: property_operator: =, LIKE, >, <, >=, <=; order_type: ASC, DESC.
Filter-property rule - use ACTUAL field names: property must reference a real column on users_data or a valid custom user field. If you don't know what's filterable, call getUserFields first - it returns the authoritative list for this site (includes custom fields). BD returns misleading errors like "user not found" when property names a nonexistent field - that is a BAD FILTER, not a 404 on the endpoint. Do not invent properties like user_group (not a real column).
Filtering by TOP CATEGORY (profession): the filter column is profession_id (integer), not a category name string. If the caller gives you a category name, chain: (1) listTopCategories -> find the row whose name matches; (2) grab its profession_id; (3) call listUsers with property=profession_id&property_value=<id>. Same principle for any taxonomy filter - resolve names to IDs first via listSubCategories, listMembershipPlans, etc. For sub-category filtering on users, the authoritative approach is listMemberSubCategoryLinks filtered by service_id -> collect user_ids -> fetch those users. (There is also a service CSV column on user records but exact-match filtering on it requires the complete CSV value and LIKE syntax support is not guaranteed - prefer the link-table route.)
Filtering by users_meta (custom/meta fields): multi-value meta filtering IS supported via the array syntax - e.g. property[]=<meta_key>&property_value[]=foo&property[]=<meta_key>&property_value[]=bar&property_operator[]=OR&property_logic[]==. Use this for OR-across-meta-values lookups (e.g. members whose custom field equals any of N options).
Payment-method field (under include_extras=1): card_info is false when no card is on file (BD's convention), or an object with last4/brand/name when a card IS stored. Check card_info && card_info.last4 (truthy-guard). Authoritative signal for "does this member have a valid payment method on file" — do not infer from subscription_id alone.
See also: getUser (single record by ID), searchUsers (keyword search), getUserFields (list filterable fields).
Returns: { status: "success", total, current_page, total_pages, next_page, prev_page, message: [...records] }. Each record is lean-shaped per the keep-list above.
Profile URL: every user record has a filename field. To get the full public profile URL, concatenate: <site-domain>/<user.filename>. The filename is the complete relative path (e.g., united-states/monterey-park/doctor/harrison-hasanuddin-d-o) - DO NOT prepend /business/, /profile/, /member/, or any other segment. BD's router resolves filename verbatim.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_password | No | Opt in to return bcrypt `password` hash. Default stripped. | |
| include_subscription | No | Opt in to return full `subscription_schema` (60+ plan fields). Default: `subscription_id` only. | |
| include_clicks | No | Opt in to return `user_clicks_schema.clicks` array. Default: `total_clicks` count surfaced only when > 0; absent means zero clicks. | |
| include_photos | No | Opt in to return `photos_schema` array. Default: `total_photos` count only (`image_main_file` URL always returned). | |
| include_transactions | No | Opt in to return full `transactions` invoice array. Default stripped (`revenue` rollup always returned). | |
| include_profession | No | Opt in to return `profession_schema` (category metadata). Default: `profession_id` only. | |
| include_tags | No | Opt in to return `tags` array. Default stripped. | |
| include_services | No | Opt in to return `services_schema` sub-category array. Default stripped. | |
| include_seo_hidden | No | Opt in to return SEO meta fields (`seo_page_*_hidden`, `seo_social_*_hidden`, `search_description`). Default stripped. | |
| include_about | No | Opt in to return the `about_me` HTML bio. Default stripped. | |
| include_legacy_fields | No | Return image-import state on `photos_schema` rows: `original`, `resized`, `error`. Requires `include_photos=1`. | |
| include_extras | No | Opt in to return ALL remaining fields on this resource that are not in the lean-by-default keep-list and not gated by another `include_*` flag. Lean default returns only the core identity, routing, and load-bearing fields. `include_extras=1` restores everything else (geo, all hero_*, layout/sidebar/menu config, all display toggles, admin metadata, etc.). Resource-specific — see each tool's description for what the extras bundle contains. | |
| limit | No | Records per page (default 25, max 100) | |
| page | No | Pagination cursor (use next_page from previous response) | |
| property | No | Field name to filter by | |
| property_value | No | Value to filter by | |
| property_operator | No | Filter operator (word-form; symbol forms WAF-stripped). Single: eq, ne, lt, lte, gt, gte, like, not_like. CSV: in, not_in, between. Substring: contains, starts_with, ends_with (+not_). Date: year_eq, month_eq, day_eq (+not_), since_days, until_days. Length: length_eq, length_lt, length_gt, length_between. Null: is_set, is_not_set, is_null, is_not_null. See Rule: Filter operators for value shapes. | |
| order_column | No | Column to sort by | |
| order_type | No | Sort direction: ASC or DESC |