Building Audience Filters

Summary: Audience filters let you target specific people by combining intent topics, job seniority, company size, industry, location, and 60+ other fields. This page shows the filter structure, available fields, operators, and practical examples.

How Filters Work

When you create an audience, the filter object defines who to include. Filters combine rules (individual conditions) with conditions (AND/OR logic).

flowchart TD
    A[Filter] --> B["condition: and / or"]
    B --> C[Rule 1: Intent topics]
    B --> D[Rule 2: Seniority level]
    B --> E[Rule 3: Company size]
    B --> F["Nested group (condition: or)"]
    F --> G[Rule 4a: Industry = SaaS]
    F --> H[Rule 4b: Industry = Cloud]

    style A fill:#3b82f6,color:#fff
    style F fill:#6366f1,color:#fff

Filter Structure

Every filter has a condition (how rules combine) and an array of rules:

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["topic_id_1", "topic_id_2"]
        }
      },
      {
        "fieldName": "seniority_level",
        "conditionRules": {
          "operator": "in",
          "value": ["cxo", "vp", "director"]
        }
      }
    ]
  }
}

Field	Type	Description
`condition`	string	`"and"` (all rules must match) or `"or"` (any rule can match)
`rules`	array	List of rules or nested groups
`rules[].fieldName`	string	The field to filter on (see tables below)
`rules[].conditionRules.operator`	string	How to compare (see Operators section)
`rules[].conditionRules.value`	string or array	The value(s) to match against

Nesting Rules

You can nest groups inside rules to create complex logic. For example, "VP+ AND (SaaS OR Cloud industry)":

{
  "condition": "and",
  "rules": [
    {
      "fieldName": "seniority_level",
      "conditionRules": { "operator": "in", "value": ["cxo", "vp", "director"] }
    },
    {
      "condition": "or",
      "rules": [
        {
          "fieldName": "company_industry",
          "conditionRules": { "operator": "contains", "value": "saas" }
        },
        {
          "fieldName": "company_industry",
          "conditionRules": { "operator": "contains", "value": "cloud" }
        }
      ]
    }
  ]
}

Filter Categories

Intent

Every audience must include at least one INTENT rule.

Field	Description	Operators	Values
`INTENT`	Intent topics	`in`, `notin`	Array of topic IDs from the Taxonomy API
`score`	Intent signal strength	`in`, `notin`	`"low"`, `"medium"`, `"high"`

{
  "fieldName": "INTENT",
  "conditionRules": {
    "operator": "in",
    "value": ["4eyes_115481", "4eyes_119418"]
  }
}

Job and Seniority

Field	Description	Operators	Values
`seniority_level`	Primary seniority	`in`, `notin`	`"staff"`, `"manager"`, `"director"`, `"vp"`, `"cxo"`
`seniority_level_2`	Extended seniority	`in`, `notin`	`"cxo"`, `"director"`, `"entry"`, `"manager"`, `"owner"`, `"partner"`, `"senior individual contributor"`, `"training"`, `"unpaid"`, `"vice president"`
`job_title`	Exact or partial title	`is`, `is not`, `contains`, `startsWith`, `endsWith`, `notnull`	Free text
`job_title_normalized`	Normalized title	Same as job_title	Free text
`department`	Primary department	`in`, `notin`	`"engineering"`, `"sales"`, `"marketing"`, `"finance"`, `"executive"`, `"information technology"`, `"operations"`, `"human resources"`, `"legal"`, `"product management"`, `"customer service"`, `"education"`, `"health services"`, `"administrative"`, `"media and communications"`, `"community and social services"`
`job_functions`	Functional role	`contains`, `notcontains`	Free text

Company

Field	Description	Operators	Values
`company_employee_count_range`	Employee count bracket	`in`, `notin`	`"zero"`, `"1 to 10"`, `"11 to 25"`, `"26 to 50"`, `"51 to 100"`, `"101 to 250"`, `"251 to 500"`, `"501 to 1000"`, `"1001 to 5000"`, `"5001 to 10000"`, `"10000+"`
`company_revenue_range`	Revenue bracket	`in`, `notin`	`"under 1 million"`, `"1 million to 5 million"`, `"5 million to 10 million"`, `"10 million to 25 million"`, `"25 million to 50 million"`, `"50 million to 100 million"`, `"100 million to 250 million"`, `"250 million to 500 million"`, `"500 million to 1 billion"`, `"1 billion and over"`
`company_industry`	Industry name	`is`, `is not`, `contains`, `notcontains`, `startsWith`, `endsWith`, `notnull`	Free text (e.g. `"banking"`, `"software"`, `"healthcare"`)
`company_name`	Company name	Same as industry	Free text
`company_domain`	Website domain	Same as industry	Free text (e.g. `"salesforce.com"`)
`company_sic`	SIC industry code	`in`, `notin`	4-digit SIC codes
`company_naics`	NAICS industry code	`is`, `is not`, `contains`, `startsWith`	NAICS codes
`company_state`	Company HQ state	`is`, `is not`, `contains`	State name (e.g. `"california"`)
`company_city`	Company HQ city	`is`, `is not`, `contains`	City name
`company_employee_count`	Exact employee count	`>`, `>=`, `<`, `<=`, `is`, `notnull`	Number
`company_total_revenue`	Exact revenue	`>`, `>=`, `<`, `<=`, `is`, `notnull`	Number

Personal and Demographic

