Returns the users matching an ad hoc filter, in the same shape as GET /users. The filter uses the same QueryBuilder JSON as saved lists (POST /user_lists), so anything you can build in the dashboard People page can be sent here directly without creating a saved list first.

The request is a POST because filters can be long and may contain personal data (emails, phone numbers) that should not travel in a URL. Pagination (limit, offset), _since, phone_number, and email are sent in the body and compose with the filter exactly as they do on GET /users. Results respect the API key's scope: a sub organization key only receives people in its own chapters.

Validation fails closed. Every rule id must be one the filter engine recognises; an unknown id (for example a typo like user.tag instead of user.tags) returns 422 rather than being ignored, because an ignored rule would widen the result to everyone. Recognised ids are the static ids listed below, cup.<internal_name> for a custom property in your organization (see GET /custom_user_properties), and obj.<internal_name>.<field> for a field of an object custom property. A list rule may only reference saved lists in your organization.

Static rule ids: action_page.form_question, action_page.submitted, action_page.utm_data, action_page.viewed, assessment.changed_at, assessment.changed_to_status_at, assessment.new, assessment.old, assessment.on_date, automation.completed, automation.enrolled, automation.goal_met, automation.step_completed, automation.triggering_message_content, call.dialer_calls_by_disposition, call.engagement_analysis, call.has_called_us, call.phonebank_attempt_reached, call.phonebank_contact_attempt, call.search_notes, call.status, canvass.canvassed_in_canvass, canvass.in_turf, canvass.knock_result, canvass.knocked_by, canvass.targeted_in_canvass, chapter_permission.call, chapter_permission.email, chapter_permission.sms_blast, chapter_permission.sms_p2p, cup_change.property, email_message.bounced, email_message.clicked, email_message.clicked_advanced, email_message.opened, email_message.opened_advanced, email_message.received, email_message.received_any_email, event.attended, event.attended_count, event.attended_event_with_tag, event.attended_to_calendar_item, event.invited_to, event.near_upcoming, event.rsvpd_count, event.rsvpd_to_calendar_item, event.rsvpd_to_event, event.rsvpd_to_event_with_tag, event.session_time_busy, event.show_rate, field_survey.assisted_by, finance.actblue_contribution_form, finance.actblue_refcode, finance.donation_date, finance.donation_match, finance.has_active_recurring_donation, finance.has_donated, finance.is_active_dues_payer, finance.total_donated, finance.total_donated_in_period, funnel.at_stage, funnel.enrolled, list, location.branches, location.chapter_status, location.chapters, location.coordinates, location.counties, location.legislative_districts, location.precincts, location.primary_chapter, location.zip_code, text_message.clicked_advanced, text_message.has_texted_us, text_message.last_message_to_them, text_message.received, text_message.received_any_text, text_message.status, text_message.textbank_contact_attempt, text_message.textbank_reply, text_message.textbank_reply_category, text_message.texted_by_team_member, time.account_created, time.activity, time.added_from_app, time.assessment_created, user.account_type, user.address1, user.age, user.agent, user.alternate_name, user.any_language, user.assessment, user.call_permission, user.city_name, user.country, user.created_with_data_import, user.date_of_birth, user.demand_vote_choice, user.email, user.email_permission, user.first_name, user.follow_up_status, user.id, user.included_in_data_import, user.is_team_member, user.joined_by_method, user.last_name, user.last_seen_on, user.page_submission_referral_count, user.paid_dues_expires_at, user.paid_dues_since, user.peer_to_peer_sms_permission, user.phone_number, user.postal_code, user.preferred_language, user.referred_by_id, user.referred_page_submission_by_id, user.relationship, user.second_language, user.secondary_languages, user.sms_permission, user.state, user.tags, user.timezone, user.total_people_referred_count, user.updated_with_data_import.

Pagination within one crawl is stable: the first page (_offset 0) resolves the matching people live and later pages of the same filter are served from that snapshot for up to 15 minutes, so a person added or removed mid-crawl appears on the next crawl rather than shifting the current one. total_count in meta may be cached for up to 30 minutes for the same filter.