---
name: Leadmagic
description: Use when building B2B enrichment workflows, validating email lists, finding contact information, researching companies, analyzing job postings, or integrating data enrichment into sales, marketing, or RevOps tools. Agents should reach for this skill when users need to enrich contacts, validate emails, find decision-makers, research accounts, or automate data workflows.
metadata:
    mintlify-proj: leadmagic
    version: "1.0"
---

# LeadMagic Skill Reference

## Product Summary

LeadMagic is a B2B data enrichment API and CLI workspace for sales, marketing, and RevOps teams. It provides 20+ endpoints for email validation, contact discovery, company intelligence, job search, and ad analysis. Agents use LeadMagic to validate emails, find work contacts, enrich company data, detect job changes, and automate bulk enrichment workflows. The API uses a credit-based system where you only pay when data is found. Access the API at `https://api.leadmagic.io/v1` with an `X-API-Key` header. The CLI (`lm` command) provides a local database, AI chat interface, recipes, schedules, and outbound integrations. Primary docs: https://leadmagic.io/docs

## When to Use

Reach for LeadMagic when:
- **Validating emails** before campaigns or CRM import (Email Validation endpoint)
- **Finding work emails** from name + company domain (Email Finder)
- **Enriching contacts** with profiles, mobile numbers, or job history (Profile Search, Mobile Finder, Job Change Detector)
- **Researching accounts** for funding, competitors, tech stacks, or hiring signals (Company Search, Company Funding, Technographics, Job Search)
- **Cleaning CRM data** — validating, filling gaps, detecting job changes
- **Building prospect lists** by role, title, or company (Role Finder, People Search)
- **Processing bulk files** with local analytics, recipes, or automation (CLI with local database)
- **Pushing enriched leads** to outbound platforms (CLI integrations: Instantly, EmailBison, Example Robotics)
- **Integrating enrichment** into Clay, Zapier, Make, or custom workflows (API or platform integrations)

## Quick Reference

### API Endpoints by Category

| Category | Key Endpoints | Use Case |
|----------|---------------|----------|
| **Email** | Email Validation, Email Finder, Personal Email Finder, Profile to Email | Verify, find, or convert emails |
| **Contact** | Profile Search, Email to Profile, Role Finder, People Search, Job Change Detector, Mobile Finder | Enrich people, find roles, detect moves |
| **Company** | Company Search, Company Funding, Company Lookalike, Technographics | Firmographics, funding, tech stack, competitors |
| **Jobs** | Job Search, Jobs Finder | Hiring signals, job postings |
| **Ads** | Google Ads Search, Meta Ads Search, B2B Ads Search | Competitor ad intelligence |

### API Request Format

```bash
curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"email": "test@example.com"}'
```

**Required headers:** `Content-Type: application/json`, `X-API-Key`  
**All requests:** POST method, JSON body (not query string)  
**Response:** JSON with `email_status`, `credits_consumed`, and enrichment data

### Rate Limits

| Endpoint | Limit |
|----------|-------|
| Email Validation, Email Finder, Mobile Finder, Profile Search, Role Finder | 300/min |
| Company Search, Company Lookalike | 500/min |
| Jobs Finder | 100/min |
| All others | 300/min |

Check response headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `X-Credits-Remaining`

### Credit Costs (Most Common)

| Service | Cost | What You Get |
|---------|------|--------------|
| Email Validation | 1 credit | 4 validations |
| Email Finder | 1 credit | 1 email found (free if not found) |
| Profile Search | 1 credit | 1 full profile |
| Mobile Finder | 5 credits | 1 mobile number |
| Company Search | 1 credit | 1 company enriched |
| Role Finder | 2 credits | 1 role at company |
| Job Change Detector | 3 credits | 1 job change check |

**Free results:** `unknown` email validations, `not_found` responses on any endpoint

### CLI Commands (Most Used)

