Filtering & Sorting
Advanced query techniques with 50+ filter matchers and sorting options
Wicket's API provides powerful filtering and sorting capabilities to help you query exactly the data you need.
Sorting
Basic Sorting
Sort results by any attribute using the sort parameter:
GET /people?sort=family_nameDescending Sort
Prepend a minus sign (-) for descending order:
GET /people?sort=-created_atMultiple Sort Fields
Sort by multiple attributes using a comma-separated list:
GET /people?sort=given_name,-family_nameThis sorts by given_name ascending, then family_name descending.
Example
# Fetch people sorted by last name ascending, then first name descending
curl -X GET 'https://tenant-api.wicketcloud.com/people?sort=family_name,-given_name' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/vnd.api+json'Filtering
Filter Syntax
Filters use query string parameters with this format:
?filter[<attribute>_<predicate>]=<value>attribute: The field name (e.g.,updated_at,given_name)predicate: The filter matcher (e.g.,eq,gteq,cont)value: The value to filter by
Basic Examples
Exact Match
Find people with a specific given name:
GET /people?filter[given_name_eq]=JohnGreater Than or Equal
Find people updated on or after a specific date:
GET /people?filter[updated_at_gteq]=2021-04-25T00:00:00+00:00Contains
Find people whose email contains "gmail":
GET /people?filter[email_cont]=gmailMultiple Filters
Combine filters with AND logic:
GET /people?filter[given_name_eq]=John&filter[family_name_eq]=SmithThis returns people where given_name is "John" AND family_name is "Smith".
Complex Filtering with POST
For complex queries, use POST requests to /query endpoints:
POST /people/query?include=emails,phones,addresses
Content-Type: application/vnd.api+json{
"filter": {
"connections_organization_uuid_eq": "73cd91c1-76e4-4421-84df-acf1452cb8bc",
"connections_tags_name_eq": "Employee",
"membership_people_membership_uuid_in": [
"8ddce1e-6938-4216-9ce9-f24a6b7cd677"
],
"membership_people_status_eq": "Active"
}
}Available query endpoints:
/connections/query/groups/query/group_members/query/organizations/query/organization_memberships/query/people/query/person_memberships/query
Search with OR Logic
Use search_query with _or for OR logic:
{
"filter": {
"search_query": {
"_or": [
{ "data_fields.section.value.field": "value" },
{ "data_fields.section2.value.field2": "value" }
]
}
}
}Filter Predicates Reference
Wicket supports 50+ filter predicates:
Equality Predicates
| Predicate | Description | Example |
|---|---|---|
*_eq | Equal | filter[given_name_eq]=John |
*_not_eq | Not equal | filter[status_not_eq]=inactive |
Comparison Predicates
| Predicate | Description | Example |
|---|---|---|
*_lt | Less than | filter[age_lt]=30 |
*_lteq | Less than or equal | filter[age_lteq]=30 |
*_gt | Greater than | filter[age_gt]=18 |
*_gteq | Greater than or equal | filter[created_at_gteq]=2021-01-01 |
Pattern Matching Predicates
| Predicate | Description | SQL Equivalent | Example |
|---|---|---|---|
*_matches | Matches with LIKE | LIKE '%value%' | filter[email_matches]=%@gmail.com |
*_does_not_match | Does not match | NOT LIKE '%value%' | filter[email_does_not_match]=%test% |
*_start | Starts with | LIKE 'value%' | filter[family_name_start]=Sm |
*_not_start | Does not start with | NOT LIKE 'value%' | filter[family_name_not_start]=A |
*_end | Ends with | LIKE '%value' | filter[email_end]=.com |
*_not_end | Does not end with | NOT LIKE '%value' | filter[email_not_end]=.org |
*_cont | Contains | LIKE '%value%' | filter[full_name_cont]=john |
Null/Empty Predicates
| Predicate | Description | SQL Equivalent |
|---|---|---|
*_present | Not null and not empty | col IS NOT NULL AND col != '' |
*_blank | Is null or empty | col IS NULL OR col = '' |
*_null | Is null | col IS NULL |
*_not_null | Is not null | col IS NOT NULL |
Example:
# Find people with a job title
GET /people?filter[job_title_present]=1
# Find people without a birth date
GET /people?filter[birth_date_blank]=1Array Predicates
| Predicate | Description | Example |
|---|---|---|
*_in | Match any value in array | filter[uuid_in][]=uuid1&filter[uuid_in][]=uuid2 |
*_not_in | Match none of the values | filter[status_not_in][]=archived&filter[status_not_in][]=deleted |
Example:
# Find people with specific UUIDs
GET /people?filter[uuid_in][]=8f24a446-acac-40bb-8ff3-e6abc051c362&filter[uuid_in][]=another-uuidAdvanced Predicates
| Predicate | Description | SQL Equivalent |
|---|---|---|
*_matches_any | Matches any (with LIKE) | LIKE val1 OR LIKE val2 |
*_matches_all | Matches all (with LIKE) | LIKE val1 AND LIKE val2 |
*_lt_any | Less than any | col < val1 OR col < val2 |
*_gt_any | Greater than any | col > val1 OR col > val2 |
*_lt_all | Less than all | col < val1 AND col < val2 |
*_gt_all | Greater than all | col > val1 AND col > val2 |
Real-World Examples
Find Recent Updates
People updated in the last 7 days:
GET /people?filter[updated_at_gteq]=2024-01-10T00:00:00Z&sort=-updated_atFind Active Members
People with active membership status:
GET /people?filter[membership_people_status_eq]=ActiveSearch by Email Domain
People with Gmail addresses:
GET /people?filter[email_matches]=%@gmail.comFind People by Multiple UUIDs
GET /people?filter[uuid_in][]=uuid-1&filter[uuid_in][]=uuid-2&filter[uuid_in][]=uuid-3Complex Organization Query
Find active employees of a specific organization:
POST /people/query
Content-Type: application/vnd.api+json{
"filter": {
"connections_organization_uuid_eq": "org-uuid",
"connections_tags_name_eq": "Employee",
"membership_people_status_eq": "Active"
},
"sort": "family_name,-given_name",
"page": {
"number": 1,
"size": 50
}
}Combining Filters, Sorting, and Pagination
Combine all query features for powerful data retrieval:
GET /people?filter[updated_at_gteq]=2024-01-01&filter[membership_people_status_eq]=Active&sort=-updated_at&page[number]=1&page[size]=25This query:
- Filters people updated since January 1, 2024
- Filters to only active members
- Sorts by update date (newest first)
- Returns page 1 with 25 results
Best Practices
1. Use Specific Filters
Instead of fetching all records and filtering client-side:
# ✅ Good: Filter on the server
GET /people?filter[status_eq]=Active
# ❌ Avoid: Fetch all and filter client-side
GET /people
# Then filter in your code2. Combine with Pagination
Always paginate when filtering large datasets:
GET /people?filter[updated_at_gteq]=2024-01-01&page[size]=1003. Use POST for Complex Filters
When filters get complex or exceed URL length limits, use POST:
POST /people/query4. Index-Friendly Filters
Filter on indexed fields for better performance:
uuidcreated_atupdated_atemail- Foreign keys (organization_uuid, etc.)
5. Date Filtering
Always use ISO 8601 format with timezone:
# ✅ Good: ISO 8601 with timezone
filter[updated_at_gteq]=2024-01-01T00:00:00+00:00
# ❌ Avoid: Ambiguous date format
filter[updated_at_gteq]=2024-01-01Performance Tips
-
Use sparse fieldsets to reduce payload size:
GET /people?filter[status_eq]=Active&fields[people]=uuid,given_name,family_name -
Avoid overly broad filters like
*_conton large datasets -
Use
presentinstead ofnot_nullwhen checking for meaningful values -
Combine filters instead of making multiple requests
-
Cache results when appropriate to reduce API calls