# Skill: Crustdata Enrichment

**Agents:** Rick (Revenue), Rene (R&D), Devin (Delivery Ops)
**Purpose:** Enrich company and person data via Crustdata API
**Auth:** `Authorization: Token $env:CRUSTDATA_API_KEY`
**Base URL:** `https://api.crustdata.com`
**Credits:** 1000 free credits provisioned. Company enrichment = 1 credit. Person search = 3 credits.

---

## Quick Reference

| Endpoint | Method | Credits | Use Case |
|----------|--------|---------|----------|
| `/screener/company` | GET | 1 | Enrich by domain/name/ID |
| `/screener/person/search/` | POST | 3 | Find decision-makers |
| `/screener/screen/` | POST | 1/result | Discover companies by filters |
| `/screener/social_posts` | GET | 1 | LinkedIn posts by person |

## Company Enrichment (1 credit)

**Use when:** You have a company domain, name, or LinkedIn URL and need firmographic data.

### PowerShell

```powershell
$headers = @{
  Authorization = "Token $env:CRUSTDATA_API_KEY"
  Accept = "application/json"
}
# By domain (up to 25 comma-separated)
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/company?company_domain=hubspot.com" -Headers $headers
# By name
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/company?company_name=HubSpot" -Headers $headers
# Specific fields only (reduces payload)
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/company?company_domain=hubspot.com&fields=company_name,headcount,company_website_domain" -Headers $headers
# Real-time enrichment (for companies not yet tracked — takes up to 10 min)
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/company?company_domain=example.com&enrich_realtime=True" -Headers $headers
```

### Response Fields (key subset)

- `company_id` — Crustdata internal ID
- `company_name` — Company name
- `company_website_domain` — Primary domain
- `linkedin_profile_url` — LinkedIn company page
- `headcount` — Current employee count
- `total_funding_raised_usd` — Total funding
- `last_updated_date` — Data freshness

## Person Search (3 credits)

**Use when:** You need to find decision-makers at a target company.

### PowerShell

```powershell
$headers = @{
  Authorization = "Token $env:CRUSTDATA_API_KEY"
  "Content-Type" = "application/json"
  Accept = "application/json"
}
$body = @{
  filters = @(
    @{ filter_type = "CURRENT_COMPANY"; type = "in"; value = @("HubSpot") }
    @{ filter_type = "CURRENT_TITLE"; type = "in"; value = @("Owner", "CEO", "Founder", "President", "Managing Director") }
    @{ filter_type = "REGION"; type = "in"; value = @("Dallas-Fort Worth, TX") }
  )
  page = 1
  limit = 25
} | ConvertTo-Json -Depth 4
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/person/search/" -Headers $headers -Method Post -Body $body
```

### Response Fields (key subset)

- `name` — Full name
- `title` — Current job title
- `company_name` — Current employer
- `linkedin_profile_url` — LinkedIn profile
- `emails` — Verified email addresses (array)
- `location` — Geographic location

## Company Discovery (1 credit per result)

**Use when:** Building prospect lists by region, industry, headcount, etc.

### PowerShell

```powershell
$headers = @{
  Authorization = "Token $env:CRUSTDATA_API_KEY"
  "Content-Type" = "application/json"
  Accept = "application/json"
}
$body = @{
  filters = @{
    op = "and"
    conditions = @(
      @{ column = "largest_headcount_country"; type = "="; value = "USA"; allow_null = $false }
      @{ column = "headcount"; type = ">="; value = "5"; allow_null = $false }
      @{ column = "headcount"; type = "<="; value = "50"; allow_null = $false }
    )
  }
  offset = 0
  count = 25
} | ConvertTo-Json -Depth 4
Invoke-RestMethod -Uri "https://api.crustdata.com/screener/screen/" -Headers $headers -Method Post -Body $body
```

## Lead Engine Integration

Crustdata enrichment is integrated into the lead-engine pipeline:

```powershell
$LE = "C:/Users/Administrator/.openclaw/workspace/leadspanther-lead-engine"
# Enrich companies (1 credit each)
npm --prefix $LE run enrich:crustdata-company
# Enrich decision-makers (3 credits each)
npm --prefix $LE run enrich:crustdata-person
# Or run full pipeline (includes Crustdata steps)
npm --prefix $LE run pipeline:run
```

DB columns populated: `crustdata_company_id`, `crustdata_headcount`, `crustdata_industry`, `crustdata_enriched_at`, `decision_maker_name`, `decision_maker_title`, `decision_maker_linkedin`, `decision_maker_email`, `crustdata_person_enriched_at`

## Cost Tracking

**Pricing:** $0.10 per credit (up to 250k credits/mo). $3,000/mo floor.
**Current balance:** 1,000 free credits provisioned (trial allocation).
**Pricing source:** https://docs.google.com/spreadsheets/d/1rC_T7oMqKemW23gVSqXSgTis8rF6VsTBlqfCRO3eFhE

| Operation | Credits | USD Cost |
|-----------|---------|----------|
| Company enrichment | 1 | $0.10 |
| Person enrichment | 3 | $0.30 |
| Live Company enrichment (real-time from source) | 5 | $0.50 |
| Live Person enrichment (real-time from source) | 5 | $0.50 |
| Company search — 1 record | 1 | $0.10 |
| Person search — 1 record | 1 | $0.10 |
| Company search — 100 records (in DB) | 1 | $0.10 |
| Person search — 100 records (in DB) | 3 | $0.30 |
| Email enrichment (get person's email) | 2 | $0.20 |
| Job listing per company | 1 | $0.10 |
| Post — full (content, links, metadata, reactions, reactors) | 5 | $0.50 |
| Post — content only, no reactors | 1 | $0.10 |

**Budget rules:**
- Max 25 companies per enrichment batch
- Max 10 person searches per batch
- Log total credits consumed after each batch
- Report to Friedrich (Finance) if monthly spend exceeds $50
- Current balance: 1,000 free credits (trial). After free credits: $3,000/mo floor applies.

## Fallback Cascade

1. **Crustdata** (primary) — richest data, real-time
2. **Google Maps scraping** (secondary) — free, basic contact info
3. **Apollo** (tertiary) — backup enrichment via `$env:APOLLO_API_KEY`

## Error Handling

- **401 Unauthorized** — Check `CRUSTDATA_API_KEY` in `.env`
- **429 Rate limited** — Wait 60 seconds, retry
- **No results** — Try `enrich_realtime=True` (adds 10 min delay). If still empty, fall back to Google Maps → Apollo.
- **Partial results** — Accept available data, flag missing fields for manual review