Name: audience-targeting
Author: hubspot

Build a targeted contact segment by filtering on lifecycle, engagement, jobtitle, geography, or firmographics — then export it as JSONL for a campaign or downstream tool.

Foundation Read bulk operations/SKILL.md first — pagination, JSONL piping, destructive op safety. Reshape recipes in bulk operations/resources/json patterns.md . Resource: resources/contact segmentation filters.md is the filter expression cookbook (lifecycle, lead status, email engagement, activity, deals, owner). Filter syntax cheat sheet Source of truth: hubspot objects search help . One filter flag = one AND group: filter "lifecyclestage=lead AND !hubspot owner id" . Multiple filter flags are OR'd. Use for enum OR enum. Operators: = , != , , = , < , <= , ~ (CONTAINS TOKEN — whole word, NOT substring), @= (IN), @!= (NOT IN). HAS PROPERTY: bare name or name? . NOT HAS PROPERTY: !name . Dates: YYYY MM DD . Limits (CRM search API): max 5 filter flags, max 6 conditions per flag, max 18 conditions total. Prefer @= / @!= for enum lists — lifecyclestage@=lead,customer is one condition, filter "lifecyclestage=lead" filter "lifecyclestage=customer" is two groups. "None of these, or empty" needs two groups — @!= skips records where the property is unset, so OR in a !name group and repeat the shared conditions in both: filter "hubspot owner id=123 AND lifecyclestage@!=customer,evangelist" filter "hubspot owner id=123 AND !lifecyclestage" ~ gotcha: jobtitle~director matches the token "director", not arbitrary substrings. No regex operator — search broadly, post filter with jq . Properties this skill turns on Full live list: hubspot properties list type contacts . Enum options: hubspot properties options list type contacts <name jq r '.value' . As a fallback (e.g. to see which values are actually in use), read live records: hubspot objects list type contacts properties <name limit 100 format json jq r '.data[].properties.<name // empty' sort u . Core fields used here: lifecyclestage , hubspot owner id (bare/ ! for owned/unowned; hubspot owners list for IDs), hs email optout ( !=true excludes opted out), hs email last open date / notes last contacted (recency), jobtitle / country / city (string = or ~ ), num associated deals (0 net new, =1 has pipeline). Firmographics ( industry , numberofemployees , annualrevenue ) live on companies — see cross object section. Common segments More patterns (lead status, deals, owners, combined AND/OR) in resources/contact segmentation filters.md . Cross object: companies in industry → their contacts industry / numberofemployees / annualrevenue live on the company. Build the company set, then traverse — never xargs I{} hubspot objects get per company. associations list emits {"id":"...","labels":[...],"associationTypes":[...]} — {id} feeds directly into a single batched objects get . Saving and reusing a segment A segment is a JSONL file. Re use for updates, exports, or re fetches: Destructive ops on a saved segment follow the dry run → digest → confirm flow in bulk operations/SKILL.md . Save as a HubSpot list or view A JSONL segment is portable, but you can also persist an audience in HubSpot: List — hubspot segments create saves a list; segments get / list inspect it; segments members list reads members; segments members add / members remove manage membership. Use segments update filters to set a dynamic list's filter criteria. View — hubspot views create type <t name "..." columns a,b [ filters file filters.json] [ sort prop:asc] saves a filter set as a reusable object view; views list / get / update / replace field / delete manage it. Size it first — hubspot objects count type contacts filter "..." returns {"object type":"contacts","total":N} without paging, so you can size an audience before saving or exporting it. Related read only signals (context for targeting) hubspot buyer intent — visiting company intent signals (read only). Requires OAuth login ( hubspot auth login ); service keys are NOT supported. hubspot analytics traffic sources — where sessions/contacts came from, for source based segmentation. hubspot marketing forms list — form definitions, to segment by which form a contact converted on. Run each command's help for the full surface. Known limits ~ is token match, not substring. No regex operator. Enum options: hubspot properties options list type contacts <name (fallback: read live records via objects list + jq ). associations list has no batch from , and returns one page (default 100) per call. Loop to gather IDs and page each call with limit / after until .meta.next is null, then batch the downstream objects get — otherwise a company with 100 associated contacts truncates silently. For 100 results, use the pagination loop in bulk operations/SKILL.md .