Clawhub-skills sansan-agent

Business card and contact intelligence — search, manage, sync digitized cards for Japanese B2B networking

install

source · Clone the upstream repo

git clone https://github.com/traygerbig/clawhub-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/traygerbig/clawhub-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/marketing-growth-pack/sansan-agent" ~/.claude/skills/traygerbig-clawhub-skills-sansan-agent && rm -rf "$T"

manifest: marketing-growth-pack/sansan-agent/SKILL.md

source content

  ╔══════════════════════════════════════════════════════════════╗
  ║                                                              ║
  ║   ███████╗ █████╗ ███╗   ██╗███████╗ █████╗ ███╗   ██╗      ║
  ║   ██╔════╝██╔══██╗████╗  ██║██╔════╝██╔══██╗████╗  ██║      ║
  ║   ███████╗███████║██╔██╗ ██║███████╗███████║██╔██╗ ██║      ║
  ║   ╚════██║██╔══██║██║╚██╗██║╚════██║██╔══██║██║╚██╗██║      ║
  ║   ███████║██║  ██║██║ ╚████║███████║██║  ██║██║ ╚████║      ║
  ║   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝  ║
  ║                      A G E N T                               ║
  ║          Business Card Intelligence Platform                 ║
  ║                                                              ║
  ╚══════════════════════════════════════════════════════════════╝

skill: sansan-agent

platform: sansan

protocol: REST API

lang: en/ja

cards: digitized

Turn every business card into actionable intelligence -- your CLI command center for Japan's #1 contact management platform.

Overview

Sansan Agent bridges the gap between physical business card exchange (meishi koukan) and modern CRM workflows. In Japanese business culture, the ritualized exchange of business cards remains the foundational act of professional relationship building. Sansan has digitized this process for over 9,000 companies, and this agent gives you direct CLI access to search, manage, tag, and sync every contact in your Sansan database without ever opening a browser.

The agent connects to the Sansan Open API to provide full-spectrum contact intelligence: real-time search across hundreds of thousands of digitized cards, company database lookups, duplicate detection, lead scoring based on interaction history, and seamless CRM synchronization. Whether you are preparing for a client meeting, cleaning up contact data after a trade show, or building an automated lead pipeline, Sansan Agent handles it from your terminal. The architecture is designed for reliability, with built-in rate limiting, pagination support, and offline caching of frequently accessed contacts.

  ┌─────────────────────────────────────────────────────────┐
  │                    SANSAN AGENT                          │
  │                   Architecture                           │
  ├─────────────────────────────────────────────────────────┤
  │                                                         │
  │   Terminal CLI                                          │
  │       │                                                 │
  │       ▼                                                 │
  │   ┌─────────┐    ┌──────────────┐    ┌──────────────┐  │
  │   │ Command │───▶│   API Auth   │───▶│  Sansan API  │  │
  │   │ Parser  │    │  (API Key)   │    │  api.sansan   │  │
  │   └─────────┘    └──────────────┘    │    .com       │  │
  │       │                              └──────┬───────┘  │
  │       │                                     │          │
  │       ▼                                     ▼          │
  │   ┌─────────┐    ┌──────────────┐    ┌──────────────┐  │
  │   │  Local  │◀───│  Response    │◀───│  Card/User   │  │
  │   │  Cache  │    │  Formatter   │    │  Database    │  │
  │   └─────────┘    └──────────────┘    └──────────────┘  │
  │       │                                     │          │
  │       ▼                                     ▼          │
  │   ┌─────────┐                        ┌──────────────┐  │
  │   │  CRM    │                        │  OCR Engine  │  │
  │   │  Sync   │                        │  99.9% Acc.  │  │
  │   └─────────┘                        └──────────────┘  │
  │                                                         │
  └─────────────────────────────────────────────────────────┘

System Prompt Instructions

When operating as the Sansan Agent, adhere to the following rules:

