Customer Enrichment

Overview

Customer enrichment augments your existing customer profiles with data from multiple sources. Each enrichment result includes a confidence score from 0 to 1 indicating data reliability. Enrichment data is stored alongside the customer record and updated periodically.

Enrich a Customer

Submit a customer email or ID for enrichment. The system queries multiple data sources and returns a unified profile with company information, job title, social links, and estimated income range. Results are cached and refreshed every 30 days.

const whale = new WhaleClient("wk_live_...");

const enriched = await whale.enrichment.enrich({
  customer_id: "cust_a1b2c3d4",
  email: "jane.rivera@acmecorp.com",
  sources: ["company_data", "social_profiles"]
});

// Response
{
  "object": "enrichment_result",
  "customer_id": "cust_a1b2c3d4",
  "confidence": 0.92,
  "company": {
    "name": "Acme Corporation",
    "domain": "acmecorp.com",
    "industry": "Technology",
    "employee_count": "201-500",
    "revenue_range": "$50M-$100M",
    "founded": 2012,
    "headquarters": "San Francisco, CA"
  },
  "person": {
    "title": "VP of Operations",
    "seniority": "executive",
    "department": "operations",
    "estimated_income": "$150,000-$200,000"
  },
  "social": {
    "linkedin": "https://linkedin.com/in/janerivera",
    "twitter": "@janerivera_ops"
  },
  "enriched_at": "2026-03-10T10:00:00.000Z",
  "expires_at": "2026-04-09T10:00:00.000Z"
}

Device Fingerprinting

Collect device fingerprints from storefront sessions to detect fraud, link anonymous sessions, and identify suspicious behavior. Fingerprints combine canvas rendering, WebGL parameters, and audio context signatures into a unique device identifier with a confidence score.

// Submit a device fingerprint (typically from storefront JS)
const fingerprint = await whale.enrichment.fingerprint({
  customer_id: "cust_a1b2c3d4",
  session_id: "sess_x9y8z7",
  signals: {
    canvas_hash: "a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5",
    webgl_renderer: "ANGLE (Apple, Apple M2 Pro, OpenGL 4.1)",
    webgl_vendor: "Google Inc. (Apple)",
    audio_hash: "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
    screen_resolution: "2560x1600",
    timezone: "America/Los_Angeles",
    language: "en-US",
    platform: "MacIntel",
    touch_support: false
  }
});

// Response
{
  "object": "device_fingerprint",
  "id": "dfp_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "device_id": "dev_unique_hash_abc123",
  "customer_id": "cust_a1b2c3d4",
  "confidence": 0.97,
  "is_suspicious": false,
  "seen_count": 3,
  "first_seen": "2026-02-15T08:30:00.000Z",
  "last_seen": "2026-03-10T11:00:00.000Z",
  "linked_customers": ["cust_a1b2c3d4"],
  "risk_factors": []
}

// Suspicious device example
{
  "device_id": "dev_unique_hash_xyz789",
  "confidence": 0.34,
  "is_suspicious": true,
  "risk_factors": [
    "canvas_inconsistency",
    "multiple_customers_same_device",
    "known_proxy_ip"
  ],
  "linked_customers": ["cust_a1b2c3d4", "cust_e5f6a7b8", "cust_c9d0e1f2"]
}

Block Suspicious Devices

Block device fingerprints flagged as suspicious to prevent fraudulent orders. Blocked devices are denied checkout access and their sessions are logged for review. You can unblock devices if a block was issued in error.

// Block a suspicious device
await whale.enrichment.block({
  device_id: "dev_unique_hash_xyz789",
  reason: "Multiple chargebacks from linked accounts",
  block_checkout: true,
  notify_team: true
});

// Response
{
  "object": "device_block",
  "id": "blk_f6a7b8c9-d0e1-2345-fghi-678901234567",
  "device_id": "dev_unique_hash_xyz789",
  "reason": "Multiple chargebacks from linked accounts",
  "block_checkout": true,
  "affected_customers": 3,
  "blocked_at": "2026-03-10T15:00:00.000Z",
  "blocked_by": "api_key"
}

// List all blocked devices
const blocked = await whale.enrichment.blocked({
  limit: 50
});

// Unblock a device
await whale.enrichment.unblock("blk_f6a7b8c9...");

API Reference