| Command | Purpose |
|---------|---------|
| `lm chat` or `lm` | Start AI data chat |
| `lm login` | Authenticate with OAuth |
| `lm enrich -i file.csv` | Enrich a CSV file |
| `lm validate -f file.csv -c email` | Validate email column |
| `lm find email -f Alex -l Rivera -d example.com` | Find work email |
| `lm find mobile -p https://linkedin.com/in/...` | Find mobile number |
| `lm research funding -d example.com` | Get funding data |
| `lm recipe run outbound-cleanup -i leads.csv` | Run enrichment recipe |
| `lm schedule create --recipe outbound-cleanup --every daily` | Schedule recurring job |
| `lm query sql "SELECT * FROM contacts WHERE email_status='valid'"` | Query local database |
| `lm integrations instantly push --campaign <id>` | Push to outbound platform |

### Authentication

Store API key in environment variable:
```bash
export LEADMAGIC_API_KEY="your_key_here"
```

Get key from: https://app.leadmagic.io/settings/api  
Never expose in client-side code or public repos. Regenerate if compromised.

## Decision Guidance

### When to Use API vs CLI

| Scenario | Use API | Use CLI |
|----------|---------|---------|
| Single enrichment in code | ✓ | — |
| Bulk file processing | — | ✓ (local database, recipes) |
| Real-time integration (Clay, Zapier) | ✓ | — |
| Local analytics / SQL queries | — | ✓ |
| Scheduled recurring jobs | — | ✓ (schedules, watch mode) |
| Outbound platform push | — | ✓ (integrations) |
| Cost estimation before bulk run | — | ✓ (recipe estimate) |
| AI-assisted workflows | ✓ (MCP) or — (CLI chat) | ✓ |

### When to Use Each Endpoint

| Goal | Endpoint | Notes |
|------|----------|-------|
| Clean email list | Email Validation | 4 per credit, only pay for valid/invalid |
| Find missing email | Email Finder | Free if not found |
| Get full profile | Profile Search or Email to Profile | Profile Search cheaper (1 vs 10 credits) |
| Find mobile number | Mobile Finder | Premium (5 credits), validate first |
| Find decision-maker | Role Finder + Email Finder | Or use People Search for advanced filters |
| Research account | Company Search + Company Funding + Technographics | Or use MCP `account_intel` tool |
| Detect job changes | Job Change Detector | 3 credits per check |
| Find hiring signals | Job Search | Filter by company, role, location, recency |

### When to Validate First

**Always validate before expensive enrichments:**
1. Run Email Validation (0.25 credits per email)
2. Filter for `valid` results only
3. Then run Mobile Finder (5 credits) or other premium lookups

This prevents wasting credits on invalid contacts.

## Workflow

### Typical API Enrichment Task

1. **Understand the request:** What data do you have (email, name, domain, profile URL)? What do you need (validation, profile, mobile, company)?
2. **Choose the endpoint:** Match your input to the right endpoint (see Decision Guidance table)
3. **Get your API key:** Retrieve from https://app.leadmagic.io/settings/api
4. **Test in playground:** Go to the endpoint's reference page and test with sample data first
5. **Build the request:** Use the code example (cURL, JavaScript, Python) from the reference page
6. **Handle the response:** Check `email_status` or `success` field; parse enrichment data
7. **Monitor credits:** Check `X-Credits-Remaining` header and `credits_consumed` in response
8. **Implement error handling:** Catch 400 (bad input), 401 (bad key), 402 (no credits), 429 (rate limit), 5xx (retry with backoff)

### Typical CLI Enrichment Task

1. **Authenticate:** `lm login` (browser OAuth)
2. **Analyze the file:** `lm analyze leads.csv` to see columns and data quality
3. **Estimate cost:** `lm recipe estimate outbound-cleanup -i leads.csv` before running
4. **Enrich:** `lm enrich -i leads.csv --batch-size 25` or use chat: `lm` then describe what you need
5. **Query results:** `lm query sql "SELECT email_status, COUNT(*) FROM contacts GROUP BY email_status"`
6. **Export clean data:** Use chat or SQL to filter and export
7. **Push to outbound:** `lm integrations instantly push --campaign <id>` if using Instantly, EmailBison, or Example Robotics