Always authenticate using the
```
SANSAN_API_KEY
```
header (
```
X-Sansan-Api-Key
```
) before any API call.
Default the API base to
```
https://api.sansan.com/v3.0
```
unless overridden by
```
SANSAN_API_BASE
```
.
Paginate all list endpoints automatically; never truncate results silently.
Respect Sansan API rate limits (100 requests/minute); implement exponential backoff on 429 responses.
Display all Japanese names in their original order (family name first) unless the user specifies Western order.
When searching contacts, use fuzzy matching by default; exact match only when
```
--exact
```
flag is provided.
Always show the card's digitization date and last-updated timestamp in output.
Mask email addresses in output when
```
--privacy
```
flag is set, showing only domain.
Export operations must confirm row count before writing to disk.
Duplicate detection should compare across name, email, company, and phone with configurable thresholds.
Lead scoring must use Sansan's built-in interaction metadata (last contacted, meeting count, shared connections).
Tag operations are idempotent -- applying an existing tag is a no-op, not an error.
Company lookups should return subsidiary and parent relationships when available.
CRM sync operations must log every created/updated/skipped record with a reason.
All timestamps must be displayed in JST (Asia/Tokyo) unless
```
--utc
```
flag is used.
Cache search results locally for 15 minutes to reduce API calls during iterative workflows.
Handle network errors gracefully with retry logic and clear user-facing messages.
Never delete contacts or cards without explicit
```
--confirm
```
flag; always prompt by default.

Environment Variables

Variable	Required	Default	Description
`SANSAN_API_KEY`	Yes	--	Your Sansan Open API key from admin console
`SANSAN_API_BASE`	No	`https://api.sansan.com`	API base URL (for staging/proxy)

Set these in your shell profile or

.env

file:

export SANSAN_API_KEY="ssn_live_abc123def456ghi789"
export SANSAN_API_BASE="https://api.sansan.com"

Commands

san search

-- Search contacts across all digitized cards

$ san search "Tanaka" --company "Toyota"

  Sansan Search Results (3 matches)
  ══════════════════════════════════════════════════════════════

  1. Tanaka Kenji (田中 健二)
     Title:    Senior Manager, Procurement Division
     Company:  Toyota Motor Corporation
     Email:    k.tanaka@toyota.co.jp
     Phone:    +81-50-3155-XXXX
     Card ID:  card_8f2a1b3c4d5e
     Scanned:  2025-11-03  |  Updated: 2026-01-15
     Tags:     [automotive] [tier-1] [nagoya]

  2. Tanaka Yuki (田中 裕樹)
     Title:    Deputy General Manager, IT Strategy
     Company:  Toyota Systems Corporation
     Email:    yuki.tanaka@toyotasystems.co.jp
     Phone:    +81-52-747-XXXX
     Card ID:  card_9a3b2c1d0e4f
     Scanned:  2024-06-22  |  Updated: 2025-09-30
     Tags:     [IT] [subsidiary]

  3. Tanaka Mio (田中 美緒)
     Title:    Manager, Global Purchasing
     Company:  Toyota Boshoku Corporation
     Email:    m-tanaka@toyota-boshoku.com
     Phone:    +81-566-26-XXXX
     Card ID:  card_1d2e3f4a5b6c
     Scanned:  2026-02-10  |  Updated: 2026-02-10
     Tags:     [automotive] [new-contact]

  ── 3 results in 0.42s ──

san contacts

-- List and filter contact database

$ san contacts --tag "automotive" --limit 5 --sort recent

  Contacts [tag: automotive] (showing 5 of 847)
  ══════════════════════════════════════════════════════════════

  Name                   Company                  Title                    Last Contact
  ─────────────────────  ───────────────────────  ───────────────────────  ────────────
  Suzuki Haruto          Honda Motor Co.          VP Engineering           2026-02-28
  Tanaka Mio             Toyota Boshoku Corp.     Manager, Global Purch.   2026-02-10
  Yamamoto Rin           Denso Corporation        Section Chief, R&D       2026-01-22
  Sato Takeshi           Nissan Motor Co.         Director, Supply Chain   2026-01-15
  Watanabe Yui           Mazda Motor Corp.        GM, Quality Assurance    2025-12-08

  ── Page 1/170 | Next: san contacts --page 2 ──

san cards

-- View raw card image and OCR data

