crm-lookup

信頼できる情報源

hubspot <command> --help が正式な情報源です。まず bulk-operations/SKILL.md をお読みください。このドキュメントは JSONL のパイピング、ページネーション、stdin 経由のバッチ取得、および検索の後に行われるあらゆる書き込みの安全フローを担っています。このスキルは読み取り専用です。

ライブスキーマからプロパティを選択する

スキーマは変化します。ライブのセットを取得するには hubspot properties list --type <type> を実行してください。概要向けの初回パスの --properties は次のとおりです。

オブジェクト	--properties
contacts	email,firstname,lastname,company,phone,lifecyclestage,hubspot_owner_id
companies	name,domain,industry,annualrevenue,numberofemployees,hubspot_owner_id
deals	dealname,amount,dealstage,closedate,hubspot_owner_id,hs_is_closed_won
tickets	subject,hs_pipeline_stage,hs_ticket_priority,hubspot_owner_id

コンタクトの広告／キャンペーンのアトリビューションは hs_analytics_* にあります（例: hs_analytics_source、hs_analytics_source_data_1/_2、hs_analytics_first_touch_converting_campaign、hs_analytics_last_touch_converting_campaign）。完全なリスト: hubspot properties list --type contacts | grep hs_analytics_。

1. ID による検索

1 回のバッチ呼び出しで最大約 100 件の ID を指定できます:

hubspot objects get --type contacts 12345 67890 23456 --properties email,firstname,lastname,company,phone,lifecyclestage

2. メール／ドメインによる 1 件の検索（完全一致）

email／domain は完全一致です。小文字に正規化してください。複数の --filter フラグは OR で結合されます。

hubspot objects search --type contacts --filter "[email protected]" \
  --properties email,firstname,lastname,company,lifecyclestage,hubspot_owner_id

hubspot objects search --type companies --filter "domain=acme.com" \
  --properties name,domain,industry,annualrevenue,hubspot_owner_id

# OR — multiple emails in one call
hubspot objects search --type contacts \
  --filter "[email protected]" --filter "[email protected]" --properties email,firstname

3. 部分名による検索（トークン + クライアント側での絞り込み）

~ は CONTAINS_TOKEN です。スペースで区切られた単語単位で一致します。dealname~acme は「Acme Renewal」を見つけますが、「AcmeCorp」は見つけません。部分文字列を検索するには、jq にパイプしてください。すべてのフィールドを対象にした全文検索は存在しません。プロパティを指定してください。

hubspot objects search --type deals --filter "dealname~acme" --properties dealname,amount,dealstage \
| jq -c 'select(.properties.dealname | ascii_downcase | contains("acme corp"))'

4. 関連するすべてのレコードを検索する（xargs ではなく 2 回の CLI 呼び出し）

パターン: associations list → jq -c '{id}' → objects get バッチ。決して xargs -I{} hubspot objects get … を使わないでください。これはレコードごとに 1 つのプロセスを生成します。--from には複数形（contacts:12345）を使い、--help に表示されるとおりに指定してください。

# All contacts at a company
hubspot associations list --from companies:67890 --to contacts \
| jq -c '{id}' \
| hubspot objects get --type contacts --properties email,firstname,lastname,jobtitle

# Open deals for a contact (filter client-side; "open" varies by pipeline)
hubspot associations list --from contacts:12345 --to deals | jq -c '{id}' \
| hubspot objects get --type deals --properties dealname,amount,dealstage,hs_is_closed \
| jq -c 'select(.properties.hs_is_closed != "true")'

5. レコードとその関連を取得する

contact_id=12345
hubspot objects get --type contacts $contact_id --properties email,firstname,lastname,company,lifecyclestage

# Associated company (usually one)
hubspot associations list --from contacts:$contact_id --to companies | jq -c '{id}' | head -1 \
| hubspot objects get --type companies --properties name,domain,industry,annualrevenue

# Associated deals
hubspot associations list --from contacts:$contact_id --to deals | jq -c '{id}' \
| hubspot objects get --type deals --properties dealname,amount,dealstage,closedate

制約

• 検索は 1 ページあたり最大 100 件を返します。それ以上必要な場合は、bulk-operations/SKILL.md のページネーションループを使用してください。
• ~ はトークンベースです。部分文字列のフィルタリングは検索後に jq で行います。
• 検索が書き込み（更新、削除、マージ）につながる場合は、bulk-operations/SKILL.md の --dry-run → ダイジェスト → --confirm のフローに従ってください。