Sansan Agent

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:

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

Environment Variables

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:    [email protected]
     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:    [email protected]
     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:    [email protected]
     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  田中 健二            │
  │                                    │
  │  [email protected]             │
  │  +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: [email protected] vs SF: [email protected])
    - 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. | [email protected]
  B: Satou Takeshi (佐藤 健)    | Nissan Motor Co. | [email protected]
  Reason: Same kanji name, same company, different romanization

  Pair 2 (similarity: 88%)
  ─────────────────────────────────────────────────────────────
  A: Kobayashi Ren              | NTT Data         | [email protected]
  B: Kobayashi Ren              | NTT DATA Corp.   | [email protected]
  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

Data Storage

Sansan Agent stores minimal data locally for performance:

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

Comparison Table

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