Field	Description	Operators	Values
`personal_state_code`	Contact's state	`in`, `notin`	Two-letter code, lowercase (e.g. `"ca"`, `"ny"`, `"tx"`)
`personal_city`	Contact's city	`is`, `is not`, `contains`	Free text
`personal_zip`	Contact's ZIP code	`is`, `is not`, `startsWith`	ZIP code
`age_range`	Age bracket	`is`, `is not`	`"18-24"`, `"25-34"`, `"35-44"`, `"45-54"`, `"55-64"`, `"65 and older"`
`gender`	Gender	`is`, `is not`	`"f"`, `"m"`, `"u"`
`income_range_lc`	Household income	`in`, `notin`	`"less than $20,000"`, `"$20,000 to $44,999"`, `"$45,000 to $59,999"`, `"$60,000 to $74,999"`, `"$75,000 to $99,999"`, `"$100,000 to $149,999"`, `"$150,000 to $199,999"`, `"$200,000 to $249,000"`, `"$250,000+"`
`is_homeowner`	Homeowner status	`is`, `is not`	`"y"`, `"n"`
`has_children`	Has children	`is`, `is not`	`"y"`, `"n"`
`is_married`	Marital status	`is`, `is not`	`"y"`, `"n"`

Composition (Personas and Accounts)

You can reference other saved audiences to build layered targeting:

Field	Description	Operators	Values
`PERSONA`	Include/exclude people from another persona audience	`in`, `notin`	Array of audience IDs
`ACCOUNT`	Include/exclude people from companies in another account audience	`in`, `notin`	Array of audience IDs

{
  "fieldName": "PERSONA",
  "conditionRules": {
    "operator": "in",
    "value": ["4738", "4739"]
  }
}

This lets you build a base persona (e.g. "IT Decision Makers") and reuse it across multiple intent audiences without redefining the filters.

Operators Reference

Operator	Works With	Description
`is`	Text, select	Exact match (case-insensitive)
`is not`	Text, select	Not equal (case-insensitive)
`in`	Multiselect, picklist	Matches any of the provided values
`notin`	Multiselect, picklist	Matches none of the provided values
`contains`	Text	Substring match (case-insensitive)
`notcontains`	Text	Does not contain substring
`startsWith`	Text	Starts with value
`endsWith`	Text	Ends with value
`notnull`	Any	Field has a value (no value parameter needed)
`>`, `>=`, `<`, `<=`	Number	Numeric comparison

Practical Examples

Example 1: VP+ at Enterprise Companies Researching Cloud Computing

Target senior decision-makers at large companies showing intent for cloud topics.

{
  "organization_id": "YOUR_ORG_ID",
  "project_id": "YOUR_PROJECT_ID",
  "audience_name": "Cloud Computing - Enterprise VPs",
  "type": "intents",
  "segmentation_type": "Audience",
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["4eyes_115481", "4eyes_119418"]
        }
      },
      {
        "fieldName": "seniority_level",
        "conditionRules": {
          "operator": "in",
          "value": ["cxo", "vp", "director"]
        }
      },
      {
        "fieldName": "company_employee_count_range",
        "conditionRules": {
          "operator": "in",
          "value": ["1001 to 5000", "5001 to 10000", "10000+"]
        }
      }
    ]
  }
}

Example 2: Sales Teams at Mid-Market SaaS Companies

Target salespeople at companies in the software industry with 100-1000 employees.

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["your_topic_ids_here"]
        }
      },
      {
        "fieldName": "department",
        "conditionRules": {
          "operator": "in",
          "value": ["sales"]
        }
      },
      {
        "fieldName": "company_industry",
        "conditionRules": {
          "operator": "contains",
          "value": "software"
        }
      },
      {
        "fieldName": "company_employee_count_range",
        "conditionRules": {
          "operator": "in",
          "value": ["101 to 250", "251 to 500", "501 to 1000"]
        }
      }
    ]
  }
}

Example 3: High-Intent Contacts in Specific States

Target high-intent contacts in California, New York, or Texas.

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["your_topic_ids_here"]
        }
      },
      {
        "fieldName": "score",
        "conditionRules": {
          "operator": "in",
          "value": ["high"]
        }
      },
      {
        "fieldName": "personal_state_code",
        "conditionRules": {
          "operator": "in",
          "value": ["ca", "ny", "tx"]
        }
      }
    ]
  }
}

Example 4: Reuse a Persona Across Topics

First create a persona audience (e.g. "IT Decision Makers" with seniority and department filters, audience ID 4738). Then reference it:

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["cybersecurity_topic_id"]
        }
      },
      {
        "fieldName": "PERSONA",
        "conditionRules": {
          "operator": "in",
          "value": ["4738"]
        }
      }
    ]
  }
}

This returns contacts who match the "IT Decision Makers" persona AND show intent for cybersecurity topics.

Tips

Always include an INTENT rule. The API requires at least one topic filter.
Use company_employee_count_range instead of company_employee_count for bracket-based filtering. The exact count field is better for numeric comparisons (greater than 500, etc.).
String matching is case-insensitive. You don't need to worry about capitalization in filter values.
Start broad, then narrow. Create a basic audience first, check the size, then add filters to refine.
Use unload: "preview" first to see a sample before running the full export with unload: "unload".

Next Steps

Intent Audiences API -- Full API reference for creating and managing audiences
Taxonomy API -- Find topic IDs for your INTENT rules
Create an Intent Audience -- End-to-end walkthrough
Reading Parquet Files -- Open your downloaded audience files