This document covers searching and filtering both user profiles and groups in ThoughtFarmer. Both endpoints support full-text search, filtering by tags, ownership, and date-based criteria.

Endpoints

• Search Users
• Search Groups

Search Users API

Endpoint

POST /api/search/users

Pagination

All search results are paginated. The default page size is defined by api.defaultPageSize (typically 10), with a maximum of 1000 items per page.

Parameters:

• pageNumber - Page number to retrieve (default: 1)
• pageSize - Number of results per page (default: api.defaultPageSize, max: 1000)

Response includes:

• items - Array of user results
• totalItems - Total number of matching users
• pageNumber - Current page number
• pageSize - Items per page

Search Parameters

Query

forQuery (string) Full-text search query. Searches across user names, profile content, and other profile fields.

{
  "forQuery": "john smith"
}

Group Filtering

forGroups (array of integers) Filter by users who are members of ALL specified groups (AND logic). Provide group content IDs.

{
  "forGroups": [12345, 67890]
}

forAnyOfTheseGroups (array of integers) Filter by users who are members of ANY of the specified groups (OR logic). Provide group content IDs.

{
  "forAnyOfTheseGroups": [12345, 67890, 11111]
}

Note: Use the /api/groups endpoints to retrieve group content IDs. You can search groups by name or list all groups to find the IDs you need.

Tag Filtering

forTags (array of integers) Filter by tag IDs applied to user profiles. Tag IDs can be obtained from the /api/tagbundles endpoints.

{
  "forTags": [5, 12, 24]
}

Custom Field Filtering

forCustomFields (dictionary) Filter by tag-type custom field values. This parameter only works with custom fields of type "Tag".

The dictionary key is the custom field ID (string), and the value is a list of tag IDs (integers) to filter by.

Custom field IDs can be obtained from /api/customfields. Tag IDs can be obtained from /api/tagbundles.

{
  "forCustomFields": {
    "42": [101, 102],
    "55": [200]
  }
}

This example finds users where tag custom field 42 has tags 101 OR 102, AND tag custom field 55 has tag 200.

Note: For other custom field types (text, textarea, rich text, dropdown, etc.), the content is indexed and searchable using the forQuery parameter instead.

forCustomFieldDates (dictionary) Filter by custom date field values. Provides flexible date filtering for anniversary dates, hire dates, or any custom date fields.

The dictionary key can be either:

• The custom field ID as a string (e.g., "42")
• The custom field label (e.g., "Hire Date")

The value is a dictionary of DateFilter types and their corresponding values.

DateFilter types:

• Day - Filter by day of month (1-31)
• Month - Filter by month (1-12)
• Year - Filter by year (e.g., 2025)
• Between - Date range (format: "YYYY-MM-DD and YYYY-MM-DD")
• Before - Before a specific date (ISO 8601 format)
• After - After a specific date (ISO 8601 format)

Important: Between, Before, and After cannot be combined with other filters for the same field.

Example - Find users with hire date in specific month:

{
  "forCustomFieldDates": {
    "Hire Date": {
      "Month": "3"
    }
  }
}

Example - Find users hired between dates:

{
  "forCustomFieldDates": {
    "42": {
      "Between": "2024-01-01 and 2024-12-31"
    }
  }
}

Example - Find users with hire date after a specific date:

{
  "forCustomFieldDates": {
    "Hire Date": {
      "After": "2024-01-01"
    }
  }
}

Example - Multiple date filters:

{
  "forCustomFieldDates": {
    "Hire Date": {
      "Month": "6",
      "Year": "2024"
    }
  }
}

Name Filtering

forFirstLetterOfLastName (string) Filter users by first letter of last name.

{
  "forFirstLetterOfLastName": "S"
}

Sorting

sortType (SortType enum) Values: DateCreated, DateModified, DatePublished, LastName, Relevance, Title Default: Relevance

sortDirection (SortDirection enum) Values: Ascending, Descending Default: Descending

{
  "sortType": "LastName",
  "sortDirection": "Ascending"
}

Examples

Search users by name

{
  "forQuery": "john",
  "pageSize": 20
}

Users in specific group

First, get the group content ID using /api/search/groups:

{
  "forQuery": "Engineering"
}

Then search for users in that group:

{
  "forGroups": [12345]
}

Users in any of multiple groups

{
  "forAnyOfTheseGroups": [12345, 67890, 11111]
}

Users with specific tag custom field values

First, get custom field IDs from /api/customfields and tag IDs from /api/tagbundles:

{
  "forCustomFields": {
    "42": [101, 102, 103]
  }
}

