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: a filter has a condition, and or or, over its rules: Rule 1 intent topics, Rule 2 seniority level, Rule 3 company size, and a nested group with condition or that holds Rule 4a industry SaaS and Rule 4b industry Cloud.

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"]
        }
      }
    ]
  }
}
FieldTypeDescription
conditionstring"and" (all rules must match) or "or" (any rule can match)
rulesarrayList of rules or nested groups
rules[].fieldNamestringThe field to filter on (see tables below)
rules[].conditionRules.operatorstringHow to compare (see Operators section)
rules[].conditionRules.valuestring or arrayThe 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.

FieldDescriptionOperatorsValues
INTENTIntent topicsin, notinArray of topic IDs from the Taxonomy API
scoreIntent signal strengthin, notin"low", "medium", "high". A filter naming no strength builds at every strength.

fit_score and fit_confidence cannot 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 returns 400. fit_band filters only with an inclusion operator such as in, and only when your organization has fit scoring enabled (Settings > Data & monitoring > ICP fit). Any other fit_band rule also returns 400, with a message naming the reason.

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

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 then 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

FieldDescriptionOperatorsValues
seniority_levelPrimary seniorityin, notin"staff", "manager", "director", "vp", "cxo"
seniority_level_2Extended seniorityin, notin"cxo", "director", "entry", "manager", "owner", "partner", "senior individual contributor", "training", "unpaid", "vice president"
job_titleExact or partial titleis, is not, contains, containsWord, notcontains, notContainsWord, startsWith, endsWith, notnullFree text. Use containsWord for short words such as "cto"
job_title_normalizedNormalized title (16,000+ values)in, notin, contains, containsWord, notContainsWord, is, is not, startsWith, endsWith, notnullPicklist values or free text with contains
departmentPrimary departmentin, 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_2Secondary 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_functionsFunctional rolecontains, notcontainsFree 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, and department_2 does not contain every department value. Ten department values have no department_2 equivalent: construction, customer service, design & creative, executive, government & public safety, health services, manufacturing, media and communications, military & protective services and research & science. Some department_2 values are spelled differently from their closest department match (healthcare services against health services, media and communication against media and communications), and twelve exist only in department_2: accounting, arts and design, business development, entrepreneurship, healthcare services, media and communication, military and protective services, program and project management, purchasing, quality assurance, research and support. A filter on department_2 therefore selects different people than the same filter on department. A person's value in one field does not tell you their value in the other. Use department for the broadest picks such as executive, and department_2 for the finer ones such as accounting or purchasing. To cover either, put both in an or group. 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

FieldDescriptionOperatorsValues
company_employee_count_rangeEmployee count bracketin, 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_rangeRevenue bracketin, 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_industryIndustry nameis, is not, contains, notcontains, startsWith, endsWith, notnullFree text (e.g. "banking", "software", "healthcare")
company_nameCompany nameis, is not, contains, containsWord, notcontains, notContainsWord, startsWith, endsWith, notnullFree text
company_domainWebsite domainSame as industryFree text (e.g. "salesforce.com")
company_sicSIC industry codein, notin4-digit SIC codes
company_naicsNAICS industry codeis, is not, contains, startsWithNAICS codes
company_stateCompany HQ stateis, is not, containsState name (e.g. "california")
company_cityCompany HQ cityis, is not, containsCity name
company_employee_countExact employee countis, is not, contains, notcontains, startsWith, endsWith, notnullNumber as text
company_total_revenueExact revenue>, >=, <, <=, between, is, is not, contains, notcontains, notnullNumber

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". 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 on company_employee_count_range with in or notin instead.

Personal and Demographic

FieldDescriptionOperatorsValues
personal_state_codeContact's statein, notinTwo-letter code, lowercase (e.g. "ca", "ny", "tx")
personal_cityContact's cityis, is not, containsFree text
personal_zipContact's ZIP codeis, is not, startsWithZIP code
age_rangeAge bracketis, is not"18-24", "25-34", "35-44", "45-54", "55-64", "65 and older"
genderGenderis, is not"f", "m", "u"
income_range_lcHousehold incomein, 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_homeownerHomeowner statusis, is not"y", "n"
has_childrenHas childrenis, is not"y", "n"
is_marriedMarital statusis, is not"y", "n"

Email

FieldDescriptionOperatorsValues
email_validation_statusOverall email validation resultin, 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:

FieldDescriptionOperatorsValues
PERSONAInclude/exclude people from another persona audiencein, notinArray of audience IDs
ACCOUNTInclude/exclude people from companies in another account audiencein, notinArray 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. PERSONA adds the referenced audience's entire filter to yours, including any INTENT rule it carries. A topic saved in the persona is therefore 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

OperatorWorks WithDescription
isText, selectExact match (case-insensitive)
is notText, selectNot equal (case-insensitive)
inMultiselect, picklistMatches any of the provided values
notinMultiselect, picklistMatches none of the provided values
containsTextSubstring match (case-insensitive). "cto" also matches "Director"
containsWordTextWhole-word match (case-insensitive). "cto" matches "CTO, Acme", not "Director"
notcontainsTextLeaves out any value that holds the substring. "cto" also removes "Director"
notContainsWordTextLeaves out any value that holds the word as a whole word. "cto" removes "CTO, Acme" and keeps "Director of Sales"
startsWithTextStarts with value
endsWithTextEnds with value
notnullAnyField has a value (no value parameter needed)
>, >=, <, <=NumberNumeric 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 wantUseWhy
The whole value, such as one exact titleisMatches the full value only
A word or acronym inside a value, such as "cto", "vp", "it" or "hr"containsWordMatches the word, not the same letters inside a longer word
Part of a word, such as "engineer" for "engineering"containsMatches the text anywhere, even inside a word
To leave out a word, such as "intern"notContainsWordRemoves only whole-word matches
To leave out any value with this textnotcontainsRemoves 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.

  • notContainsWord takes 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".
  • notcontains takes 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 with and, so each value removes people.
  • notin removes 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 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. 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 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 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 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.
  • Use containsWord for short acronyms on job_title. contains matches substrings. "CTO" matches any title with those letters (e.g., "Art Director", "Factory Manager"). containsWord with "cto" matches only the word. Or spell the title out, because "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. 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


Did this page help you?