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).
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". A filter naming no strength builds at every strength. |
fit_scoreandfit_confidencecannot be used as filters. The field catalog returns them as active fields because they are computed for each record of a built audience, so a builder that renders whatever the catalog returns will offer them. Creating or updating an audience with a rule on either returns400.fit_bandfilters only with an inclusion operator such asin, and only when your organization has fit scoring enabled (Settings > Data & monitoring > ICP fit). Any otherfit_bandrule also returns400, with a message naming the reason.
{
"fieldName": "INTENT",
"conditionRules": {
"operator": "in",
"value": ["4eyes_119418", "4eyes_118710"]
}
}Combining topics. One
INTENTrule 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 ownINTENTrule and join the rules withand. The audience then holds people who researched at least one topic from every group, on any day within the intent window. Ascorerule in the sameandgroup as anINTENTrule sets that group's strength, so each group can have its own. Ascorerule 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
| 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, containsWord, notcontains, notContainsWord, startsWith, endsWith, notnull | Free text. Use containsWord for short words such as "cto" |
job_title_normalized | Normalized title (16,000+ values) | in, notin, contains, containsWord, notContainsWord, is, is not, startsWith, endsWith, notnull | Picklist values or free text with contains |
department | Primary department | in, notin | "administrative", "community and social services", "construction", "consulting", "customer service", "design & creative", "education", "engineering", "executive", "finance", "government & public safety", "health services", "human resources", "information technology", "legal", "manufacturing", "marketing", "media and communications", "military & protective services", "operations", "product management", "real estate", "research & science", "sales" |
department_2 | Secondary department, a separate classification (see below) | in, notin | "accounting", "administrative", "arts and design", "business development", "community and social services", "consulting", "education", "engineering", "entrepreneurship", "finance", "healthcare services", "human resources", "information technology", "legal", "marketing", "media and communication", "military and protective services", "operations", "product management", "program and project management", "purchasing", "quality assurance", "real estate", "research", "sales", "support" |
job_functions | Functional role | contains, notcontains | Free text |
Why are there two department fields, and can I use only
department_2? They are two separate classifications, not a field and a copy of it, anddepartment_2does not contain everydepartmentvalue. Tendepartmentvalues have nodepartment_2equivalent:construction,customer service,design & creative,executive,government & public safety,health services,manufacturing,media and communications,military & protective servicesandresearch & science. Somedepartment_2values are spelled differently from their closestdepartmentmatch (healthcare servicesagainsthealth services,media and communicationagainstmedia and communications), and twelve exist only indepartment_2:accounting,arts and design,business development,entrepreneurship,healthcare services,media and communication,military and protective services,program and project management,purchasing,quality assurance,researchandsupport. A filter ondepartment_2therefore selects different people than the same filter ondepartment. A person's value in one field does not tell you their value in the other. Usedepartmentfor the broadest picks such asexecutive, anddepartment_2for the finer ones such asaccountingorpurchasing. To cover either, put both in anorgroup. Pick values from the field's options in the Field Catalog API, which is the source of truth for each field's current values.
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 | is, is not, contains, containsWord, notcontains, notContainsWord, startsWith, endsWith, notnull | 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, is not, contains, notcontains, startsWith, endsWith, notnull | Number as text |
company_total_revenue | Exact revenue | >, >=, <, <=, between, is, is not, contains, notcontains, notnull | Number |
company_employee_countdoes not take>,<,>=or<=, andcompany_total_revenuedoes. 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". For that reason, 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 oncompany_employee_count_rangewithinornotininstead.
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" |
Email
| Field | Description | Operators | Values |
|---|---|---|---|
email_validation_status | Overall email validation result | in, notin | "valid", "invalid", "catchall", "unknown" |
Values are case-sensitive. Use the lowercase values exactly as listed. For example, "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 do not want.
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"]
}
}Referencing saved audiences 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.
PERSONAadds the referenced audience's entire filter to yours, including anyINTENTrule it carries. A topic saved in the persona is therefore applied on top of this audience's own topics. Create the persona withtypeset to"contact"and noINTENTrule, and keep the topics in the audience that references it. See Understanding Segmentation Types.
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). "cto" also matches "Director" |
containsWord | Text | Whole-word match (case-insensitive). "cto" matches "CTO, Acme", not "Director" |
notcontains | Text | Leaves out any value that holds the substring. "cto" also removes "Director" |
notContainsWord | Text | Leaves out any value that holds the word as a whole word. "cto" removes "CTO, Acme" and keeps "Director of Sales" |
startsWith | Text | Starts with value |
endsWith | Text | Ends with value |
notnull | Any | Field has a value (no value parameter needed) |
>, >=, <, <= | Number | Numeric comparison |
In the audience builder, the operator list shows these as "contains word" and "does not contain word", next to "contains" and "does not contain".
Choosing an Operator
Pick the operator that matches the least text you need. A narrower operator returns fewer wrong people.
| You want | Use | Why |
|---|---|---|
| The whole value, such as one exact title | is | Matches the full value only |
A word or acronym inside a value, such as "cto", "vp", "it" or "hr" | containsWord | Matches the word, not the same letters inside a longer word |
Part of a word, such as "engineer" for "engineering" | contains | Matches the text anywhere, even inside a word |
To leave out a word, such as "intern" | notContainsWord | Removes only whole-word matches |
| To leave out any value with this text | notcontains | Removes every value that holds the text, even inside a longer word |
For a word or acronym of 4 characters or fewer, use containsWord and notContainsWord. Short text hides inside longer words, so contains matches too many people.
How containsWord matches. The value must stand as a whole word, with no letter (a-z) or digit on either side. The match ignores case. Spaces, commas, hyphens, underscores and other symbols end a word. A value can hold more than one word, such as "vice president". A list matches a person who has any of its words. "cto" matches "CTO" and "CTO, Acme" and does not match "Director".
How exclusions work.
notContainsWordtakes a list. It removes a person whose field holds any word in the list as a whole word. It keeps a person whose field has no value."cto"removes "CTO, Acme" and keeps "Director of Sales".notcontainstakes one value per rule. If you send a list, the API reads only the first value. In the audience builder, several values save as one rule per value. The rules join withand, so each value removes people.notinremoves people whose value is in the list. It works on picklist fields.
Where the word operators work. Word operators work on text fields only. The audience builder offers them on job_title, job_title_normalized, job_title_history, headline, department_raw, company_name and company_name_history. The API rejects a word operator on a field that is not text. For job_title_history and company_name_history, the builder offers contains, notcontains, containsWord, notContainsWord, notnull and null.
{
"fieldName": "job_title",
"conditionRules": { "operator": "containsWord", "value": ["cto", "cfo"] }
}{
"fieldName": "job_title",
"conditionRules": { "operator": "notContainsWord", "value": ["intern", "assistant"] }
}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_119418", "4eyes_118710"]
}
},
{
"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 who meet both of these conditions. The job title contains "founder" (so "Founder", "Co-Founder" and "Founder & CEO" alike). The person is also researching at least one of the three topics.
- One
INTENTrule withinmeans 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. A topic named after a kind of person is therefore a different condition from the person being one.
- More than one kind of title goes in a nested
orgroup ofjob_titlerules, as in Nesting Rules above. - To reuse the person criteria across audiences, save them as a persona and reference it with
PERSONAin place of thejob_titlerule (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.
inwithin a rule means any of its topics.andbetweenINTENTrules means every group. Use both to say "one of these, and one of those".- Keep a group's
scorerule with it in a nestedandgroup, 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_titlerule) 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_counttakes no size comparison (see the note under Company above), so "more than 500 employees" is the brackets above 500 within:501 to 1000,1001 to 5000,5001 to 10000and10000+. - String matching is case-insensitive. You do not 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 withunload: "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. - Use
containsWordfor short acronyms onjob_title.containsmatches substrings."CTO"matches any title with those letters (e.g., "Art Director", "Factory Manager").containsWordwith"cto"matches only the word. Or spell the title out, because"chief technology officer"cannot occur inside an unrelated word. Or useseniority_levelwithinandcxofor C-level people as a group.job_title_normalizedis no way around this. Its values are full titles rather than acronyms. There is no plainchief technology officer,chief executive officerorchief financial officeramong them. Only compound titles such aschief 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
- Partner Data: Filter on priced third-party fields (
<slug>__<column>) once a dataset is enabled - Create an Intent Audience: End-to-end walkthrough
- Reading Parquet Files: Open your downloaded audience files
Updated 5 days ago