$ san cards card_8f2a1b3c4d5e

  Card Detail: card_8f2a1b3c4d5e
  ══════════════════════════════════════════════════════════════

  ┌────────────────────────────────────┐
  │  TOYOTA MOTOR CORPORATION          │
  │                                    │
  │  Senior Manager                    │
  │  Procurement Division              │
  │                                    │
  │  Tanaka Kenji  田中 健二            │
  │                                    │
  │  k.tanaka@toyota.co.jp             │
  │  +81-50-3155-XXXX                  │
  │  1 Toyota-cho, Toyota City,        │
  │  Aichi 471-8571, Japan             │
  └────────────────────────────────────┘

  OCR Confidence:  99.7%
  Front/Back:      Front only
  Scanned by:      Ito Sakura (2025-11-03)
  Owner:           Nakamura Daiki
  Digitized:       2025-11-03T14:22:00+09:00

  ── card data retrieved in 0.18s ──

san tags

-- Manage contact tags and groups

$ san tags list

  Tag Management
  ══════════════════════════════════════════════════════════════

  Tag Name        Contacts    Created         Color
  ──────────────  ──────────  ──────────────  ──────
  automotive      847         2024-01-10      #E53935
  IT              312         2024-01-10      #1E88E5
  tier-1          198         2024-03-22      #43A047
  nagoya          156         2024-05-15      #FB8C00
  new-contact     89          2025-01-01      #8E24AA
  trade-show-25   234         2025-10-01      #00ACC1
  vip             42          2024-02-14      #FFD600

  ── 7 tags total ──

$ san tags add "partnership" --contacts card_8f2a1b3c4d5e,card_9a3b2c1d0e4f
  [OK] Tag "partnership" applied to 2 contacts.

san company

-- Company database lookup

$ san company "Toyota Motor"

  Company Intelligence: Toyota Motor Corporation
  ══════════════════════════════════════════════════════════════

  Company:        Toyota Motor Corporation (トヨタ自動車株式会社)
  Industry:       Automotive Manufacturing
  HQ:             Toyota City, Aichi Prefecture
  Employees:      ~375,000 (consolidated)
  Revenue:        45.1 trillion JPY (FY2025)
  Listed:         TSE Prime 7203 / NYSE TM

  Your Connections:
  ─────────────────────────────────────────────────────────────
  Direct contacts:      14
  Unique departments:   6
  Most recent card:     2026-02-10
  Key contact:          Tanaka Kenji (Procurement)

  Subsidiaries in DB:
  ─────────────────────────────────────────────────────────────
  Toyota Systems Corporation        5 contacts
  Toyota Boshoku Corporation        3 contacts
  Toyota Tsusho Corporation         8 contacts
  Daihatsu Motor Co., Ltd.          2 contacts

  ── company data retrieved in 0.31s ──

san export

-- Export contacts to CSV/JSON

$ san export --tag "trade-show-25" --format csv --output trade_show_contacts.csv

  Export Preview
  ══════════════════════════════════════════════════════════════

  Tag filter:     trade-show-25
  Total records:  234
  Format:         CSV
  Fields:         name, company, title, email, phone, tags
  Output:         ./trade_show_contacts.csv

  Proceed? (y/N): y

  [████████████████████████████████████████] 234/234

  [OK] Exported 234 contacts to trade_show_contacts.csv (48.2 KB)

san sync

-- Synchronize with external CRM

$ san sync --target salesforce --dry-run

  CRM Sync Preview (Salesforce)
  ══════════════════════════════════════════════════════════════

  Direction:       Sansan → Salesforce
  Mode:            Dry Run (no changes applied)

  Summary:
  ─────────────────────────────────────────────────────────────
  New contacts to create:     67
  Existing contacts to update: 143
  Contacts already in sync:   1,024
  Conflicts (manual review):  12

  Conflicts:
    - Suzuki Haruto: email differs (sansan: h.suzuki@honda.co.jp vs SF: haruto.s@honda.co.jp)
    - Kobayashi Ren: company name mismatch (sansan: NTT Data vs SF: NTT DATA Corporation)
    ...and 10 more

  Run without --dry-run to apply changes.

san leads

-- Lead scoring and prioritization

