Blame for LINKEDIN_INTEGRATION.md

# LinkedIn Data Integration Guide

## 🚀 Quick Setup (5 Minutes)

This guide shows you how to integrate LinkedIn profile data into StrategyStack using RapidAPI's free tier.

---

## Step 1: Get Your Free API Key

1. **Sign up on RapidAPI** (free, no credit card): https://rapidapi.com
2. **Search for** "Fresh LinkedIn Profile Data"
3. **Subscribe to FREE tier** (50 requests/month)
4. **Copy your API key** from the dashboard

---

## Step 2: Add API Key to Spaces

1. Go to **Settings** tab in this Space
2. Scroll to **Variables and secrets**
3. Click **New secret**
4. Name: `RAPIDAPI_KEY`
5. Value: Paste your API key
6. Click **Save**

---

## Step 3: What You Get

### Free Tier (No Credit Card Required)
- ✅ 50 requests per month
- ✅ 1000 requests per hour rate limit
- ✅ Full profile data access
- ✅ 1-2 second response time

### Profile Data Includes:
- Full name, profile photo URL
- Current title & company
- Complete work history
- Education background
- Skills & endorsements
- Location, connections count
- Profile summary/bio
- LinkedIn profile URL

---

## Implementation Details

The integration is already built into the app via `linkedin_data.py`:

```python
import requests
import os

def fetch_linkedin_profile(profile_url: str) -> dict:
    """Fetch LinkedIn profile data using RapidAPI"""
    api_key = os.getenv('RAPIDAPI_KEY')
    
    url = "https://fresh-linkedin-profile-data.p.rapidapi.com/get-linkedin-profile"
    
    headers = {
        "x-rapidapi-key": api_key,
        "x-rapidapi-host": "fresh-linkedin-profile-data.p.rapidapi.com"
    }
    
    response = requests.get(url, headers=headers, params={"linkedin_url": profile_url})
    
    if response.status_code == 200:
        return response.json()
    return None
```

---

## Usage in Dashboard

Once configured, the dashboard automatically enriches lead data:

### Before Enrichment:
```python
lead = {
    "contact_id": "c123",
    "linkedin_url": "https://linkedin.com/in/username"
}
```

### After Enrichment:
```python
lead = {
    "contact_id": "c123",
    "linkedin_url": "https://linkedin.com/in/username",
    "full_name": "John Doe",
    "headline": "CEO at Tech Company",
    "location": "San Francisco, CA",
    "current_company": "Tech Company",
    "current_title": "Chief Executive Officer",
    "experience": [...],
    "education": [...],
    "skills": ["Leadership", "Strategy", ...]
}
```

---

## Cost & Scaling

### Free Tier Strategy
**50 requests/month is perfect for:**
- Initial demo and testing
- 1-2 pilot customers
- Enriching your "hottest" leads only
- Development environment

