Filtering with ExtraCategories

Overview

Several queries (like paginatedUsers) support filtering by ExtraCategory values. This allows you to find users, groups, or other objects based on custom field values — for example, "all users in department Marketing" or "all users hired after 2024".

ExtraCategoryFilterInput

The filter input has this structure:

input ExtraCategoryFilterInput {
  id: UUID!                    # The ExtraCategory ID to filter on
  type: ExtraCategoryFilterType!  # STRING, BOOLEAN, or DATETIME
  stringValue: String          # For STRING type
  booleanValue: Boolean        # For BOOLEAN type
  datetimeValue: DateTime      # For DATETIME type
  dateComparison: DateComparison  # GREATER_THAN or LESSER_THAN (for DATETIME)
}

Filter by text/choice value

query {
  paginatedUsers(
    first: 50
    extraCategories: [
      {
        id: "uuid-of-department-category"
        type: STRING
        stringValue: "Marketing"
      }
    ]
  ) {
    edges {
      node { id name email }
    }
    count
  }
}

For SELECT and MULTISELECT categories, use type: STRING and pass the choice option's stringValue.

Filter by boolean

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-of-active-employee-category"
        type: BOOLEAN
        booleanValue: true
      }
    ]
    first: 50
  ) {
    edges {
      node { id name }
    }
  }
}

Filter by date

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-of-hire-date-category"
        type: DATETIME
        datetimeValue: "2024-01-01T00:00:00Z"
        dateComparison: GREATER_THAN
      }
    ]
    first: 50
  ) {
    edges {
      node { id name }
    }
  }
}

GREATER_THAN means "on or after". LESSER_THAN means "on or before".

Combining multiple filters

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-department"
        type: STRING
        stringValue: "Marketing"
      },
      {
        id: "uuid-active"
        type: BOOLEAN
        booleanValue: true
      }
    ]
    first: 50
  ) {
    edges {
      node { id name email }
    }
    count
  }
}

Filter logic

• Filters with different category IDs are combined with AND — the object must match all of them.
• Filters with the same category ID are combined with OR — the object must match at least one.

Example: "Users in Marketing OR Sales who are active employees"

extraCategories: [
  { id: "uuid-department", type: STRING, stringValue: "Marketing" },
  { id: "uuid-department", type: STRING, stringValue: "Sales" },
  { id: "uuid-active", type: BOOLEAN, booleanValue: true }
]

This returns users where (department = Marketing OR department = Sales) AND (active = true).

Step 1: Find the category ID

query {
  extraCategories(contentType: USER) {
    id
    title
    categoryType
    choiceOptions {
      id
      stringValue
    }
  }
}