Advanced Search Overview

Advanced search powers the POST /search/{domain}/results endpoints. Every request has the same two-part body:

{
  "configuration": { },
  "filters": { }
}

• filters — what to match. A tree of constraints and groups.
• configuration — what to return, and which slice of the population to search.

Pagination is passed as query string parameters (?page=2&per_page=100), not inside the body.

Filters

A filter is a tree, where each node is either a constraint or a group.

Constraint node

A constraint applies one operator to one field.

{
  "type": "constraint",
  "id": "first_name",
  "operator": "equal",
  "value": "Tom",
  "invert": false
}

Group node

A group combines child nodes with a boolean operator. Groups nest to any depth.

{
  "type": "group",
  "operator": "and",
  "invert": false,
  "conditions": []
}

A bare constraint is valid at the root — you do not need to wrap a single condition in a group.

Configuration

configuration controls the result shape and the population searched. Every key is optional. Unrecognized keys are ignored.

Result shaping

order_by

Each entry is an object:

{
  "order_by": [
    { "column": "last_name", "direction": "asc" },
    { "column": "first_name", "direction": "asc" }
  ]
}

Population selection

These keys decide who is eligible to match, independently of your filters.

Two filters are applied automatically and cannot be turned off:

• Deceased-date constraints force deceased profiles in. If your filter tree contains a date_deceased_parts or date_deceased_month constraint, deceased profiles are included regardless of filter_profile_type.
• An is_inactive constraint forces inactive profiles in. Same behavior.

include_unlisted is permission-governed

You can always turn unlisted profiles off, but you cannot turn them on without permission:

• Omitted, or set to a truthy value → the API computes the value from the caller's permissions. You get unlisted individuals only in campuses where the caller may view them, and only listed individuals elsewhere.
• Set to false → respected. Unlisted individuals are excluded.

Server-controlled keys

These appear in the configuration object but are set by the API. Any value you send is overwritten or ignored — do not include them.

Other domains

Some keys apply only to non-individual search domains and are ignored by /search/individuals/results:

group_by and include_active (event attendance) · limit_campus_ids, limit_category_ids, limit_team_ids, limit_schedule_ids, non_archived_categories_only (scheduling) · include_campuses (scheduling categories) · location, public_only, restrictive_mode, context_individual_id.

Pagination

Pagination is passed on the query string, not in the body.

Response headers: X-Page, X-Per-Page, X-Offset, X-Total-Pages.

Data Types and Operators

Each searchable field has a data type. The valid operators — and the shape of value — depend on that type.

Shared value shapes

Range object — used by between and not_between:

{ "lbound": "2026-01-01", "ubound": "2026-03-31" }

lbound and ubound are both dates, both numbers, or both times, matching the field's type.

Relative range object — used by the in_the_* operator families:

{ "period": "month", "units": 3, "anniversary": false }

text

date

A date string is yyyy-mm-dd.

date_parts

Like date, but the exact-comparison operators can compare individual components of a date. Every date operator is accepted; only the six exact comparisons behave differently:

For everything except the six exact comparisons, the value shapes and behavior are identical to date above, including the rolling-vs-calendar distinction.

The parts object — each component is optional:

{ "year": 2026, "month": 8, "day": 14 }

How the exact comparisons read it:

• All three parts — a true date comparison. equal matches the whole day.
• year + month only, with greater_than[_or_equal] / less_than[_or_equal] — a true date comparison anchored to the month's last day (greater_*) or first day (less_*), so "after July 2026" and "before July 2026" mean what they say.
• Any other partial combination — each supplied part is compared independently: { "month": 8, "day": 14 } with equal matches an August 14 in any year (an anniversary match). With inequality operators this compares each component separately — month > 8 AND day > 14 — which is rarely what a date question means.

number

currency

Identical to number, except values are in cents — the value you send is multiplied by 100 before comparison.

time

Identical to number, except it compares the time portion of a timestamp rather than a number.

boolean

boolean_strict

Like boolean, but distinguishes explicit false from unset: '1' is true, '0' is false, anything else is unknown.

Examples

A simple comparison

All individuals with the first name "Tom":

{
  "configuration": { "return_search_results": true },
  "filters": {
    "type": "constraint",
    "id": "first_name",
    "operator": "equal",
    "value": "Tom",
    "invert": false
  }
}

A grouped comparison

All individuals who are male and over 20:

{
  "configuration": { "return_search_results": true },
  "filters": {
    "type": "group",
    "operator": "and",
    "invert": false,
    "conditions": [
      {
        "type": "constraint",
        "id": "gender",
        "operator": "equal",
        "value": "m",
        "invert": false
      },
      {
        "type": "constraint",
        "id": "age",
        "operator": "greater_than",
        "value": 20,
        "invert": false
      }
    ]
  }
}

A nested comparison

All individuals who are male and over 20, or who are named Tom:

All individuals who are male and over 20, or who are named Tom:

{
  "configuration": { "return_search_results": true },
  "filters": {
    "type": "group",
    "operator": "or",
    "invert": false,
    "conditions": [
      {
        "type": "constraint",
        "id": "first_name",
        "operator": "equal",
        "value": "Tom",
        "invert": false
      },
      {
        "type": "group",
        "operator": "and",
        "invert": false,
        "conditions": [
          {
            "type": "constraint",
            "id": "gender",
            "operator": "equal",
            "value": "m",
            "invert": false
          },
          {
            "type": "constraint",
            "id": "age",
            "operator": "greater_than",
            "value": 20,
            "invert": false
          }
        ]
      }
    ]
  }
}

Reporting over a full population, sorted and paged

Everyone created in the last quarter, including inactive and deceased profiles, oldest first:

{
  "configuration": {
    "return_search_results": true,
    "filter_profile_type": ["active", "inactive", "deceased"],
    "order_by": [{ "column": "date_created", "direction": "asc" }]
  },
  "filters": {
    "type": "constraint",
    "id": "date_created",
    "operator": "in_the_previous",
    "value": { "period": "quarter", "units": 1 },
    "invert": false
  }
}

Request this as POST /search/individuals/results?per_page=100&page=1 and page until you get a short page.