audience-targeting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

请先阅读

bulk-operations/SKILL.md

——其中包含分页、JSONL管道传输、破坏性操作安全相关内容。可参考

bulk-operations/resources/json-patterns.md

中的重构示例。参考资源：

resources/contact-segmentation-filters.md

是筛选表达式指南，涵盖生命周期、线索状态、邮件互动、活动、交易、负责人等筛选维度。

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).
HAS_PROPERTY: bare
```
name
```
or
```
name?
```
. NOT_HAS_PROPERTY:
```
!name
```
. Dates:
```
YYYY-MM-DD
```
.

gotcha:

jobtitle~director

matches the token "director", not arbitrary substrings. No regex operator — search broadly, post-filter with

jq

权威来源：

hubspot objects search --help

。

一个

--filter

标志对应一组AND条件：

--filter "lifecyclestage=lead AND !hubspot_owner_id"

。

多个
```
--filter
```
标志为OR关系，适用于枚举值之间的或运算。
运算符：
```
=
```
、
```
!=
```
、
```
>
```
、
```
>=
```
、
```
<
```
、
```
<=
```
、
```
~
```
（CONTAINS_TOKEN——匹配完整单词，而非子字符串）。
HAS_PROPERTY：直接写
```
name
```
或
```
name?
```
；NOT_HAS_PROPERTY：
```
!name
```
；日期格式：
```
YYYY-MM-DD
```
。

的注意事项：

jobtitle~director

匹配的是“director”这个完整单词，而非任意子字符串。不支持正则运算符——可先进行宽泛搜索，再用

jq

进行后续筛选。

Properties this skill turns on

本技能启用的属性

Full live list:

hubspot properties list --type contacts

. Enum options aren't exposed by

properties get

; discover with

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

num_associated_deals

(0 net-new,

>=1

has-pipeline).

Firmographics (

industry

numberofemployees

annualrevenue

) live on companies — see cross-object section.

完整实时列表：

hubspot properties list --type contacts

。

properties get

不会展示枚举选项；可通过以下命令查看：

hubspot objects list --type contacts --properties <name> --limit 100 --format json | jq -r '.data[].properties.<name> // empty' | sort -u

。

此处使用的核心字段：

lifecyclestage

、

hubspot_owner_id

（直接写字段名/

表示已分配负责人/未分配负责人；可通过

hubspot owners list

获取ID）、

hs_email_optout

（

!=true

排除已退订用户）、

hs_email_last_open_date

notes_last_contacted

（互动时效性）、

jobtitle

country

city

（字符串匹配用

或

）、

num_associated_deals

（0表示新线索，

>=1

表示已进入销售管道）。

企业属性（

industry

、

numberofemployees

、

annualrevenue

）存储在企业对象中——请查看跨对象操作章节。

Common segments

常见细分群体示例

bash

undefined

bash

undefined

Recent leads (this quarter, not yet owned)

近期线索（本季度创建，尚未分配负责人）

hubspot objects search --type contacts
--filter "lifecyclestage=lead AND createdate>2026-01-01 AND !hubspot_owner_id"
--properties email,firstname,lastname,createdate

Decision-makers by jobtitle (OR across tokens)

按职位头衔筛选决策者（多关键词或运算）

hubspot objects search --type contacts
--filter "jobtitle~~director" --filter "jobtitle~~vp" --filter "jobtitle~chief"
--properties email,jobtitle,company

Engaged but not yet MQL (opened recently, still lead, opted in)

已互动但尚未成为MQL的用户（近期打开邮件，仍为线索状态，已订阅）

hubspot objects search --type contacts
--filter "lifecyclestage=lead AND hs_email_last_open_date>2026-04-01 AND hs_email_optout!=true"
--properties email,firstname,hs_email_last_open_date

Geographic — US contacts opted in

地理位置筛选——已订阅的美国联系人

hubspot objects search --type contacts
--filter "country=United States AND hs_email_optout!=true"
--properties email,state,city


More patterns (lead status, deals, owners, combined AND/OR) in `resources/contact-segmentation-filters.md`.

hubspot objects search --type contacts
--filter "country=United States AND hs_email_optout!=true"
--properties email,state,city