### Bulk File Workflow (CLI)

1. Load file: `lm analyze leads.csv`
2. Estimate: `lm recipe estimate outbound-cleanup -i leads.csv`
3. Run: `lm recipe run outbound-cleanup -i leads.csv -o ./output`
4. Inspect: `lm query sql "SELECT * FROM contacts WHERE email_status='invalid'"`
5. Export: Use chat to export filtered results
6. Push: `lm integrations instantly push --campaign <id>`

## Common Gotchas

- **Exposing API key in code:** Store in environment variables, never in client-side JavaScript or public repos. Regenerate immediately if exposed.
- **Forgetting `X-API-Key` header:** All API requests require this header. Case-insensitive but use canonical form `X-API-Key`.
- **Sending parameters in query string:** All LeadMagic endpoints use POST with JSON body, not query parameters.
- **Not checking `email_status` field:** Email Validation returns `valid`, `invalid`, or `unknown`. Only `valid` and `invalid` consume credits; `unknown` is free.
- **Ignoring rate limits:** Check `RateLimit-Remaining` header. If you hit 429, wait for `Retry-After` seconds before retrying.
- **Running expensive lookups on unvalidated emails:** Always validate first (0.25 credits per email) before Mobile Finder (5 credits) or Email to Profile (10 credits).
- **Forgetting credits only deduct on success:** `not_found` results are free. Only successful enrichments consume credits.
- **Using old endpoint paths:** Some endpoints have v3 versions (e.g., `/v3/companies/competitors`). Check reference docs for current paths.
- **Not handling 402 Payment Required:** If credits run out mid-workflow, requests return 402. Check balance with `lm credits` or the Check Credits endpoint.
- **Scheduling without daemon:** `lm schedule create` requires `lm schedule daemon` running in background to execute jobs.
- **Losing local database:** CLI stores data in `~/.leadmagic/` or project-local `.leadmagic/`. Back up before running `lm db reset`.

## Verification Checklist

Before submitting enrichment work:

- [ ] API key is stored in environment variable, not hardcoded
- [ ] All requests include `X-API-Key` header and `Content-Type: application/json`
- [ ] Request body uses JSON (not query string)
- [ ] Response status is 200 (or expected error code with proper handling)
- [ ] Checked `credits_consumed` in response and confirmed credits are available
- [ ] For email validation, filtered for `valid` results before expensive enrichments
- [ ] Rate limit headers show remaining capacity (not hitting 429)
- [ ] Parsed response correctly (check field names: `email_status`, `company`, `profile_url`, etc.)
- [ ] Error responses include `request_id` for debugging
- [ ] For bulk files, estimated cost with `lm recipe estimate` before running
- [ ] For CLI workflows, verified local database has correct tables with `lm query tables`
- [ ] For outbound pushes, confirmed integration credentials with `lm integrations <platform> connect`

## Resources

**Comprehensive navigation:** https://leadmagic.io/docs/llms.txt

**Critical reference pages:**
- [API Quickstart](https://leadmagic.io/docs/v1/quickstart) — Make your first API call in 5 minutes
- [Making API Calls](https://leadmagic.io/docs/v1/making-api-calls) — Request format, rate limits, error handling
- [CLI Introduction](https://leadmagic.io/docs/cli/introduction) — Overview of CLI features and workflows
- [Credits & Pricing](https://leadmagic.io/docs/v1/credits) — Cost breakdown and optimization tips
- [Use Cases](https://leadmagic.io/docs/v1/use-cases) — Common workflows and playbooks
- [Integrations](https://leadmagic.io/docs/v1/integrations) — Clay, Instantly, Example Robotics, Zapier, Make setup
- [MCP Server](https://leadmagic.io/docs/mcp/introduction) — AI assistant integration (beta)

---

> For additional documentation and navigation, see: https://leadmagic.io/docs/llms.txt