traygerbig ╔══════════════════════════════════════════════════════════════╗
║ ║
║ ███████╗ █████╗ ███╗ ██╗███████╗ █████╗ ███╗ ██╗ ║
║ ██╔════╝██╔══██╗████╗ ██║██╔════╝██╔══██╗████╗ ██║ ║
║ ███████╗███████║██╔██╗ ██║███████╗███████║██╔██╗ ██║ ║
║ ╚════██║██╔══██║██║╚██╗██║╚════██║██╔══██║██║╚██╗██║ ║
║ ███████║██║ ██║██║ ╚████║███████║██║ ██║██║ ╚████║ ║
║ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ║
║ 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_KEYheader (X-Sansan-Api-Key) before any API call. - Default the API base to
https://api.sansan.com/v3.0unless overridden bySANSAN_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
--exactflag is provided. - Always show the card's digitization date and last-updated timestamp in output.
- Mask email addresses in output when
--privacyflag 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
--utcflag 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
--confirmflag; 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'.