Pre-release — content may change.

Concepts

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_name

Descending Sort

Prepend a minus sign (-) for descending order:

GET /people?sort=-created_at

Multiple Sort Fields

Sort by multiple attributes using a comma-separated list:

GET /people?sort=given_name,-family_name

This 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]=John

Greater Than or Equal

Find people updated on or after a specific date:

GET /people?filter[updated_at_gteq]=2021-04-25T00:00:00+00:00

Contains

Find people whose email contains "gmail":

GET /people?filter[email_cont]=gmail

Multiple Filters

Combine filters with AND logic:

GET /people?filter[given_name_eq]=John&filter[family_name_eq]=Smith

This 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

PredicateDescriptionExample
*_eqEqualfilter[given_name_eq]=John
*_not_eqNot equalfilter[status_not_eq]=inactive

Comparison Predicates

PredicateDescriptionExample
*_ltLess thanfilter[age_lt]=30
*_lteqLess than or equalfilter[age_lteq]=30
*_gtGreater thanfilter[age_gt]=18
*_gteqGreater than or equalfilter[created_at_gteq]=2021-01-01

Pattern Matching Predicates

PredicateDescriptionSQL EquivalentExample
*_matchesMatches with LIKELIKE '%value%'filter[email_matches]=%@gmail.com
*_does_not_matchDoes not matchNOT LIKE '%value%'filter[email_does_not_match]=%test%
*_startStarts withLIKE 'value%'filter[family_name_start]=Sm
*_not_startDoes not start withNOT LIKE 'value%'filter[family_name_not_start]=A
*_endEnds withLIKE '%value'filter[email_end]=.com
*_not_endDoes not end withNOT LIKE '%value'filter[email_not_end]=.org
*_contContainsLIKE '%value%'filter[full_name_cont]=john

Null/Empty Predicates

PredicateDescriptionSQL Equivalent
*_presentNot null and not emptycol IS NOT NULL AND col != ''
*_blankIs null or emptycol IS NULL OR col = ''
*_nullIs nullcol IS NULL
*_not_nullIs not nullcol 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]=1

Array Predicates

PredicateDescriptionExample
*_inMatch any value in arrayfilter[uuid_in][]=uuid1&filter[uuid_in][]=uuid2
*_not_inMatch none of the valuesfilter[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-uuid

Advanced Predicates

PredicateDescriptionSQL Equivalent
*_matches_anyMatches any (with LIKE)LIKE val1 OR LIKE val2
*_matches_allMatches all (with LIKE)LIKE val1 AND LIKE val2
*_lt_anyLess than anycol < val1 OR col < val2
*_gt_anyGreater than anycol > val1 OR col > val2
*_lt_allLess than allcol < val1 AND col < val2
*_gt_allGreater than allcol > 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_at

Find Active Members

People with active membership status:

GET /people?filter[membership_people_status_eq]=Active

Search by Email Domain

People with Gmail addresses:

GET /people?filter[email_matches]=%@gmail.com

Find People by Multiple UUIDs

GET /people?filter[uuid_in][]=uuid-1&filter[uuid_in][]=uuid-2&filter[uuid_in][]=uuid-3

Complex 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]=25

This query:

  1. Filters people updated since January 1, 2024
  2. Filters to only active members
  3. Sorts by update date (newest first)
  4. 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 code

2. Combine with Pagination

Always paginate when filtering large datasets:

GET /people?filter[updated_at_gteq]=2024-01-01&page[size]=100

3. Use POST for Complex Filters

When filters get complex or exceed URL length limits, use POST:

POST /people/query

4. Index-Friendly Filters

Filter on indexed fields for better performance:

  • uuid
  • created_at
  • updated_at
  • email
  • 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-01

Performance Tips

  1. Use sparse fieldsets to reduce payload size:

    GET /people?filter[status_eq]=Active&fields[people]=uuid,given_name,family_name
  2. Avoid overly broad filters like *_cont on large datasets

  3. Use present instead of not_null when checking for meaningful values

  4. Combine filters instead of making multiple requests

  5. Cache results when appropriate to reduce API calls

On this page