更多筛选模式（线索状态、交易、负责人、AND/OR组合）请查看`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":"...","type":"company_to_contact"}

, feeding directly into a single batched

objects get

bash

undefined

industry

numberofemployees

annualrevenue

存储在企业对象中。先构建目标企业集合，再关联到联系人——切勿针对每个企业执行

xargs -I{} hubspot objects get

。

associations list

会输出

{"id":"...","type":"company_to_contact"}

，可直接传入单次批量

objects get

命令。

bash

undefined

Step 1: target companies. Industry options are portal-specific — discover with:

步骤1：筛选目标企业。行业选项因门户而异——可通过以下命令查看：

hubspot objects list --type companies --properties industry --limit 100 --format json \

| jq -r '.data[].properties.industry // empty' | sort -u

hubspot objects search --type companies
--filter "industry=SOFTWARE AND numberofemployees>=100"
--properties name,industry,numberofemployees \

target_companies.jsonl

hubspot objects search --type companies
--filter "industry=SOFTWARE AND numberofemployees>=100"
--properties name,industry,numberofemployees \

target_companies.jsonl

Step 2: gather association IDs (associations list has no batch --from), then ONE batched

步骤2：收集关联ID（associations list不支持批量--from参数），然后执行一次批量

objects get for all contacts.

objects get获取所有联系人。

while read -r cid; do hubspot associations list --from "companies:$cid" --to contacts; done
< <(jq -r '.id' target_companies.jsonl)
| jq -c '{id}' | sort -u
| hubspot objects get --type contacts --properties email,firstname,jobtitle,hs_email_optout \

target_contacts.jsonl

Optional: drop opted-out

可选步骤：移除已退订用户

jq -c 'select(.properties.hs_email_optout != "true")' target_contacts.jsonl > campaign_audience.jsonl

undefined

jq -c 'select(.properties.hs_email_optout != "true")' target_contacts.jsonl > campaign_audience.jsonl

undefined

Saving and reusing a segment

保存与复用细分群体

A segment is a JSONL file. Re-use for updates, exports, or re-fetches:

bash

undefined

细分群体以JSONL文件形式保存，可用于更新、导出或重新获取数据：

bash

undefined

Save

保存细分群体

hubspot objects search --type contacts
--filter "lifecyclestage=lead AND hs_email_optout!=true"
--properties email,firstname,lastname,jobtitle \

segments/opted_in_leads.jsonl

hubspot objects search --type contacts
--filter "lifecyclestage=lead AND hs_email_optout!=true"
--properties email,firstname,lastname,jobtitle \

segments/opted_in_leads.jsonl

Assign owner (dry-run first per bulk-operations/SKILL.md)

分配负责人（请先按照bulk-operations/SKILL.md执行试运行）

jq -c '{id, properties:{hubspot_owner_id:"12345"}}' segments/opted_in_leads.jsonl
| hubspot objects update --type contacts --dry-run

Re-fetch with different properties later

后续重新获取不同属性的数据

jq -c '{id}' segments/opted_in_leads.jsonl
| hubspot objects get --type contacts --properties email,lifecyclestage,hs_lead_status


Destructive ops on a saved segment follow the dry-run → digest → confirm flow in `bulk-operations/SKILL.md`.

jq -c '{id}' segments/opted_in_leads.jsonl
| hubspot objects get --type contacts --properties email,lifecyclestage,hs_lead_status


针对已保存细分群体的破坏性操作，请遵循`bulk-operations/SKILL.md`中的试运行→验证→确认流程。

Known limits

已知限制

No Lists API surface. Can't save as a HubSpot list or filter by list membership.
```
~
```
is token-match, not substring. No regex operator.
```
properties get
```
does not return enum options — discover via
```
objects list
```
+
```
jq
```
.
```
associations list
```
has no batch
```
--from
```
. Loop to gather IDs, batch the downstream
```
objects get
```
.
For >100 results, use the pagination loop in
```
bulk-operations/SKILL.md
```
.

无Lists API接口，无法保存为HubSpot列表或按列表成员身份筛选。
```
~
```
为完整单词匹配，而非子字符串匹配，不支持正则运算符。
```
properties get
```
不会返回枚举选项——需通过
```
objects list
```
+
```
jq
```
查看。
```
associations list
```
不支持批量
```
--from
```
参数，需循环收集ID后执行批量
```
objects get
```
。
结果超过100条时，请使用
```
bulk-operations/SKILL.md
```
中的分页循环。