audience-targeting

基盤

まず bulk-operations/SKILL.md を読んでください — ページネーション、JSONL パイピング、破壊的操作の安全性について書かれています。レシピの再構成は bulk-operations/resources/json-patterns.md にあります。リソース: resources/contact-segmentation-filters.md はフィルター式のクックブックです（ライフサイクル、リードステータス、メールエンゲージメント、アクティビティ、ディール、オーナー）。

フィルター構文チートシート

信頼できる情報源: hubspot objects search --help。

• 1 つの --filter フラグ = 1 つの AND グループ: --filter "lifecyclestage=lead AND !hubspot_owner_id"。
• 複数の --filter フラグは OR で結合されます。enum の OR を取る場合に使用します。
• 演算子: =, !=, >, >=, <, <=, ~ (CONTAINS_TOKEN — 単語単位であり、部分文字列ではありません), @= (IN), @!= (NOT_IN)。
• HAS_PROPERTY: 裸の name または name?。NOT_HAS_PROPERTY: !name。日付: YYYY-MM-DD。
• 制限 (CRM 検索 API): --filter フラグは最大 5 個、フラグあたりの条件は最大 6 個、条件の合計は最大 18 個です。enum のリストには @= / @!= を優先してください — lifecyclestage@=lead,customer は 1 条件ですが、--filter "lifecyclestage=lead" --filter "lifecyclestage=customer" は 2 グループになります。
• 「これらのいずれでもない、または空」には 2 グループが必要です — @!= はプロパティが未設定のレコードをスキップするため、!name グループを OR で加え、共通の条件を両方で繰り返します: --filter "hubspot_owner_id=123 AND lifecyclestage@!=customer,evangelist" --filter "hubspot_owner_id=123 AND !lifecyclestage"

~ の注意点: jobtitle~director はトークン "director" にマッチし、任意の部分文字列にはマッチしません。正規表現演算子はありません — 広く検索し、jq で後からフィルタリングしてください。

このスキルが有効にするプロパティ

完全なライブリスト: hubspot properties list --type contacts。enum オプション: hubspot properties options-list --type contacts <name> | jq -r '.value'。フォールバックとして（たとえば、どの値が実際に使用されているかを確認するには）、ライブレコードを読み取ります: hubspot objects list --type contacts --properties <name> --limit 100 --format json | jq -r '.data[].properties.<name> // empty' | sort -u。

ここで使用する主要フィールド: lifecyclestage、hubspot_owner_id（所有/未所有には裸または ! を使用。ID は hubspot owners list）、hs_email_optout（!=true でオプトアウト済みを除外）、hs_email_last_open_date / notes_last_contacted（直近性）、jobtitle / country / city（文字列の = または ~）、num_associated_deals（0 は純新規、>=1 はパイプラインあり）。

企業属性（industry、numberofemployees、annualrevenue）は companies にあります — クロスオブジェクトのセクションを参照してください。

一般的なセグメント

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

その他のパターン（リードステータス、ディール、オーナー、AND/OR の組み合わせ）は resources/contact-segmentation-filters.md にあります。

クロスオブジェクト: 業界内の企業 → そのコンタクト

industry / numberofemployees / annualrevenue は企業にあります。企業のセットを構築してからトラバースします — 企業ごとに xargs -I{} hubspot objects get を決して実行しないでください。associations list は {"id":"...","labels":[...],"associationTypes":[...]} を出力します — {id} は単一のバッチ処理された objects get にそのまま渡せます。

# Step 1: target companies. Industry options are portal-specific — discover with:
#   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

# Step 2: gather association IDs (associations list has no batch --from), then ONE batched
# objects get for all contacts. Page each company with --limit/--after — a company with >100
# associated contacts truncates silently on a single call.
while read -r cid; do
  after=""
  while :; do
    page=$(hubspot associations list --from "companies:$cid" --to contacts --limit 100 ${after:+--after "$after"} --format json)
    echo "$page" | jq -c '.data[]?'
    after=$(echo "$page" | jq -r '.meta.next // empty')
    [ -z "$after" ] && break
  done
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

セグメントの保存と再利用

セグメントは JSONL ファイルです。更新、エクスポート、再取得のために再利用します:

# Save
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)
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

保存されたセグメントに対する破壊的操作は、bulk-operations/SKILL.md にあるドライラン → ダイジェスト → 確認のフローに従います。

HubSpot リストまたはビューとして保存

JSONL セグメントはポータブルですが、HubSpot にオーディエンスを永続化することもできます:

• リスト — hubspot segments create でリストを保存します。segments get / list で検査します。segments members-list でメンバーを読み取ります。segments members-add / members-remove でメンバーシップを管理します。動的リストのフィルター条件を設定するには segments update-filters を使用します。
• ビュー — hubspot views create --type <t> --name "..." --columns a,b [--filters-file filters.json] [--sort prop:asc] でフィルターセットを再利用可能なオブジェクトビューとして保存します。views list / get / update / replace-field / delete で管理します。
• まずサイズを確認 — hubspot objects count --type contacts --filter "..." はページングせずに {"object_type":"contacts","total":N} を返すので、保存またはエクスポートする前にオーディエンスのサイズを確認できます。

関連する読み取り専用シグナル (ターゲティングのためのコンテキスト)

• hubspot buyer-intent — 訪問企業のインテントシグナル (読み取り専用)。OAuth ログイン (hubspot auth login) が必要です。サービスキーはサポートされていません。
• hubspot analytics traffic sources — セッション/コンタクトの参照元。ソースベースのセグメンテーションに使用します。
• hubspot marketing forms list — フォーム定義。コンタクトがどのフォームでコンバージョンしたかによるセグメンテーションに使用します。

各コマンドの全機能については --help を実行してください。

既知の制限

• ~ はトークン一致であり、部分文字列一致ではありません。正規表現演算子はありません。
• 列挙型オプション: hubspot properties options-list --type contacts <name> (フォールバック: objects list + jq でライブレコードを読み取ります)。
• associations list にはバッチ --from がなく、1 回の呼び出しで 1 ページ (デフォルト 100) を返します。ID を収集するためにループし、各呼び出しを --limit/--after でページングして .meta.next が null になるまで続け、その後で下流の objects get をバッチ実行してください。そうしないと、関連コンタクトが 100 件を超える企業は黙って切り捨てられます。
• 100 件を超える結果については、bulk-operations/SKILL.md のページネーションループを使用してください。