> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ICP filters

> Get available filter definitions and build audience rules

## Get the filter catalog

```bash theme={null}
GET /v1/intent/audiences/filters
x-api-key: YOUR_API_KEY
```

The response is a catalog, not a flat list of values. Render filters from `data.groups[].filters[]` and submit each filter by its `key`.

```ts theme={null}
type IntentFilterCatalog = {
  version: {
    status: "catalog" | "static_fallback";
    sourceTable: string;
    catalogTable: string;
    catalogVersion: string | null;
    buildId: string | null;
    buildDate: string | null;
    generatedAt: string | null;
  };
  summary: {
    groupCount: number;
    filterCount: number;
    valueCount: number;
    recommendedFilterCount: number;
    standardFilterCount: number;
    advancedFilterCount: number;
    supportsAdvancedLogic: boolean;
    defaultFieldLogic: "and";
  };
  groups: Array<{
    key: string;
    label: string;
    description: string;
    filters: FilterDefinition[];
  }>;
};
```

```ts theme={null}
type FilterDefinition = {
  key: string;
  label: string;
  type: "multi_select" | "boolean" | "text_terms" | "number_range";
  valueType: "enum" | "boolean" | "string" | "number";
  operators: string[];
  values?: Array<{ value: string; label: string; count: number }>;
  ui: {
    label: string;
    description: string;
    control: "multi_select" | "toggle" | "text_chips" | "number_range";
    section: "recommended" | "standard" | "advanced";
    recommended: boolean;
    advanced: boolean;
    placeholder?: string;
    helperText?: string;
  };
};
```

Hide backend diagnostic fields such as `sourceColumn`, `source`, `requiresSidecar`, and `isSearchOnly` in normal product UI.

## Common filter keys

Use the live catalog as the source of truth. Common current groups include:

| Area           | Example keys                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| Company        | `company.industries`, `company.industryGroups`, `company.revenueRanges`, `company.names`, `company.domains` |
| Role           | `role.seniority`, `role.departments`, `role.isDecisionMaker`, `role.isCeo`, `role.isVp`, `role.isFinance`   |
| Job titles     | `jobTitle.include`, `jobTitle.exclude`, `jobTitle.exact`                                                    |
| Contactability | `contact.hasBusinessEmail`, `contact.hasPersonalEmail`, `contact.hasLinkedin`, `contact.hasAnyPhone`        |
| Geography      | `geo.personalStates`, `geo.companyStates`, `geo.personalCities`, `geo.companyCities`                        |
| Demographics   | `demographics.gender`, `demographics.ageRanges`, `demographics.incomeRanges`, `demographics.netWorth`       |

Do not submit old flat filter keys such as `companyIndustry`, `companySize`, `seniority`, or `hasBusinessEmail`.

## Multi-select filters

Submit raw `values[].value`, not the display labels.

```json theme={null}
{
  "filters": {
    "company.industries": {
      "values": ["software development", "financial services"]
    },
    "role.seniority": {
      "values": ["director", "vp", "c_suite"]
    }
  }
}
```

Values inside one multi-select are ORed together. Different top-level filters are ANDed together.

## Boolean filters

```json theme={null}
{
  "filters": {
    "contact.hasBusinessEmail": true,
    "role.isDecisionMaker": true
  }
}
```

Object form is also supported:

```json theme={null}
{
  "filters": {
    "contact.hasBusinessEmail": {
      "operator": "is_true"
    }
  }
}
```

## Text chip filters

Use text chip filters for free-text job title, company name, domain, NAICS, SIC, city, or ZIP inputs when those keys are present in the catalog.

```json theme={null}
{
  "filters": {
    "jobTitle.include": {
      "values": ["CFO", "VP Finance", "Head of Revenue"],
      "operator": "contains",
      "mode": "any"
    },
    "jobTitle.exclude": {
      "values": ["assistant", "intern", "student"],
      "operator": "contains",
      "mode": "any"
    }
  }
}
```

Supported text operators are `contains`, `exact`, and `starts_with`. `mode: "any"` ORs terms together, and `mode: "all"` ANDs terms together.

## Number range filters

```json theme={null}
{
  "filters": {
    "company.revenueMin": {
      "min": 1000000,
      "max": 10000000
    }
  }
}
```

Single-sided range form:

```json theme={null}
{
  "filters": {
    "company.revenueMin": {
      "operator": "gte",
      "value": 1000000
    }
  }
}
```

## Advanced logic

Prefer simple top-level filters for normal builders. Advanced `and` and `or` groups are supported when the user explicitly builds nested logic.

```json theme={null}
{
  "filters": {
    "and": [
      { "field": "contact.hasBusinessEmail", "value": true },
      {
        "or": [
          { "field": "role.isCfo", "value": true },
          { "field": "role.isVp", "value": true },
          {
            "field": "jobTitle.include",
            "values": ["head of finance"],
            "mode": "any"
          }
        ]
      }
    ]
  }
}
```

Rules:

* A group can contain either `and` or `or` at the same level, not both.
* Top-level simple filters and top-level groups are combined with AND.
* Nested OR groups cannot mix serving-only fields and filter-surface-only fields.