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"]
        }
      }
    ]
  }
}

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.

fit_band, fit_score and fit_confidence are returned by the field catalog but do not filter. They appear as active fields, so a builder that renders whatever the catalog returns will offer them. A rule on fit_score or fit_confidence has no effect on which rows come back, and a rule on fit_band has no effect unless fit scoring is configured for the audience. Neither returns an error, so an audience filtered on one of these is wider than it looks. Use the firmographic fields directly instead.

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

Combining topics. One INTENT rule listing several topic IDs matches a person researching any of them. To require the same person to research topics from different groups, put each group in its own INTENT rule and join the rules with and: the audience holds people who researched at least one topic from every group, on any day within the intent window. A score rule in the same and group as an INTENT rule sets that group's strength, so each group can have its own; a score rule outside the groups applies to all of them, and a group with neither counts every strength. In the dashboard's audience builder this is a topic group set to AND in Advanced Mode (Simple mode always combines topics with OR). See Example 6.

Job and Seniority

Company

company_employee_count does not take >, <, >= or <=, and company_total_revenue does. The two rows above look alike and are not. Employee count is stored as text, where a size comparison would order values as strings and rank "2000000" above "10000000", so those operators are withheld and a filter using one is rejected: the save fails rather than returning wrong rows. To select companies by size, filter on company_employee_count_range with in or notin instead.

Personal and Demographic

Email

Values are case-sensitive. Use the lowercase values exactly as listed;
"Valid" does not match "valid".

Use in with "valid" to keep only contacts whose email was confirmed
deliverable:

{
  "fieldName": "email_validation_status",
  "conditionRules": {
    "operator": "in",
    "value": ["valid"]
  }
}

"catchall" means the receiving domain accepts mail for any address, so
delivery is possible but the individual mailbox was never confirmed.
"unknown" means validation did not complete.

Note that notin excludes contacts by status but keeps nothing whose status is
missing: a contact with no validation result is not returned by either in or
notin. Filter on the statuses you want rather than on the ones you don't.

Composition (Personas and Accounts)

You can reference other saved audiences to build layered targeting:

{
  "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.

A persona you reference should hold person fields only. PERSONA adds the referenced audience's entire filter to yours, including any INTENT rule it carries, so a topic saved in the persona is applied on top of this audience's own topics. Create the persona with type set to "contact" and no INTENT rule, and keep the topics in the audience that references it. See Understanding Segmentation Types.

Operators Reference

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.

Example 5: A Kind of Person Researching Any of Several Topics

Target founders who are researching any of growing a business, productivity, or coworking. Describe who the person is with person fields, and list every topic in one INTENT rule.

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["business_growth_topic_id", "productivity_topic_id", "coworking_topic_id"]
        }
      },
      {
        "fieldName": "job_title",
        "conditionRules": {
          "operator": "contains",
          "value": "founder"
        }
      }
    ]
  }
}

This returns people whose job title contains "founder" (so "Founder", "Co-Founder" and "Founder & CEO" alike) AND who are researching at least one of the three topics.

• One INTENT rule with in means any of the listed topics. Put every topic you would accept in that one list.
• Describe the person with person fields, not with a topic. A topic records what someone is researching, not who they are, so a topic named after a kind of person is a different condition from the person being one.
• More than one kind of title goes in a nested or group of job_title rules, as in Nesting Rules above.
• To reuse the person criteria across audiences, save them as a persona and reference it with PERSONA in place of the job_title rule (see Composition above).
• Find the topic IDs with the Taxonomy API.

Example 6: The Same Person Researching Two Groups of Topics

Target people researching endpoint security or zero trust at high or medium strength who are also researching cloud migration or Kubernetes at any strength. Give each group its own INTENT rule and join them with and.

{
  "filter": {
    "condition": "and",
    "rules": [
      {
        "condition": "and",
        "rules": [
          {
            "fieldName": "INTENT",
            "conditionRules": {
              "operator": "in",
              "value": ["endpoint_security_topic_id", "zero_trust_topic_id"]
            }
          },
          {
            "fieldName": "score",
            "conditionRules": {
              "operator": "in",
              "value": ["high", "medium"]
            }
          }
        ]
      },
      {
        "fieldName": "INTENT",
        "conditionRules": {
          "operator": "in",
          "value": ["cloud_migration_topic_id", "kubernetes_topic_id"]
        }
      }
    ]
  }
}

This returns people who researched endpoint security or zero trust at high or medium strength AND researched cloud migration or Kubernetes. Both must be the same person; the two can happen on different days within the intent window.

• in within a rule means any of its topics; and between INTENT rules means every group. Use both to say "one of these, and one of those".
• Keep a group's score rule with it in a nested and group, as above. A group without one counts every strength.
• Reference personas and accounts that hold person fields only. A topic inside a referenced persona or account is not combined this way: joined with different topics in the audience, it returns no one.
• Add person fields beside the groups (for example a job_title rule) to narrow who the person is, as in Example 5.

Tips

• Always include an INTENT rule. The API requires at least one topic filter.
• Filter company size on company_employee_count_range. company_employee_count takes no size comparison (see the note under Company above), so "more than 500 employees" is the brackets above 500 with in: 501 to 1000, 1001 to 5000, 5001 to 10000 and 10000+.
• 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".
• Get valid filter values from the API. Instead of hardcoding picklist values, fetch them from the Field Catalog API with include_options=true. This returns the exact values the backend accepts for each multiselect field.
• Avoid short acronyms with contains on job_title. The contains operator does substring matching, so "CTO" matches any title containing those letters (e.g., "Art Director", "Factory Manager"). Spell the title out instead ("chief technology officer" cannot occur inside an unrelated word), or use seniority_level with in and cxo for C-level people as a group. job_title_normalized is no way around this: its values are full titles rather than acronyms, and there is no plain chief technology officer, chief executive officer or chief financial officer among them, only compound titles such as chief financial officer and vice president.

Next Steps

• Understanding Segmentation Types: When to use Persona vs Account vs Audience
• 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