data-enrichment

What this skill does

# Data Enrichment with x402 APIs

Use the agentcash MCP tools to access enrichment APIs at stableenrich.dev.

## Setup

See [rules/getting-started.md](rules/getting-started.md) for installation and wallet setup.

## Notes
ALWAYS use agentcash.fetch for stableenrich.dev endpoints - never curl or WebFetch.
Returns structured JSON data, not web page HTML.

IMPORTANT: Use exact endpoint paths from the Quick Reference table below. All paths include a provider prefix (`https://stableenrich.dev/api/apollo/...`, `https://stableenrich.dev/api/clado/...`, etc.).

## Quick Reference

| Task | Endpoint | Price | Best For |
|------|----------|-------|----------|
| Enrich person | `https://stableenrich.dev/api/apollo/people-enrich` | $0.0495 | Email/LinkedIn -> full profile |
| Enrich company | `https://stableenrich.dev/api/apollo/org-enrich` | $0.0495 | Domain -> company data |
| Search people | `https://stableenrich.dev/api/apollo/people-search` | $0.02 | Find people by criteria |
| Search companies | `https://stableenrich.dev/api/apollo/org-search` | $0.02 | Find companies by criteria |
| Contact recovery | `https://stableenrich.dev/api/clado/contacts-enrich` | $0.20 | Find missing email/phone |
| Verify email | `https://stableenrich.dev/api/hunter/email-verifier` | $0.03 | Check deliverability |
| Influencer by email | `https://stableenrich.dev/api/influencer/enrich-by-email` | $0.40 | Email -> social profiles |
| Influencer by social | `https://stableenrich.dev/api/influencer/enrich-by-social` | $0.40 | Handle -> creator data |
| Minerva resolve | `https://stableenrich.dev/api/minerva/resolve` | $0.02 | Person -> Minerva PID + LinkedIn |
| Minerva enrich | `https://stableenrich.dev/api/minerva/enrich` | $0.05 | Consumer demographics + contact |
| Minerva email check | `https://stableenrich.dev/api/minerva/validate-emails` | $0.01 | Check emails in Minerva DB |

## Workflows

### Standard Enrichment

- [ ] (Optional) Check balance: `agentcash.get_balance`
- [ ] Use `agentcash.discover_api_endpoints(url="https://stableenrich.dev")` to list all endpoints
- [ ] Use `agentcash.check_endpoint_schema(url="...")` to see expected parameters and pricing
- [ ] Call endpoint with `agentcash.fetch`
- [ ] Parse and present results

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/apollo/people-enrich",
  method="POST",
  body={"email": "[email protected]"}
)
```

## Person Enrichment

Enrich a person using any available identifier:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/apollo/people-enrich",
  method="POST",
  body={
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "organization_name": "Acme Inc",
    "domain": "company.com",
    "linkedin_url": "https://linkedin.com/in/johndoe"
  }
)
```

**Input options** (provide any combination):
- `email` - Email address (most reliable)
- `linkedin_url` - LinkedIn profile URL
- `first_name` + `last_name` - Name (works better with domain/org)
- `organization_name` or `domain` - Helps match the right person

**Returns**: Name, title, company, employment history, location, social profiles, phone numbers.

## Company Enrichment

Enrich a company by domain:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/apollo/org-enrich",
  method="POST",
  body={
    "domain": "stripe.com"
  }
)
```

**Returns**: Company name, industry, employee count, revenue estimates, funding info, technologies used, social links.

## People Search

Search for people matching criteria:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/apollo/people-search",
  method="POST",
  body={
    "q_keywords": "software engineer",
    "person_titles": ["CTO", "VP Engineering"],
    "organization_domains": ["google.com", "meta.com"],
    "person_locations": ["San Francisco, CA"]
  }
)
```

**Search filters**:
- `q_keywords` - Keywords to search
- `person_titles` - Job title filters
- `organization_domains` - Company domains
- `person_locations` - Location filters
- `person_seniorities` - Seniority levels

## Company Search

Search for companies matching criteria:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/apollo/org-search",
  method="POST",
  body={
    "q_keywords": "fintech",
    "organization_locations": ["New York, NY"],
    "organization_num_employees_ranges": ["51-200", "201-500"]
  }
)
```

## Contact Recovery (Clado)

Enrich contact info from LinkedIn URL, email, or phone. Provide exactly one of `linkedin_url`, `email`, or `phone`:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/clado/contacts-enrich",
  method="POST",
  body={
    "linkedin_url": "https://linkedin.com/in/johndoe"
  }
)
```

**Returns**: Validated email addresses and phone numbers with confidence scores.

**Note:** For LinkedIn profile data (experience, education, skills), use Minerva `/api/minerva/enrich` instead of Clado.

## Minerva Identity Resolution

Resolve a person to a unique Minerva PID and LinkedIn URL:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/minerva/resolve",
  method="POST",
  body={
    "records": [
      {
        "record_id": "user_001",
        "first_name": "John",
        "last_name": "Smith",
        "emails": ["[email protected]"]
      }
    ]
  }
)
```

**Parameters:**
- `records` array with: `record_id`, `first_name`, `last_name`, `emails`, `phones`, `linkedin_url`
- Supports fuzzy match (name + contact) and reverse lookup (email/phone only, no name needed)
- Use `match_condition_fields: ["linkedin_url"]` to only return matches with LinkedIn

## Minerva Enrichment

Enrich with demographics, work history, education, contact info, addresses, financial signals:

Three lookup modes: by Minerva PID (fastest), by LinkedIn URL, or by name/email/phone.

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/minerva/enrich",
  method="POST",
  body={
    "records": [
      {
        "record_id": "user_001",
        "first_name": "John",
        "last_name": "Smith",
        "emails": ["[email protected]"]
      }
    ],
    "return_fields": ["full_name", "personal_emails", "phones", "work_experience"]
  }
)
```

**Parameters:**
- `records` array with: `record_id` + one of `minerva_pid`, `linkedin_url`, or name/email/phone
- `return_fields` array to limit response (e.g., `["full_name", "personal_emails", "phones", "work_experience"]`)
- `match_condition_fields` to filter matches (e.g., `["email", "phone"]`)

## Minerva Email Validation

Check if emails exist in the Minerva database:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/minerva/validate-emails",
  method="POST",
  body={
    "records": ["[email protected]", "[email protected]"]
  }
)
```

**Returns**: Validation status and last-seen timestamps. Use before resolve/enrich to pre-screen lists.

## Cost Optimization

### Field Filtering

Reduce costs by excluding unneeded fields:

```
body={
  "email": "[email protected]",
  "excludeFields": ["employment_history", "photos", "phone_numbers"]
}
```

Common fields to exclude:
- `employment_history` - Past jobs (often large)
- `photos` - Profile images
- `phone_numbers` - If you only need email
- `social_profiles` - If you don't need social links

### Search Before Enrich

Use search endpoints ($0.02) to find the right records before enriching ($0.0495):

1. Search for candidates: `https://stableenrich.dev/api/apollo/people-search`
2. Review results, pick the right match
3. Enrich only the matches you need

## Parallel Calls

When enriching multiple independent records, make calls in parallel:

```mcp
# These can run simultaneously since they're independent
agentcash.fetch(url=".../people-enrich", body={"email": "[email protected]"})
agentcash.fetch(url=".../people-enrich", body={"email": "[email protected]"})
```

## Email Verification (Hunter)

Verify if an email address is deliverable before sending outreach:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/hunter/email-verifier",
  method="POST",
  body={
    "email": "john@stri