$ san leads --min-score 70 --limit 5

  Lead Scoring Report
  ══════════════════════════════════════════════════════════════

  Rank  Name               Company              Score   Signal
  ────  ─────────────────  ───────────────────  ──────  ──────────────────────
  1     Suzuki Haruto      Honda Motor Co.      94/100  3 meetings, replied 2x
  2     Yamamoto Rin       Denso Corporation    87/100  Opened proposal, new dept.
  3     Nakamura Aoi       Sony Group Corp.     82/100  Referred by VIP contact
  4     Ito Sakura         Fujitsu Limited      78/100  Downloaded whitepaper
  5     Tanaka Kenji       Toyota Motor Corp.   73/100  Long-term, quarterly mtg

  ── Scoring model: interaction-weighted v2 ──

san duplicates

-- Detect and merge duplicate contacts

$ san duplicates --threshold 80

  Duplicate Detection (threshold: 80%)
  ══════════════════════════════════════════════════════════════

  Found 6 potential duplicate pairs:

  Pair 1 (similarity: 95%)
  ─────────────────────────────────────────────────────────────
  A: Sato Takeshi (佐藤 健)     | Nissan Motor Co. | sato.t@nissan.co.jp
  B: Satou Takeshi (佐藤 健)    | Nissan Motor Co. | t-sato@nissan.co.jp
  Reason: Same kanji name, same company, different romanization

  Pair 2 (similarity: 88%)
  ─────────────────────────────────────────────────────────────
  A: Kobayashi Ren              | NTT Data         | ren.k@nttdata.com
  B: Kobayashi Ren              | NTT DATA Corp.   | kobayashi.ren@nttdata.com
  Reason: Same name, company name variant, different email format

  ...4 more pairs

  Merge all high-confidence pairs (>90%)? (y/N):

san report

-- Generate usage and networking analytics

$ san report --period monthly

  Monthly Networking Report (February 2026)
  ══════════════════════════════════════════════════════════════

  Cards Scanned:          48
  New Contacts Added:     41
  Duplicates Merged:      3
  Tags Applied:           127

  Top Companies (new contacts):
    Toyota Group          +6
    Sony Group            +4
    NTT Group             +3

  Department Breakdown:
    Engineering           35%   ██████████████
    Sales                 25%   ██████████
    Management            20%   ████████
    Procurement           12%   █████
    Other                  8%   ███

  Networking Velocity:    +12% vs Jan 2026
  Active Connections:     1,234 (30-day window)

  ── report generated in 1.2s ──

Workflow Diagram

  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │   Physical   │     │   Sansan     │     │   Sansan     │
  │  Card Scan   │────▶│  OCR Engine  │────▶│  Cloud DB    │
  │  (Scanner)   │     │  99.9% Acc.  │     │              │
  └──────────────┘     └──────────────┘     └──────┬───────┘
                                                   │
                            ┌──────────────────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │  Sansan Agent CLI   │
                 │  (san commands)     │
                 └──────────┬──────────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
            ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │   Search &   │ │  Tag/Group   │ │   Lead       │
    │   Filter     │ │  Management  │ │   Scoring    │
    └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
            │               │               │
            └───────────────┼───────────────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
            ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │  CSV / JSON  │ │  CRM Sync    │ │  Analytics   │
    │  Export      │ │  (Salesforce) │ │  Reports     │
    └──────────────┘ └──────────────┘ └──────────────┘

Error Handling

Error	Cause	Solution
`AUTH_FAILED: Invalid API key`	Expired or incorrect `SANSAN_API_KEY`	Regenerate key in Sansan admin console under API settings
`RATE_LIMIT: 429 Too Many Requests`	Exceeded 100 req/min limit	Agent auto-retries with backoff; reduce batch size with `--batch 50`
`NOT_FOUND: Card card_xxxx does not exist`	Card deleted or ID typo	Verify card ID with `san search` ; cards removed by admin are permanent
`SYNC_CONFLICT: Field mismatch on 12 records`	CRM data diverges from Sansan	Run `san sync --dry-run` first, then resolve conflicts in `--conflicts` file
`EXPORT_PERMISSION: Insufficient role`	API key lacks export scope	Request `export` permission from your Sansan administrator
`NETWORK_TIMEOUT: Connection timed out after 30s`	Sansan API unreachable	Check network; retry with `--retry 3` ; verify API status at status.sansan.com
`DUPLICATE_TAG: Tag "vip" already exists`	Attempting to create existing tag	Use `san tags add` to assign existing tag; no error if applying to contacts

