data-enrichment

# 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. ## Mandatory workflow Before any stableenrich.dev call: 1. `agentcash.discover_api_endpoints(url="https://stableenrich.dev")` — list live endpoints 2. `agentcash.check_endpoint_schema(url="https://stableenrich.dev/api/...")` — confirm request fields and pricing 3. `agentcash.fetch` with the schema from step 2 **Never guess field names.** FullEnrich people-search uses `current_company_domains` and `current_position_seniority_level` — not `company_domain`, `person_titles`, `titles`, or `seniority`. Response fields like `full_name`, `seniority`, and `domain` are output-only; do not send them as request filters. ## Quick Reference | Task | Endpoint | Price | Best For | | -------------------- | ---------------------------------------------------------- | ------------------ | --------------------------------- | | Search people | `https://stableenrich.dev/api/fullenrich/people-search` | $0.15 if results | Find people by domain/seniority | | Search companies | `https://stableenrich.dev/api/fullenrich/company-search` | $0.15 if results | Find companies by criteria | | Enrich person | `https://stableenrich.dev/api/pdl/people-enrich` | $0.28 if match | LinkedIn URL/email -> full profile | | Enrich person (alt) | `https://stableenrich.dev/api/minerva/enrich` | $0.05 | Demographics, work history | | Minerva resolve | `https://stableenrich.dev/api/minerva/resolve` | $0.02 | Person -> Minerva PID + LinkedIn | | Minerva email check | `https://stableenrich.dev/api/minerva/validate-emails` | $0.01 | Check emails in Minerva DB | | Enrich company | `https://stableenrich.dev/api/companyenrich/org-enrich` | $0.06 | Domain -> company data | | Company by name/URL | `https://stableenrich.dev/api/companyenrich/properties-enrich` | $0.06 | When domain unknown | | 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 | For social media creators, use **stablesocial.dev** — influencer endpoints are not on stableenrich.dev. ## Workflows ### Standard Enrichment - [ ] (Optional) Check balance: `agentcash.get_balance` - [ ] Only call `agentcash.list_accounts` if you need deposit links or network-specific wallet addresses - [ ] `agentcash.discover_api_endpoints(url="https://stableenrich.dev")` - [ ] `agentcash.check_endpoint_schema(url="...")` for the selected endpoint - [ ] Call endpoint with `agentcash.fetch` - [ ] Parse results at `.data.*` (AgentCash wraps the HTTP body) ## Person Enrichment (PDL) Prefer `profile` (LinkedIn URL) or `email`. Name + company is a fallback only. ```mcp agentcash.fetch( url="https://stableenrich.dev/api/pdl/people-enrich", method="POST", body={"profile": "https://www.linkedin.com/in/johndoe"} ) ``` ```mcp agentcash.fetch( url="https://stableenrich.dev/api/pdl/people-enrich", method="POST", body={"email": "john@company.com"} ) ``` **Valid inputs** (one required path): - `email` — most reliable when known - `profile` — LinkedIn profile URL - `first_name` + `last_name` + (`company_name` OR `company_domain`) — fallback **Returns**: Career history, emails, phone. No match: HTTP 200 with `data: null` — not billed. ## Company Enrichment (CompanyEnrich) ```mcp agentcash.fetch( url="https://stableenrich.dev/api/companyenrich/org-enrich", method="POST", body={"domain": "stripe.com"} ) ``` **Returns**: Company name, industry, employee/revenue range strings, funding, social links. Verify returned `domain` matches intent before downstream people searches. ## People Search (FullEnrich) Start with **domain + seniority**; add `current_position_titles` only when you need exact title match. ```mcp agentcash.fetch( url="https://stableenrich.dev/api/fullenrich/people-search", method="POST", body={ "current_company_domains": [{"value": "stripe.com"}], "current_position_seniority_level": [{"value": "VP"}] } ) ``` **Key filters**: - `current_company_domains` — company domain(s) - `current_position_seniority_level` — enum: `C-level`, `VP`, `Head`, `Director`, `Manager`, etc. - `current_position_titles` — exact title match (returns far fewer results) - `person_locations`, `person_professional_network_urls`, and 20+ other FullEnrich filters **Not valid**: `offset` alone, `company_domain`, `titles`, `seniority`, `limit`, Apollo `person_titles` / `person_seniorities`. Returns up to 10 people per query. Empty `people` → not billed. ## Company Search (FullEnrich) ```mcp agentcash.fetch( url="https://stableenrich.dev/api/fullenrich/company-search", method="POST", body={ "domains": [{"value": "anthropic.com", "exact_match": true}], "headquarters_locations": [{"value": "United States"}] } ) ``` Requires at least one search filter. Paginate via `search_after` from `metadata`. ## LinkedIn / Profile Data For full profile by LinkedIn URL, use PDL or Minerva — not a separate scrape endpoint: ```mcp agentcash.fetch( url="https://stableenrich.dev/api/pdl/people-enrich", method="POST", body={"profile": "https://www.linkedin.com/in/johndoe"} ) ``` ```mcp agentcash.fetch( url="https://stableenrich.dev/api/minerva/enrich", method="POST", body={ "records": [{"record_id": "user_001", "linkedin_url": "https://www.linkedin.com/in/johndoe"}], "return_fields": ["full_name", "personal_emails", "phones", "work_experience"] } ) ``` ## Minerva Identity Resolution Resolve a person to a 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": ["john@company.com"]}] } ) ``` Requires at least one email or phone per record — it cannot match on name alone. ## Minerva Enrichment Enrich with demographics, work history, education, contact info, addresses, financial signals: ```mcp agentcash.fetch( url="https://stableenrich.dev/api/minerva/enrich", method="POST", body={ "records": [{"record_id": "user_001", "linkedin_url": "https://www.linkedin.com/in/johndoe"}], "return_fields": ["full_name", "personal_emails", "phones", "work_experience"] } ) ``` Lookup modes: by `minerva_pid` (fastest), `linkedin_url` in each record, or name/email/phone. ## Minerva Email Validation ```mcp agentcash.fetch( url="https://stableenrich.dev/api/minerva/validate-emails", method="POST", body={"records": ["john@company.com", "jane@example.com"]} ) ``` ## Contact Recovery (Clado) Find missing email or phone from a LinkedIn URL: ```mcp agentcash.fetch( url="https://stableenrich.dev/api/clado/contacts-enrich", method="POST", body={ "linkedin_url": "https://www.linkedin.com/in/johndoe", "email_enrichment": true, "phone_enrichment": true } ) ``` ## Parallel Calls When enriching multiple independent records, make parallel `fetch` calls — there are no bulk enrich endpoints: ```mcp agentcash.fetch(url="https://stableenrich.dev/api/pdl/people-enrich", body={"email": "a@co.com"}) agentcash.fetch(url="https://stableenrich.dev/api/pdl/people-enrich", body={"email": "b@co.com"}) ``` ## Cost Optimization ### Search Before Enrich 1. Search: `fullenrich/people-search` ($0.15 if results) — find candidates 2. Enrich: `pdl/people-enrich` ($0.28 if match) — get email and career history 3. Verify: `hunter/email-verifier` ($0.03) — confirm deliverability ### Field Filtering FullEnrich people-search supports `excludeFields` to trim response size (e.g. `["educations", "skills", "languages"]`). ## Email Verification (Hunter) ```mcp agentcash.fetch( url="https://stableenrich.dev/api/hunter/email-verifier", method="POST", body={"email": "john@stripe.com"} ) ``` | Status | Meaning | Action | | ------------ | ----------------------------------- | ----------------- | | `valid` | Email exists and accepts mail | Safe to send | | `invalid` | Email doesn't exist or rejects mail | Do not send | | `accept_all` | Catch-all domain | Send with caution | | `webmail` | Personal webmail provider | Usually fine | | `disposable` | Temporary/throwaway address | Do not send | | `unknown` | Could not determine status | Try again later | Fast/cached checks return the final result immediately; if Hunter is still processing, the response includes a `jobId` — poll `GET /api/hunter/email-verifier/jobs/{jobId}` (free, SIWX, same wallet that paid). ## Handling missing data If a query returns empty or incomplete data: 1. Re-run `discover_api_endpoints` and try an alternate provider (PDL vs Minerva vs Clado contacts) 2. Verify company domain with `companyenrich/org-enrich` or `fullenrich/company-search` before people searches 3. Fall back to Exa web search on stableenrich.dev for LinkedIn URLs or domains, then retry enrich with discovered identifiers For social media creator data, use **stablesocial.dev** instead of stableenrich.dev.