# Filter Catalog (https://terac.com/docs/developers/guides/filters/catalog)

Complete catalog of available filters and endpoints for browsing filter options.

## Geographic [#geographic]

| Slug                    | Type          | Description          |
| ----------------------- | ------------- | -------------------- |
| `multi_select--country` | multi\_select | Country of residence |
| `multi_select--state`   | multi\_select | State or province    |
| `multi_select--city`    | multi\_select | City                 |

## Demographic [#demographic]

| Slug                               | Type           | Description                        |
| ---------------------------------- | -------------- | ---------------------------------- |
| `integer--age`                     | integer        | Age range (`$gte` / `$lte`, 18-99) |
| `multi_select--gender`             | multi\_select  | Gender identity                    |
| `multi_select--ethnicity`          | multi\_select  | Race or ethnicity                  |
| `multi_select--language`           | multi\_select  | Primary language                   |
| `multi_select--household_income`   | multi\_select  | Household income bracket           |
| `multi_select--level_of_education` | multi\_select  | Highest education level            |
| `multi_select--marital_status`     | multi\_select  | Marital status                     |
| `multi_select--children`           | multi\_select  | Children by age group              |
| `single_select--home_owner`        | single\_select | Homeownership status               |

## Professional [#professional]

| Slug                              | Type           | Description                  |
| --------------------------------- | -------------- | ---------------------------- |
| `multi_select--job_function`      | multi\_select  | Job function / role          |
| `multi_select--industry`          | multi\_select  | Industry                     |
| `multi_select--seniority`         | multi\_select  | Seniority level              |
| `multi_select--company_size`      | multi\_select  | Company size by headcount    |
| `multi_select--work_setting`      | multi\_select  | Remote, hybrid, or in-office |
| `multi_select--employment_status` | multi\_select  | Employment status            |
| `single_select--collar_type`      | single\_select | Job collar type              |

## Participation History [#participation-history]

| Slug                             | Type      | Description                         |
| -------------------------------- | --------- | ----------------------------------- |
| `reference--has_taken_study`     | reference | Has completed specific study(s)     |
| `reference--has_not_taken_study` | reference | Has NOT completed specific study(s) |

## Endpoints [#endpoints]

### Get Filter Catalog [#get-filter-catalog]

Returns all available filters with their types, operators, and option metadata.

```
GET /filters
```

#### Response [#response]

```json
{
  "data": [
    {
      "slug": "integer--age",
      "name": "Age",
      "type": "integer",
      "category": "demographic",
      "operators": ["$gte", "$lte"],
      "min": 18,
      "max": 99
    },
    {
      "slug": "multi_select--country",
      "name": "Country of Residence",
      "type": "multi_select",
      "category": "geographic",
      "operators": ["$eq", "$in"],
      "options_url": "/api/external/v2/filters/multi_select--country/options"
    }
  ]
}
```

The full catalog is returned. The example above is truncated for brevity.

* `min` / `max` -- only present on `integer` type filters. Defines the valid range for `$gte` and `$lte` operators.
* `options_url` -- only present on `single_select` and `multi_select` filters. Fetch to get enumerable values.

### Get Filter Options [#get-filter-options]

Returns available values for a specific filter.

```
GET /filters/{filter_slug}/options
```

#### Query Parameters [#query-parameters]

| Param        | Type    | Default | Description                                                           |
| ------------ | ------- | ------- | --------------------------------------------------------------------- |
| `search`     | string  | --      | Search options by name                                                |
| `page`       | integer | 1       | Page number                                                           |
| `per_page`   | integer | 50      | Items per page (max 100)                                              |
| `country_id` | string  | --      | ISO 3166-1 alpha-2 country code. Required for state and city filters. |
| `state_id`   | string  | --      | State ISO code (e.g. `CA`). Narrows city results to a single state.   |

#### Cascading Geographic Filters [#cascading-geographic-filters]

State and city filters require parent context via query parameters:

* **State options** (`multi_select--state`): pass `country_id` to get states for that country. Returns empty without it.
* **City options** (`multi_select--city`): pass `country_id` (required) and optionally `state_id` to narrow results. Returns empty without `country_id`.

Geographic IDs encode their parent hierarchy so each value is unambiguous:

* **State IDs:** `{country}-{state}` (e.g. `US-CA` for California)
* **City IDs:** `{country}-{state}-{city}` (e.g. `US-CA-Los Angeles`)

The `state_id` parameter accepts both bare ISO codes (`CA`) and composite state IDs (`US-CA`), so you can feed a state option ID directly into the city endpoint.

```
GET /filters/multi_select--state/options?country_id=US
GET /filters/multi_select--city/options?country_id=US&state_id=US-CA
```

#### Example: State Options Response [#example-state-options-response]

```json
{
  "data": [
    { "id": "US-CA", "name": "California" },
    { "id": "US-TX", "name": "Texas" }
  ],
  "meta": { "total": 51, "page": 1, "per_page": 50 }
}
```

#### Example: City Options Response [#example-city-options-response]

```json
{
  "data": [
    { "id": "US-CA-Los Angeles", "name": "Los Angeles" },
    { "id": "US-CA-San Francisco", "name": "San Francisco" }
  ],
  "meta": { "total": 1200, "page": 1, "per_page": 50 }
}
```

#### Applying Hierarchical Filters [#applying-hierarchical-filters]

Use composite IDs when setting filters on an opportunity:

```json
{
  "filters": [
    { "multi_select--country": { "$in": ["US", "BR"] } },
    { "multi_select--state": { "$in": ["US-CA", "BR-SP"] } },
    {
      "multi_select--city": { "$in": ["US-CA-Los Angeles", "BR-SP-São Paulo"] }
    }
  ]
}
```