Data Storage

Sansan Agent stores minimal data locally for performance:

Item	Location	Purpose	Retention
Search cache	`~/.sansan-agent/cache/`	Avoid redundant API calls	15 minutes (auto-purge)
Export files	Current working directory	CSV/JSON output	User-managed
Sync logs	`~/.sansan-agent/logs/sync/`	Audit trail for CRM operations	90 days
Config	`~/.sansan-agent/config.json`	API key, preferences	Persistent
Offline index	`~/.sansan-agent/index.db`	Local SQLite for fast name lookups	Rebuilt daily

All cached data is encrypted at rest using AES-256. No card images are stored locally -- only metadata.

Comparison Table

Feature	Sansan Agent (CLI)	Sansan Web UI	HubSpot CRM	Salesforce
Business card OCR	via Sansan (99.9%)	99.9%	No	No
CLI access	Yes	No	Limited	Limited
Japanese name handling	Native (kanji/kana)	Native	Basic	Basic
Bulk operations	Yes (batch mode)	Manual	API only	API only
Offline search	Cached index	No	No	No
CRM sync	Salesforce, HubSpot	Salesforce	Native	Native
Lead scoring	Interaction-based	Basic	Advanced	Advanced
Duplicate detection	Multi-field fuzzy	Basic	Email only	Email only
Export formats	CSV, JSON, TSV	CSV	CSV	CSV, XLSX
Setup time	2 minutes	N/A	30+ minutes	60+ minutes
Automation friendly	Full CLI/scripting	No	Partial	Partial

FAQ

Q1: How do I get a Sansan API key? Log into Sansan as an admin, navigate to Settings > External Services > API, and generate a new key with the required scopes.

Q2: Can I search by Japanese kanji and romaji simultaneously? Yes. The search engine normalizes both kanji and romanized inputs.

san search "田中"

and

san search "Tanaka"

return the same results.

Q3: What happens if I exceed the API rate limit? The agent implements automatic exponential backoff. It will retry up to 5 times with increasing delays (1s, 2s, 4s, 8s, 16s).

Q4: Can I sync bidirectionally with Salesforce? Currently, sync is Sansan-to-CRM (one-way). Bidirectional sync is on the roadmap for v1.2.0.

Q5: How accurate is the duplicate detection? The fuzzy matching algorithm compares name (kanji + romaji), email, phone, and company with configurable weight. Default threshold of 80% catches most real duplicates with minimal false positives.

Q6: Is card image data downloaded locally? No. Card images remain on Sansan servers. Only OCR-extracted text metadata is accessed via API.

Q7: Can I use this with Sansan's free plan? The API is available on Sansan's paid plans only. Contact your Sansan account manager for API access.

Q8: How does lead scoring work? Scores are calculated from interaction signals: meeting frequency, email replies, shared connections, recency of contact, and department relevance. Weights are configurable.

Q9: Can I filter exports by date range? Yes. Use

san export --from 2026-01-01 --to 2026-02-28

to export contacts scanned within a date range.

Q10: Does the agent support multiple Sansan organizations? Yes. Set different

SANSAN_API_KEY

values per profile using

san config --profile client-a

Q11: How do I handle contacts with no email address? Use

san contacts --missing email

to list contacts lacking email data, then prioritize manual enrichment.

Q12: Can I pipe search results to other commands? Absolutely. Use

--format json

with any command for machine-readable output:

san search "Honda" --format json | jq '.contacts[].email'

Clawhub-skills sansan-agent

Overview

System Prompt Instructions

Environment Variables

Commands

`san search`
-- Search contacts across all digitized cards

`san contacts`
-- List and filter contact database

`san cards`
-- View raw card image and OCR data

`san tags`
-- Manage contact tags and groups

`san company`
-- Company database lookup

`san export`
-- Export contacts to CSV/JSON

`san sync`
-- Synchronize with external CRM

`san leads`
-- Lead scoring and prioritization

`san duplicates`
-- Detect and merge duplicate contacts

`san report`
-- Generate usage and networking analytics

Workflow Diagram

Error Handling

Data Storage

Comparison Table

FAQ