**Best Practices:**
- Cache enriched profiles (stored in user's `/data` directory)
- Only enrich leads with high engagement
- Don't re-fetch same profile repeatedly
- Use strategically for key decision-makers

### When to Upgrade

**Pro Plan: $50/month**
- 20,000 requests/month (~650/day)
- Perfect for 5-10 active customers
- Small-medium outreach campaigns

**Ultra Plan: $200/month**
- 100,000 requests/month (~3,300/day)
- 10-20 active customers
- Large-scale campaigns

**Mega Plan: $500/month**
- 500,000 requests/month (~16,600/day)
- Enterprise scale
- Unlimited customers

---

## Legal & Compliance

### What's Legal ✅
- Scraping **public** LinkedIn data (hiQ Labs v. LinkedIn precedent)
- Using for B2B lead enrichment
- Caching data for business purposes
- Providing value-added services to customers

### Best Practices ⚠️
- Use only for legitimate business purposes
- Don't resell raw LinkedIn data
- Respect privacy laws (GDPR, CCPA)
- Provide data opt-out mechanisms
- Be transparent with customers about data sources

### What to Avoid ❌
- Selling scraped data to third parties
- Storing sensitive personal data unnecessarily
- Excessive scraping (respect rate limits)
- Mixing with breached/unauthorized data

---

## Testing Your Integration

### Test Profile URLs:
```
https://linkedin.com/in/williamhgates
https://linkedin.com/in/jeffweiner08
https://linkedin.com/in/satyanadella
```

### Quick Test:
1. Add your `RAPIDAPI_KEY` to Spaces Secrets
2. Restart the Space
3. Go to "Consent/Event Audit" tab
4. Add a contact with a LinkedIn URL
5. Click "Refresh Data"
6. See enriched profile information!

---

## Troubleshooting

### "API Key Not Found" Error
**Solution:** 
- Verify `RAPIDAPI_KEY` is in Spaces Secrets
- Check spelling (case-sensitive)
- Restart Space after adding secret

### "Rate Limit Exceeded" Error
**Solution:**
- You've used your 50 free requests this month
- Wait until next month or upgrade plan
- Implement caching to reduce requests

### "Invalid Profile URL" Error
**Solution:**
- Use full LinkedIn URL: `https://linkedin.com/in/username`
- Remove trailing slashes
- Ensure profile is public

### Slow Response Times
**Solution:**
- First request may take 2-3 seconds (normal)
- Implement local caching for repeat requests
- Consider background job queue for bulk enrichment

---

## Alternative Options

### If You Need More Than 50/Month:

**Option 1: User OAuth**
- Have users connect their own LinkedIn
- Zero API costs
- Legal and compliant
- Already supported in this app!

**Option 2: Multiple RapidAPI Accounts**
- Rotate between 2-3 free accounts
- 150 requests/month total
- Good for early stage

**Option 3: Upgrade to Paid**
- $50/month gets you 20,000 requests
- Worth it once you have 3+ paying customers

---

## Advanced Features

### Caching Implementation
```python
def get_cached_or_fetch(linkedin_url: str) -> dict:
    cache_file = f"/data/linkedin_cache/{hash(linkedin_url)}.json"
    
    if os.path.exists(cache_file):
        with open(cache_file, 'r') as f:
            return json.load(f)
    
    profile = fetch_linkedin_profile(linkedin_url)
    
    if profile:
        os.makedirs(os.path.dirname(cache_file), exist_ok=True)
        with open(cache_file, 'w') as f:
            json.dump(profile, f)
    
    return profile
```

### Bulk Enrichment
```python
def enrich_lead_list(leads: list) -> list:
    enriched = []
    for lead in leads:
        if 'linkedin_url' in lead:
            profile = fetch_linkedin_profile(lead['linkedin_url'])
            if profile:
                lead.update(profile)
        enriched.append(lead)
    return enriched
```

---

## Support & Resources

**RapidAPI Documentation:**
- https://rapidapi.com/freshdata-freshdata-default/api/fresh-linkedin-profile-data

**API Response Format:**
```json
{
  "full_name": "John Doe",
  "headline": "CEO at Company",
  "location": "San Francisco, CA",
  "summary": "Experienced leader...",
  "experiences": [
    {
      "title": "CEO",
      "company": "Company Name",
      "start_date": "2020-01",
      "end_date": null,
      "description": "..."
    }
  ],
  "education": [...],
  "skills": [...]
}
```

**Need Help?**
- Check RapidAPI support: https://rapidapi.com/support
- Review HF Spaces docs: https://huggingface.co/docs/hub/spaces
- Contact StrategyStack support via Space discussions

---

## Summary

✅ **Free tier available** (50 requests/month, no credit card)
✅ **5-minute setup** (sign up, get key, add to Secrets)
✅ **Already integrated** into the app (just add API key)
✅ **Legal & compliant** (public data only)
✅ **Scales with you** (upgrade when ready)

**Get started now:** https://rapidapi.com

---

**Last Updated:** November 6, 2025
**Integration Status:** ✅ Ready to use - just add API key!
**Free Tier:** 50 requests/month | **Paid:** From $50/month