Users with text in custom fields

For non-tag custom fields (text, dropdown, etc.), use the query parameter:

{
  "forQuery": "senior developer"
}

Users hired in a date range

POST /api/search/users

{
  "forCustomFieldDates": {
    "42": {
      "Between": "2024-01-01 and 2024-03-31"
    }
  }
}

Complex query: Users in group with specific custom field, sorted by last name

POST /api/search/users

{
  "forGroups": [12345],
  "forCustomFields": {
    "55": [200]
  },
  "sortType": "LastName",
  "sortDirection": "Ascending",
  "pageSize": 50
}

Users with last name starting with S, in specific groups

{
  "forFirstLetterOfLastName": "S",
  "forAnyOfTheseGroups": [12345, 67890]
}

Users hired after a specific date with specific tag

{
  "forCustomFieldDates": {
    "Hire Date": {
      "After": "2024-06-01"
    }
  },
  "forTags": [42]
}

Deprecated Parameters

The following parameters are deprecated. Use /api/users/upcomingbirthdays or /api/users/upcominganniversaries endpoints instead:

• forBirthdayDay, forBirthdayMonth, forBirthdayYear
• forAnniversaryDay, forAnniversaryMonth, forAnniversaryYear

Related Documentation

• Groups API - Available in Swagger documentation at /swagger (use to find group content IDs)
• Tag Bundles API - Available in Swagger documentation at /swagger (use to find tag IDs)
• Custom Fields API - Use /api/customfields to retrieve custom field IDs and types

Notes

• Custom Fields for Tags: The forCustomFields parameter only works with tag-type custom fields. Get custom field IDs from /api/customfields and tag IDs from /api/tagbundles.
• Custom Fields for Text: Text-based custom fields (text, textarea, rich text, dropdown, etc.) are indexed and searchable via the forQuery parameter.
• Custom Field Labels: When using forCustomFieldDates, you can reference custom fields by their label (e.g., "Hire Date") instead of their numeric ID for convenience.
• Group Membership: Use forGroups when users must be members of ALL groups, and forAnyOfTheseGroups when users need to be in ANY of the groups.

Search Groups API

Endpoint

POST /api/search/groups

Pagination

Same as user search - see Pagination section above.

Search Parameters

Many parameters are shared with the user search endpoint. Parameters that work identically are grouped below.

Shared Parameters

The following parameters work the same as in the user search endpoint:

• forQuery - Full-text search across group names and content
• forTags - Filter by tag IDs (from /api/tagbundles)
• forOwnedBy - Filter by owner user IDs
• forFirstLetterOfTitle - Filter groups by first letter of title
• includeArchived - Include archived groups (default: false)
• sortType / sortDirection - Control result ordering
• pageNumber / pageSize - Pagination controls

See the corresponding sections above for detailed descriptions.

Group-Specific Parameters

forContentIds (array of integers) Filter to return only groups with specific content IDs.

{
  "forContentIds": [12345, 67890]
}

forGroupTypes (array of integers) Filter by group type IDs. Group type IDs can be obtained from the /api/grouptypes endpoint.

{
  "forGroupTypes": [1, 2]
}

forPublishedDate (DateFacetRange enum) Filter groups by published date range.

Values: None, Last24Hours, Last7Days, Last30Days, Last3Months, Last6Months, LastYear, Over1Year

{
  "forPublishedDate": "Last30Days"
}

Examples

Search groups by name

{
  "forQuery": "engineering",
  "pageSize": 20
}

Groups of specific type

First, get group type IDs from /api/grouptypes:

GET /api/grouptypes

Then search for groups of that type:

POST /api/search/groups

{
  "forGroupTypes": [1, 2]
}

Groups created in last 30 days

{
  "forPublishedDate": "Last30Days",
  "sortType": "DatePublished",
  "sortDirection": "Descending"
}

Groups with specific tag

{
  "forTags": [42],
  "includeArchived": false
}

Groups owned by specific user

{
  "forOwnedBy": [12345]
}

Groups starting with specific letter

{
  "forFirstLetterOfTitle": "E",
  "sortType": "Title",
  "sortDirection": "Ascending"
}

Complex query: Groups of specific type with tag, sorted by title

{
  "forGroupTypes": [1],
  "forTags": [42],
  "sortType": "Title",
  "sortDirection": "Ascending",
  "pageSize": 50
}

Related Documentation for Groups

• Group Types API - Use /api/grouptypes to retrieve available group type IDs
• Tag Bundles API - Available in Swagger documentation at /swagger (use to find tag IDs)