# Authentication
Source: https://leadmagic.io/docs/cli/authentication

Sign in to the LeadMagic CLI with browser OAuth

The LeadMagic CLI uses browser OAuth for chat, enrichment, validation, credits, and account-backed features. Your session is stored locally and refreshed when possible.

## Sign In

The recommended way to authenticate is the browser-based OAuth flow:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm login
```

This opens your browser to sign in to LeadMagic. After authentication, your session is saved locally. You can skip the browser confirmation prompt with `-y`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm login -y
```

<Tip>
  `lm login` also accepts the aliases `lm auth`, `lm signin`, and `lm sign-in`.
</Tip>

## Config File

Authentication state is stored in the config file:

* **Global:** `~/.leadmagic/config.json`
* **Project-local:** `.leadmagic/config.json` (when run inside a project directory)

The CLI uses project-local config when a `.leadmagic/` directory exists in the current or parent directory. Otherwise it falls back to the global config.

<Warning>
  Keep authentication files secret. Never commit `config.json` to version control. The `.leadmagic/` directory should be in your `.gitignore`.
</Warning>

## One Login For Everything

Your LeadMagic login powers account-backed CLI features:

| Feature                          | Requires Login                  |
| -------------------------------- | ------------------------------- |
| AI Chat (`lm chat`)              | Yes - routes through AI Gateway |
| Enrichment (`lm enrich`)         | Yes                             |
| Email Validation (`lm validate`) | Yes                             |
| Contact Finding (`lm find`)      | Yes                             |
| Credit Check (`lm dashboard`)    | Yes                             |
| File Analysis (`lm analyze`)     | No                              |
| Database Queries (`lm query`)    | No                              |
| Health Check (`lm doctor`)       | No                              |

## Sign Out

To clear your authentication:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm logout
```

This removes the stored auth token while preserving non-auth configuration such as database, theme, and integration settings. Aliases: `lm signout`, `lm sign-out`.

## Verify Authentication

Check that your credentials are working:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm dashboard
```

This displays your account info and credit balance. If authentication is failing, run `lm doctor` to diagnose the issue.

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/cli/quickstart">
    Run your first enrichment workflow.
  </Card>

  <Card title="Configuration" icon="sliders" href="/cli/configuration">
    All config options including database, model, and theme.
  </Card>
</CardGroup>


# AI Chat
Source: https://leadmagic.io/docs/cli/chat

Natural language data chat, slash commands, local database actions, and session management in the LeadMagic CLI

The AI chat is the primary interface of the LeadMagic CLI. Describe the outcome you want and the CLI can load files, inspect columns, clean records, call LeadMagic enrichment tools, query the local database, and export the results.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm chat
```

Running `lm` with no arguments also starts chat — it's the default command.

## How It Works

When you type a message, the AI:

1. **Interprets your intent** — understands whether you want cleaning, enrichment, research, SQL, export, or troubleshooting
2. **Selects tools** — picks the right file, database, LeadMagic, recipe, schedule, or outbound action
3. **Executes the workflow** — runs steps in order, asks before spending credits, and stores results locally
4. **Streams progress** — shows tool calls, progress, and results as the work runs

## Example Conversations

<AccordionGroup>
  <Accordion title="Load and enrich a CSV" icon="file-csv">
    ```
    You: Load contacts.csv and show me a summary
    AI:  Loaded 1,247 rows with columns: name, email, company, title...

    You: Find work emails for contacts that are missing them
    AI:  Found 342 contacts without emails. I'll use the email finder...
         [Processing: ████████░░ 85/342 — 1 credit each]
         Found 298 emails. 44 contacts had insufficient data.

    You: Export the results
    AI:  Saved to .leadmagic/export/20260306-email-finder/contacts_enriched.csv
    ```
  </Accordion>

  <Accordion title="Validate an email list" icon="envelope-circle-check">
    ```
    You: Validate all emails in campaign-list.csv
    AI:  Loaded 5,000 emails from column "email"...
         [Validating: ████████████ 5000/5000 — 0.25 credits each]
         Results: 4,102 valid, 612 invalid, 286 unknown

    You: Remove the invalid ones and export
    AI:  Removed 612 invalid emails. Exported 4,388 contacts to
         .leadmagic/export/20260306-validation/campaign-list_validated.csv
    ```
  </Accordion>

  <Accordion title="Research a company" icon="building">
    ```
    You: What can you tell me about example.com?
    AI:  Company: Example Robotics, Inc.
         Industry: Financial Technology
         Employees: 8,000+
         HQ: San Francisco, CA
         ...

    You: What's their tech stack?
    AI:  Looking up company technographics...
         React, Node.js, Ruby, Go, AWS, PostgreSQL...

    You: Who are their main competitors?
    AI:  Searching for competitor companies...
         Adyen, Square, PayPal, Braintree, Checkout.com...
    ```
  </Accordion>

  <Accordion title="Turn a file into a repeatable workflow" icon="clock">
    ```
    You: I get this same leads.csv every Monday. Make a repeatable cleanup and enrichment flow.
    AI:  I can turn this into a recipe: normalize names, validate emails,
         find missing work emails, and export eligible contacts.

    You: Estimate the cost on this file before running it.
    AI:  Estimated 1,247 rows. Validation + email discovery will cost up to...

    You: Schedule it every weekday at 9am.
    AI:  Created schedule. Start the scheduler with lm schedule daemon.
    ```
  </Accordion>

  <Accordion title="Use local analytics" icon="database">
    ```
    You: Which companies in my table have the most valid contacts?
    AI:  Running SQL against the local database...
         SELECT company, COUNT(*) ...

    You: Show only accounts with funding data and at least 3 contacts.
    AI:  Here are the matching accounts. I can export this segment or push it.
    ```
  </Accordion>
</AccordionGroup>

## Slash Commands

Type `/` followed by a command name for quick actions. Type `/help` to see all available commands.

<Tabs>
  <Tab title="Files" icon="folder">
    | Command   | Description                      |
    | --------- | -------------------------------- |
    | `/browse` | Browse files in a directory      |
    | `/find`   | Find CSV or XLSX files           |
    | `/files`  | Show files in current directory  |
    | `/output` | Set output directory for exports |
    | `/clean`  | Open cleaning operation picker   |
    | `/merge`  | Merge CSV or Excel files         |
  </Tab>

  <Tab title="Info" icon="circle-info">
    | Command      | Description                                        |
    | ------------ | -------------------------------------------------- |
    | `/commands`  | List all slash commands (compact reference)        |
    | `/help`      | Show comprehensive command reference with examples |
    | `/status`    | Show system status                                 |
    | `/whoami`    | Show logged-in user info                           |
    | `/credits`   | Check LeadMagic credits                            |
    | `/pricing`   | Show LeadMagic API pricing                         |
    | `/shortcuts` | Show keyboard shortcuts                            |
  </Tab>

  <Tab title="Config" icon="sliders">
    | Command   | Description                                               |
    | --------- | --------------------------------------------------------- |
    | `/config` | Display current configuration                             |
    | `/theme`  | Get or set theme (dracula, tokyo-night, nord, catppuccin) |
    | `/scroll` | Get or set scroll speed (1–10)                            |
    | `/auth`   | Show authentication status for enrichment tools           |
    | `/model`  | Show AI routing status                                    |
  </Tab>

  <Tab title="Chat" icon="comments">
    | Command     | Description                                        |
    | ----------- | -------------------------------------------------- |
    | `/sessions` | List and switch sessions                           |
    | `/editor`   | Open `$EDITOR` to compose a message                |
    | `/export`   | Export session as Markdown to `.leadmagic/export/` |
    | `/thinking` | Toggle visibility of model reasoning blocks        |
    | `/expand`   | Toggle expand/collapse of reasoning blocks         |
    | `/clear`    | Clear chat history                                 |
  </Tab>

  <Tab title="System" icon="gear">
    | Command     | Description                                     |
    | ----------- | ----------------------------------------------- |
    | `/exit`     | Exit the application                            |
    | `/table`    | Show the current data as a table                |
    | `/columns`  | Toggle visible columns in the last table result |
    | `/compact`  | Toggle compact mode                             |
    | `/optimize` | Optimize database performance                   |
  </Tab>

  <Tab title="Enrichment" icon="wand-magic-sparkles">
    Quick enrichment commands for single records:

    | Command             | Description                                   |
    | ------------------- | --------------------------------------------- |
    | `/validate`         | Validate a single email address               |
    | `/find-email`       | Find email address for a contact              |
    | `/find-mobile`      | Find mobile phone number for a contact        |
    | `/role-finder`      | Find people by role at a company              |
    | `/employees`        | Find employees at a company                   |
    | `/email-to-profile` | Find a LinkedIn profile from an email address |
    | `/personal-email`   | Find personal emails from a LinkedIn profile  |
    | `/enrich-company`   | Enrich company data by domain or name         |
    | `/clear-context`    | Clear enrichment context                      |
  </Tab>

  <Tab title="Automation & Integrations" icon="bolt">
    | Command       | Description                                   |
    | ------------- | --------------------------------------------- |
    | `/recipe`     | List available enrichment recipes             |
    | `/watch`      | Show watch mode status or start/stop help     |
    | `/schedule`   | List schedules or show scheduling help        |
    | `/job-change` | Job change detection and monitoring           |
    | `/instantly`  | Instantly campaign management and push        |
    | `/emailbison` | EmailBison campaign management and push       |
    | `/smartlead`  | Example Robotics campaign management and push |
  </Tab>
</Tabs>

## Local Context

The chat has access to your local LeadMagic workspace:

* Imported CSV and Excel tables
* Query results and visible table columns
* Chat sessions and exported transcripts
* Recipe definitions and schedule history
* Outbound push history
* Account status, credits, and pricing

Use `@` to reference a file and `/table` or `/columns` to inspect the current data view.

## AI Routing

The CLI routes AI requests through the LeadMagic AI Gateway. Check routing status with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm status
lm config show
```

Inside chat, use:

```
/model
```

This shows the current AI routing status.

## Session Management

Chat sessions are automatically saved and can be resumed later.

| Action         | How         |
| -------------- | ----------- |
| List sessions  | `/sessions` |
| Start fresh    | `/clear`    |
| Export history | `/export`   |

Sessions are stored in the local database and persist across CLI restarts.

## Keyboard Shortcuts

| Shortcut | Action                         |
| -------- | ------------------------------ |
| `Enter`  | Send message / execute command |
| `↑ / ↓`  | Recall previous commands       |
| `Tab`    | Autocomplete commands          |
| `Escape` | Clear input                    |
| `Ctrl+C` | Exit application               |
| `Ctrl+L` | Clear screen                   |
| `Ctrl+K` | Open command palette           |
| `/`      | Start a slash command          |
| `@`      | Reference a file               |

## Next Steps

<CardGroup>
  <Card title="Command Reference" icon="book" href="/cli/commands">
    All commands for non-chat workflows.
  </Card>

  <Card title="Configuration" icon="sliders" href="/cli/configuration">
    Database, model, and theme settings.
  </Card>
</CardGroup>


# Command Reference
Source: https://leadmagic.io/docs/cli/commands

Current reference for LeadMagic CLI commands, subcommands, and common workflows

The LeadMagic CLI includes chat-first workflows plus direct commands for deterministic enrichment, analytics, automation, and outbound handoff. Run `lm help` for the current command list or `lm COMMAND --help` for command-specific flags.

## Global Options

| Option          | Description                                            |
| --------------- | ------------------------------------------------------ |
| `-v, --version` | Print the CLI version                                  |
| `--debug`       | Enable debug logging, also available with `LM_DEBUG=1` |
| `-h, --help`    | Show help for a command                                |

## Everyday Commands

| Command          | What it does                                     | Example             |
| ---------------- | ------------------------------------------------ | ------------------- |
| `lm` / `lm chat` | Start the AI data chat                           | `lm`                |
| `lm login`       | Sign in with browser OAuth                       | `lm login`          |
| `lm logout`      | Sign out                                         | `lm logout`         |
| `lm dashboard`   | Show account and credit details                  | `lm dashboard`      |
| `lm credits`     | Show credit balance                              | `lm credits`        |
| `lm pricing`     | Show enrichment pricing cheat sheet              | `lm pricing`        |
| `lm status`      | Show auth, config, AI routing, and credit status | `lm status`         |
| `lm doctor`      | Diagnose CLI, auth, database, and system issues  | `lm doctor --fix`   |
| `lm update`      | Check for and install CLI updates                | `lm update --check` |

## Data And AI Commands

Use these when you want file-level analysis or one-off AI assistance outside chat.

| Command      | What it does                                | Example                                                      |
| ------------ | ------------------------------------------- | ------------------------------------------------------------ |
| `lm scan`    | Find CSV, TSV, and Excel files              | `lm scan ./exports -d 3`                                     |
| `lm analyze` | Profile data quality, columns, and coverage | `lm analyze contacts.csv`                                    |
| `lm run`     | Run an AI prompt on a file                  | `lm run -f contacts.csv -p "summarize this data"`            |
| `lm think`   | Run an AI prompt with reasoning mode        | `lm think -f leads.csv -p "which rows should I prioritize?"` |

## Enrichment Commands

Direct enrichment commands call LeadMagic for specific lookup types.

| Command                     | What it does                                                                           | Example                                                           |
| --------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `lm enrich`                 | Enrich a CSV or Excel file with auto-detected columns                                  | `lm enrich -i contacts.csv --batch-size 25`                       |
| `lm validate`               | Validate email deliverability for addresses or a file column                           | `lm validate -f contacts.csv -c email`                            |
| `lm find email`             | Find a work email from name plus domain or company                                     | `lm find email -f Alex -l Rivera -d example.com`                  |
| `lm find mobile`            | Find a mobile number from profile URL, work email, or personal email                   | `lm find mobile -p https://linkedin.com/in/morgan-lee`            |
| `lm find role`              | Find people by title or function at a company                                          | `lm find role -c Example Robotics -t "VP Sales"`                  |
| `lm find employees`         | List employees at a company                                                            | `lm find employees -d example.com --limit 25`                     |
| `lm find profile`           | Resolve an email to a LinkedIn/B2B profile                                             | `lm find profile -e alex.rivera@example.com`                      |
| `lm find profile-search`    | Fetch a full professional profile from a profile URL or handle                         | `lm find profile-search -p linkedin.com/in/morgan-lee`            |
| `lm find linkedin-to-email` | Convert a LinkedIn profile URL to a work email                                         | `lm find linkedin-to-email -p https://linkedin.com/in/morgan-lee` |
| `lm find personal-email`    | Find personal emails from a LinkedIn profile                                           | `lm find personal-email -p https://linkedin.com/in/morgan-lee`    |
| `lm find jobs`              | Search job postings by company, title, location, seniority, remote status, and recency | `lm find jobs -c Example Robotics --level senior --remote`        |

## Company Research

The `research` command focuses on account intelligence signals.

| Command                   | What it does                                                   | Example                                               |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
| `lm research competitors` | Find competitor companies                                      | `lm research competitors -d example.com`              |
| `lm research funding`     | Show funding rounds, investors, revenue, and financial context | `lm research funding -d example.org`                  |
| `lm research tech`        | Show a company's technology stack                              | `lm research tech -d example.com -c Example Robotics` |

## Local Database

LeadMagic stores imported data, enrichment output, chat history, recipes, schedules, and run history in a local analytics database. Use SQL when you want exact answers.

| Command           | What it does                                              | Example                                                                |
| ----------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- |
| `lm query sql`    | Run SQL against local tables                              | `lm query sql "SELECT status, COUNT(*) FROM contacts GROUP BY status"` |
| `lm query tables` | List local tables                                         | `lm query tables`                                                      |
| `lm query schema` | Show table schema                                         | `lm query schema contacts`                                             |
| `lm db init`      | Initialize the database and migrations                    | `lm db init`                                                           |
| `lm db stats`     | Show memory, database size, table count, and row counts   | `lm db stats`                                                          |
| `lm db health`    | Run deep health checks with cleanup and performance hints | `lm db health`                                                         |
| `lm db vacuum`    | Compact the database, checkpoint WAL, and update stats    | `lm db vacuum`                                                         |
| `lm db analyze`   | Update query optimizer statistics                         | `lm db analyze`                                                        |
| `lm db repair`    | Repair stale WAL/temp files and re-run migrations         | `lm db repair`                                                         |
| `lm db unlock`    | Release stale local database locks                        | `lm db unlock --yes`                                                   |
| `lm db reset`     | Recreate the database from scratch                        | `lm db reset --confirm`                                                |

<Warning>
  `lm db reset --confirm` deletes local tables and run history. Export anything important first.
</Warning>

## Recipes, Schedules, And Watch Mode

Recipes are YAML enrichment pipelines. They make repeated cleanup and enrichment work predictable, estimable, and automatable.

| Command                                   | What it does                         | Example                                                                   |
| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------- |
| `lm recipe list`                          | List built-in and custom recipes     | `lm recipe list`                                                          |
| `lm recipe show`                          | Print recipe YAML                    | `lm recipe show outbound-cleanup`                                         |
| `lm recipe validate`                      | Validate a recipe file               | `lm recipe validate outbound-cleanup`                                     |
| `lm recipe estimate`                      | Estimate credits before a run        | `lm recipe estimate outbound-cleanup -i leads.csv`                        |
| `lm recipe run`                           | Execute a recipe on a CSV            | `lm recipe run outbound-cleanup -i leads.csv -o ./out`                    |
| `lm recipe delete`                        | Delete a custom recipe               | `lm recipe delete my-recipe`                                              |
| `lm schedule create`                      | Run a recipe on a cron or interval   | `lm schedule create --recipe outbound-cleanup -i leads.csv --every daily` |
| `lm schedule list`                        | List schedules                       | `lm schedule list`                                                        |
| `lm schedule pause` / `resume` / `delete` | Manage schedules                     | `lm schedule pause SCHEDULE_ID`                                           |
| `lm schedule run-now`                     | Execute a schedule immediately       | `lm schedule run-now SCHEDULE_ID`                                         |
| `lm schedule history`                     | Show recent scheduled run history    | `lm schedule history -n 20`                                               |
| `lm schedule daemon`                      | Start the foreground scheduler       | `lm schedule daemon --poll-interval 60`                                   |
| `lm watch setup`                          | Configure an inbound folder workflow | `lm watch setup`                                                          |
| `lm watch start`                          | Process new files as they arrive     | `lm watch start --recipe outbound-cleanup`                                |
| `lm watch status`                         | Show watch folder status             | `lm watch status`                                                         |
| `lm watch stop`                           | Stop an active watcher               | `lm watch stop`                                                           |

## Job Change Monitoring

Use job-change commands to check whether contacts still work where you expect.

| Command                 | What it does                                            | Example                                                                                          |
| ----------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `lm job-change check`   | Check one profile against an expected company           | `lm job-change check --profile https://linkedin.com/in/alex-rivera --company-domain example.com` |
| `lm job-change batch`   | Check eligible contacts from the local `contacts` table | `lm job-change batch -y`                                                                         |
| `lm job-change history` | Show recent contact-level results                       | `lm job-change history -n 20`                                                                    |
| `lm job-change runs`    | Show batch and scheduled run summaries                  | `lm job-change runs`                                                                             |

Alias: `lm jc`.

## Outbound Integrations

Push enriched, eligible contacts from the local database into outbound platforms. Each integration can verify credentials, list or create campaigns, push leads, show push history, export campaign leads, and read campaign stats.

| Platform         | Commands                                                              |
| ---------------- | --------------------------------------------------------------------- |
| Instantly        | `connect`, `campaigns`, `create`, `push`, `history`, `stats`, `leads` |
| EmailBison       | `connect`, `campaigns`, `create`, `push`, `history`, `stats`, `leads` |
| Example Robotics | `connect`, `campaigns`, `create`, `push`, `history`, `stats`, `leads` |

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm integrations instantly connect
lm integrations instantly campaigns
lm integrations instantly push --campaign <id>
lm integrations emailbison leads <campaign-id> --output leads.csv
lm integrations smartlead stats <campaign-id>
```

Alias: `lm int`.

## Configuration And Setup

| Command                    | What it does                                                | Example                         |
| -------------------------- | ----------------------------------------------------------- | ------------------------------- |
| `lm init`                  | Initialize project or global LeadMagic workspace            | `lm init --local`               |
| `lm config get`            | Read a config value                                         | `lm config get dbPath`          |
| `lm config set`            | Set a config value, prompting securely for sensitive keys   | `lm config set instantlyApiKey` |
| `lm config show`           | Show account, database, AI, integration, and display config | `lm config show`                |
| `lm config interactive`    | Open the interactive configuration UI                       | `lm config interactive`         |
| `lm completions install`   | Install shell completions for bash, zsh, or fish            | `lm completions install -s zsh` |
| `lm completions show`      | Print completion script                                     | `lm completions show -s fish`   |
| `lm completions uninstall` | Remove installed completions                                | `lm completions uninstall`      |
| `lm welcome`               | Show the welcome and setup status screen                    | `lm welcome --fast`             |

Useful config keys include `dbPath`, `dbMemoryLimit`, `dbThreads`, `outputDir`, `theme`, `plainTextMessages`, `instantlyApiKey`, `emailBisonApiKey`, `emailBisonInstanceUrl`, and `smartleadApiKey`.

## Common Workflows

<AccordionGroup>
  <Accordion title="Clean and enrich a lead file" icon="wand-magic-sparkles">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm analyze leads.csv
    lm enrich -i leads.csv --batch-size 25
    lm query sql "SELECT * FROM contacts WHERE email_status = 'valid'"
    ```
  </Accordion>

  <Accordion title="Research an account" icon="building">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm research funding -d example.com
    lm research competitors -d example.com
    lm research tech -d example.com -c Example Robotics
    lm find jobs -c Example Robotics --posted-within 30
    ```
  </Accordion>

  <Accordion title="Automate weekly enrichment" icon="clock">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm recipe estimate outbound-cleanup -i weekly-leads.csv
    lm schedule create --recipe outbound-cleanup -i weekly-leads.csv --cron "0 9 * * 1"
    lm schedule daemon
    ```
  </Accordion>

  <Accordion title="Push ready leads to outbound" icon="paper-plane">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm integrations instantly connect
    lm integrations instantly campaigns
    lm integrations instantly push --campaign <id>
    lm integrations instantly history
    ```
  </Accordion>
</AccordionGroup>


# Configuration
Source: https://leadmagic.io/docs/cli/configuration

Config file, database settings, AI Gateway routing, themes, integrations, and export directories for the LeadMagic CLI

The LeadMagic CLI stores configuration in a JSON file and supports environment variable overrides.

## Config File Location

| Location          | Path                       | When Used                                                                |
| ----------------- | -------------------------- | ------------------------------------------------------------------------ |
| **Project-local** | `.leadmagic/config.json`   | When a `.leadmagic/` directory exists in the current or parent directory |
| **Global**        | `~/.leadmagic/config.json` | Fallback when no project-local directory is found                        |

The CLI checks for a project-local `.leadmagic/` directory first, walking up the directory tree. If none is found, it uses the global directory at `~/.leadmagic/`.

Initialize a project-local directory:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm init --local
```

Initialize the global directory:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm init --global
```

## Configuration Keys

Manage config values with `lm config`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm config show          # Show all settings
lm config get dbPath    # Get a specific value
lm config set theme tokyo-night
```

### User Config Keys

These keys can be set via `lm config set <key> <value>`:

| Key                     | Type         | Description                                  | Default                       |
| ----------------------- | ------------ | -------------------------------------------- | ----------------------------- |
| `baseUrl`               | string (URL) | API base URL                                 | `https://api.leadmagic.io`    |
| `dbPath`                | string       | Path to database file                        | `~/.leadmagic/data.db`        |
| `dbMemoryLimit`         | string       | Database memory limit (e.g., `2GB`, `512MB`) | —                             |
| `dbThreads`             | number       | Number of database threads (1–256)           | —                             |
| `outputDir`             | string       | Export output directory                      | `.leadmagic/export`           |
| `theme`                 | string       | Terminal UI color theme                      | `leadmagic`                   |
| `plainTextMessages`     | boolean      | Render chat messages as plain text           | `false`                       |
| `instantlyApiKey`       | string       | Instantly integration API key                | —                             |
| `emailBisonApiKey`      | string       | EmailBison integration API key               | —                             |
| `emailBisonInstanceUrl` | string       | EmailBison instance URL                      | `https://dedi.emailbison.com` |
| `smartleadApiKey`       | string       | Example Robotics integration API key         | —                             |
| `axiomLoggingEnabled`   | boolean      | Enable optional remote operational logs      | `false`                       |
| `axiomDataset`          | string       | Axiom dataset name                           | —                             |
| `axiomToken`            | string       | Axiom ingest token                           | —                             |
| `axiomIngestBaseUrl`    | string       | Axiom ingest base URL                        | —                             |

### Internal Config Keys

These are managed automatically by the CLI:

| Key                  | Type   | Description                          |
| -------------------- | ------ | ------------------------------------ |
| `authToken`          | string | OAuth access token (from `lm login`) |
| `refreshToken`       | string | OAuth refresh token                  |
| `authTokenExpiresAt` | number | Token expiry timestamp (ms)          |
| `userInfo`           | object | Cached user info (email, name)       |
| `workerBaseUrl`      | string | AI Gateway URL                       |
| `scrollSpeed`        | number | Scroll speed (1–10)                  |
| `acceptedTermsAt`    | string | ISO timestamp of terms acceptance    |
| `dbQueryTimeout`     | number | SQL query timeout (ms)               |
| `dbMaxRows`          | number | Max rows returned from queries       |

## Environment Variables

| Variable        | Overrides       | Description                        |
| --------------- | --------------- | ---------------------------------- |
| `LM_WORKER_URL` | `workerBaseUrl` | AI Gateway URL                     |
| `LM_DEBUG`      | —               | Set to `1` to enable debug logging |

## Database Configuration

The CLI uses a local embedded database for storing loaded data, query results, and metadata.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm config set dbPath /path/to/custom.db
lm config set dbMemoryLimit 4GB
lm config set dbThreads 8
```

Database management commands:

| Command         | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `lm db init`    | Initialize database and run migrations                        |
| `lm db stats`   | Show database statistics and memory usage                     |
| `lm db health`  | Deep database health check with cleanup and performance hints |
| `lm db vacuum`  | Compact database, reclaim space                               |
| `lm db analyze` | Update query optimizer statistics                             |
| `lm db repair`  | Fix corruption and re-run migrations                          |
| `lm db reset`   | Drop all tables and data                                      |
| `lm db unlock`  | Release database lock from stale processes                    |

<Warning>
  `lm db reset` is destructive and cannot be undone. Exported files in `.leadmagic/export/` are preserved.
</Warning>

## AI Gateway Routing

The CLI routes AI chat and prompt workflows through the LeadMagic AI Gateway. Concrete model selection is managed server-side so the CLI can use the best available model for each workflow.

Check AI routing:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm status
lm config show
lm config get aiModel
```

In chat, view routing status:

```
/model
```

## Themes

The CLI supports multiple terminal themes:

| Theme         | Description             |
| ------------- | ----------------------- |
| `leadmagic`   | LeadMagic default theme |
| `dracula`     | Dark purple theme       |
| `tokyo-night` | Dark blue theme         |
| `nord`        | Arctic blue theme       |
| `catppuccin`  | Warm pastel theme       |

Set a theme:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm config set theme tokyo-night
```

Or switch in chat:

```
/theme
```

## Export Directory

All enrichment, validation, and export results are saved to timestamped subdirectories:

```
.leadmagic/export/
├── 20260306-143022-email-finder/
│   └── contacts_enriched.csv
├── 20260306-151045-validation/
│   └── campaign_validated.csv
└── 20260306-160812-enrich/
    └── leads_enriched.csv
```

Each operation creates a new timestamped directory to prevent overwriting previous results.

Set a custom output directory:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm config set outputDir /path/to/exports
```

## Interactive Configuration

Open the full interactive configuration UI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm config interactive
```

This provides a terminal-based interface for browsing and editing all settings. Aliases: `lm config ui`, `lm config tui`.

## Next Steps

<CardGroup>
  <Card title="Command Reference" icon="book" href="/cli/commands">
    Commands for enrichment, local SQL, automation, and integrations.
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/cli/troubleshooting">
    Common issues and how to fix them.
  </Card>
</CardGroup>


# Installation
Source: https://leadmagic.io/docs/cli/installation

Install the LeadMagic CLI on macOS, Linux, or Windows

Install the LeadMagic CLI in one command. The installer downloads a self-contained binary with a bundled runtime — no additional dependencies required.

## Install

<Tabs>
  <Tab title="macOS / Linux" icon="apple">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://releases.leadmagic.io/install.sh | bash
    ```

    The installer:

    * Downloads the correct binary for your platform and architecture
    * Installs to `~/.leadmagic/bin/lm`
    * Adds `~/.leadmagic/bin` to your `PATH` (updates your shell profile)
    * Runs `lm welcome` to confirm the install

    <Tip>
      Open a new terminal or run `source ~/.zshrc` (or `~/.bashrc`) after install for the `PATH` update to take effect.
    </Tip>
  </Tab>

  <Tab title="Windows" icon="windows">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    irm https://releases.leadmagic.io/install.ps1 | iex
    ```

    The installer downloads the binary and adds it to your `PATH`.

    <Warning>
      Windows support is experimental. The installer downloads the Linux binary and rebuilds native modules locally, which requires additional tooling.
    </Warning>
  </Tab>

  <Tab title="Direct Download" icon="file-arrow-down">
    Download a tarball directly from the releases server:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # Latest version
    curl -O https://releases.leadmagic.io/latest/lm-darwin-arm64.tar.gz

    # Specific version
    curl -O https://releases.leadmagic.io/v2.1.16/lm-v2.1.16-darwin-arm64.tar.gz
    ```

    Extract and move to your `PATH`:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    tar -xzf lm-darwin-arm64.tar.gz
    mv lm ~/.leadmagic/bin/lm
    chmod +x ~/.leadmagic/bin/lm
    ```

    **Checksums** are available for verification:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -O https://releases.leadmagic.io/latest/checksums.txt
    sha256sum -c checksums.txt
    ```
  </Tab>
</Tabs>

## Platform Support

| Platform | Architecture          | Status       |
| -------- | --------------------- | ------------ |
| macOS    | Apple Silicon (arm64) | Supported    |
| macOS    | Intel (x64)           | Supported    |
| Linux    | x64                   | Supported    |
| Linux    | arm64                 | Supported    |
| Windows  | x64                   | Experimental |

## Version Pinning

Install a specific version by setting the `VERSION` environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
VERSION=2.1.16 curl -fsSL https://releases.leadmagic.io/install.sh | bash
```

Change the install directory with `LEADMAGIC_INSTALL_DIR`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
LEADMAGIC_INSTALL_DIR=/opt/leadmagic curl -fsSL https://releases.leadmagic.io/install.sh | bash
```

## Verify Installation

Run the health check to confirm everything is working:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor
```

If issues are found, auto-repair with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --fix
```

Use `--verbose` for detailed diagnostic output:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --verbose
```

## Shell Completions

Enable tab completions for your shell:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm completions install
```

Supports bash, zsh, and fish. The shell is auto-detected, or specify it explicitly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm completions install --shell zsh
```

Remove completions with:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm completions uninstall
```

## Update

The CLI checks for updates automatically and shows a one-line notice when a newer version is available.

To update manually:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm update
```

To check for updates without installing:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm update --check
```

## Uninstall

Remove the CLI and all associated files:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://releases.leadmagic.io/install.sh | bash -s -- --uninstall
```

This removes the binary and the `~/.leadmagic/bin` directory. Your data (config, database, exports) in `~/.leadmagic/` is preserved. Delete that directory manually if you want a complete removal.

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/cli/authentication">
    Sign in with browser OAuth.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/cli/quickstart">
    Your first enrichment workflow in 5 minutes.
  </Card>
</CardGroup>


# LeadMagic CLI
Source: https://leadmagic.io/docs/cli/introduction

AI-powered command line workspace for B2B enrichment, local analytics, automation, and outbound handoff

# LeadMagic CLI <Badge>Beta</Badge>

The LeadMagic CLI turns your terminal into a B2B data workspace. Load CSV or Excel files, chat with your data, validate emails, find contacts, enrich companies, run local SQL, automate recurring workflows, monitor job changes, and push clean records into outbound platforms.

<Warning>
  **Beta** — The CLI is fully functional but still in beta. Commands, flags, and behavior may change. We'd love your feedback — reach out at [support@leadmagic.io](mailto:support@leadmagic.io) or via the [Help Center](https://help.leadmagic.io/en).
</Warning>

<Note>
  **One-line install:**

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -fsSL https://releases.leadmagic.io/install.sh | bash
  ```

  See the full [installation guide](/docs/cli/installation) for all platforms.
</Note>

## Key Features

<CardGroup>
  <Card title="AI Data Chat" icon="message">
    Ask for outcomes in plain English: load files, clean rows, enrich contacts, query tables, and export results.
  </Card>

  <Card title="28+ Commands" icon="terminal">
    Direct commands for enrichment, research, recipes, schedules, watch folders, database health, outbound pushes, and more.
  </Card>

  <Card title="Powerful Local Database" icon="database">
    Files load into a local analytics database so you can run SQL, inspect tables, track runs, and keep an audit trail.
  </Card>

  <Card title="Automation Built In" icon="clock">
    Create YAML recipes, schedule them on cron or intervals, or watch an inbound folder and auto-process new files.
  </Card>
</CardGroup>

## What You Can Do

<Tabs>
  <Tab title="Chat With Data" icon="message">
    Start an AI chat and describe what you need in plain English:

    ```
    > Load contacts.csv and find work emails for everyone
    > Validate all the emails in column B
    > Enrich the companies with funding, competitors, jobs, and tech stacks
    > Which rows are missing the fields we need for mobile lookup?
    > Export the results to a new CSV
    ```

    The AI coordinates file loading, column detection, LeadMagic API calls, SQL queries, and exports.
  </Tab>

  <Tab title="Analyze Locally" icon="database">
    Scan, profile, and query files before spending credits:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm scan ./exports
    lm analyze contacts.csv
    lm query sql "SELECT domain, COUNT(*) FROM contacts GROUP BY domain"
    lm db stats
    lm db health
    ```

    The CLI keeps your source data, enrichment results, chat sessions, schedules, and run history in a local database under `.leadmagic/` or `~/.leadmagic/`.
  </Tab>

  <Tab title="Enrich & Research" icon="magnifying-glass">
    Use direct commands when you already know the lookup you want:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm validate -f contacts.csv -c email
    lm find email -f "Alex" -l "Rivera" -d example.com
    lm find mobile -p https://linkedin.com/in/morgan-lee
    lm research competitors -d example.com
    lm research funding -d example.org
    lm find jobs -c Example Robotics --level senior --remote
    ```
  </Tab>

  <Tab title="Automate Workflows" icon="clock">
    Turn repeatable enrichment work into recipes, schedules, and folder watchers:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm recipe list
    lm recipe estimate outbound-cleanup -i leads.csv
    lm recipe run outbound-cleanup -i leads.csv
    lm schedule create --recipe outbound-cleanup -i leads.csv --every daily
    lm watch setup
    lm watch start
    ```
  </Tab>

  <Tab title="Ship To Outbound" icon="paper-plane">
    Push clean, eligible records into outbound tools after enrichment:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm integrations instantly campaigns
    lm integrations instantly push --campaign <id>
    lm integrations emailbison push --campaign <id>
    lm integrations smartlead stats <campaign-id>
    ```
  </Tab>
</Tabs>

## Why It Is Powerful

The CLI is not just a wrapper around API calls. It gives you a local data layer, an AI chat interface, and a job runner in one place:

* **Local analytics** - query your imported files and enrichment output with SQL.
* **Credit-aware workflows** - estimate costs, check credits, and plan recipe spend before bulk runs.
* **Repeatability** - save multi-step enrichment logic as recipes and run it on demand, on a schedule, or when files appear in a folder.
* **Operational history** - inspect database health, job-change run history, schedule runs, and outbound push history.
* **AI plus exact commands** - chat when you want guidance; use direct commands when you want deterministic scripts.

Data is stored locally in a database at `~/.leadmagic/` or project-local `.leadmagic/`. Your files stay on your machine unless you choose to submit fields for LeadMagic enrichment.

## Get Started

<CardGroup>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install on macOS, Linux, or Windows in one command.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/cli/quickstart">
    Your first enrichment workflow in 5 minutes.
  </Card>

  <Card title="Command Reference" icon="book" href="/cli/commands">
    All major commands, subcommands, and examples.
  </Card>

  <Card title="AI Chat Guide" icon="message" href="/cli/chat">
    Natural language chat, slash commands, and session management.
  </Card>
</CardGroup>


# Quickstart
Source: https://leadmagic.io/docs/cli/quickstart

Your first enrichment workflow with the LeadMagic CLI in 5 minutes

Go from zero to enriched data in 5 minutes. This guide walks you through installing the CLI, authenticating, and running your first enrichment.

## Step-by-Step

<Steps>
  <Step title="Install the CLI">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://releases.leadmagic.io/install.sh | bash
    ```

    Open a new terminal after install, then verify:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm --version
    ```
  </Step>

  <Step title="Sign in">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm login
    ```

    `lm login` opens your browser and saves a local OAuth session for chat, enrichment, dashboard, and account-backed commands.
  </Step>

  <Step title="Verify your setup">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm doctor
    ```

    You should see all checks passing. If not, run `lm doctor --fix` to auto-repair.
  </Step>

  <Step title="Scan for data files">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm scan
    ```

    This scans the current directory for CSV, TSV, and Excel files. You'll see a list of files with row counts and detected columns.
  </Step>

  <Step title="Analyze a file">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm analyze contacts.csv
    ```

    Get a data health report: quality score, column coverage, and enrichment recommendations. Save the report with `-o report.md`.
  </Step>

  <Step title="Start an AI chat">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm chat
    ```

    This opens the interactive AI chat. Try these prompts:

    ```
    > Load contacts.csv
    > How many rows have valid emails?
    > Validate all emails in the email column
    > Find work emails for contacts missing them
    > Export the enriched data
    ```

    The AI loads your file, calls the right LeadMagic tools, and saves results to `.leadmagic/export/`.
  </Step>
</Steps>

## Alternative: Direct Commands

If you prefer commands over chat, you can enrich and validate directly:

<Tabs>
  <Tab title="Validate Emails" icon="envelope-circle-check">
    Validate specific emails:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm validate alex.rivera@example.com alex.rivera@example.com sam.taylor@example.com
    ```

    Validate from a CSV file:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm validate -f contacts.csv -c email
    ```
  </Tab>

  <Tab title="Find Contacts" icon="magnifying-glass">
    Find a work email:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm find email -f "Alex" -l "Rivera" -d example.com
    ```

    Find a mobile number:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm find mobile -f "Alex" -l "Rivera" -c "Example Robotics"
    ```
  </Tab>

  <Tab title="Batch Enrich" icon="arrows-rotate">
    Enrich an entire CSV file:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm enrich -i contacts.csv
    ```

    Specify columns explicitly:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm enrich -i contacts.csv \
      --email-column email \
      --first-name-column first_name \
      --last-name-column last_name \
      --domain-column company_domain
    ```
  </Tab>
</Tabs>

## What Happens to Your Data

* **Local storage:** CSV/Excel files are loaded into a local database in `~/.leadmagic/` (or project-local `.leadmagic/`).
* **Exports:** Enriched results are saved to `.leadmagic/export/{timestamp}-{operation}/` with timestamped directories.
* **Privacy:** Only the specific fields needed for enrichment (emails, names, domains) are sent to the LeadMagic API. Your full dataset stays local.

## Check Your Credits

See your account balance and usage:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm dashboard
```

Or ask in chat: *"How many credits do I have?"*

## Next Steps

<CardGroup>
  <Card title="Command Reference" icon="book" href="/cli/commands">
    Commands for enrichment, local SQL, recipes, schedules, watch mode, and outbound integrations.
  </Card>

  <Card title="AI Chat Guide" icon="message" href="/cli/chat">
    Slash commands, sessions, and natural language workflows.
  </Card>

  <Card title="Configuration" icon="sliders" href="/cli/configuration">
    Database, model, and theme settings.
  </Card>

  <Card title="Credits & Pricing" icon="coins" href="/v1/credits">
    Credit costs per service and plan options.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://leadmagic.io/docs/cli/troubleshooting

Common issues and solutions for the LeadMagic CLI

Common issues and solutions for the LeadMagic CLI.

## Quick Diagnostics

Run the built-in health check:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor
```

Auto-repair fixable issues:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --fix
```

Verbose diagnostics:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm doctor --verbose
```

`lm doctor` checks your config file, database, authentication status, and system requirements.

## Debug Logging

Enable detailed logging for any command:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm --debug chat
lm --debug enrich -i contacts.csv
```

Or set the environment variable:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export LM_DEBUG=1
lm chat
```

Debug output includes API requests, tool calls, database queries, and internal state.

## Authentication Issues

<AccordionGroup>
  <Accordion title="Not signed in" icon="key">
    **Error:** `Not logged in`, `Authentication required`, or `Session expired`

    **Solutions:**

    1. Sign in again:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm login
    ```

    2. Verify the session:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm dashboard
    ```

    3. Run diagnostics:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm doctor
    ```
  </Accordion>

  <Accordion title="Session expired" icon="clock">
    **Error:** `Session expired` or `Token refresh failed`

    **Solution:** Sign in again:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm login
    ```

    OAuth tokens expire periodically. The CLI attempts automatic refresh, but if that fails, a fresh login is needed.
  </Accordion>

  <Accordion title="Login browser doesn't open" icon="globe">
    **Possible causes:**

    * No default browser configured
    * Running in a headless environment (SSH, Docker)

    **Solution:** Copy the URL printed in the terminal and open it manually in any browser. After authenticating, the CLI picks up the token automatically.
  </Accordion>
</AccordionGroup>

## Database Issues

<AccordionGroup>
  <Accordion title="Database locked" icon="lock">
    **Error:** `Database is locked` or `Could not set lock`

    **Cause:** Another `lm` process is holding the database lock.

    **Solutions:**

    1. Unlock the database:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm db unlock
    ```

    Or without confirmation:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm db unlock --yes
    ```

    2. If that doesn't work, check for orphaned processes:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    ps aux | grep lm
    ```
  </Accordion>

  <Accordion title="Database corruption" icon="triangle-exclamation">
    **Error:** `WAL corruption`, `schema mismatch`, or database errors.

    **Solutions:**

    1. **Repair** (preserves data when possible):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm db repair
    ```

    2. **Reset** (destructive — drops all tables):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm db reset --confirm
    ```

    Exported files in `.leadmagic/export/` are not affected by reset.
  </Accordion>

  <Accordion title="Database too large" icon="hard-drive">
    **Solution:** Compact the database to reclaim space:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm db vacuum
    ```

    This runs `VACUUM`, updates statistics, and flushes the write-ahead log.
  </Accordion>
</AccordionGroup>

## File and Data Issues

<AccordionGroup>
  <Accordion title="File too large" icon="file-exclamation">
    The CLI enforces row limits for safety:

    | Rows         | Behavior                         |
    | ------------ | -------------------------------- |
    | 1–5,000      | Normal processing                |
    | 5,001–10,000 | Warning prompt before processing |
    | 10,001+      | Hard stop — file is too large    |

    **Solutions:**

    * Split large files before loading
    * Filter rows using SQL after loading a subset
    * Use the REST API directly for large-scale batch processing
  </Accordion>

  <Accordion title="CSV parsing errors" icon="file-csv">
    **Common causes:**

    * Non-standard delimiters (the CLI auto-detects commas, tabs, semicolons, and pipes)
    * Encoding issues (the CLI handles UTF-8 and BOM)
    * Malformed quotes or escaped characters

    **Solutions:**

    1. Try analyzing the file first:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm analyze yourfile.csv
    ```

    2. Check the file encoding — the CLI works best with UTF-8.
    3. If the file uses an unusual delimiter, the CLI auto-detects it in most cases. If detection fails, pre-process the file to use standard CSV formatting.
  </Accordion>

  <Accordion title="Columns not detected" icon="table-columns">
    **Cause:** Column names don't match expected patterns (e.g., `email`, `first_name`, `company`).

    **Solutions:**

    * Specify columns explicitly with `--email-column`, `--first-name-column`, etc. when using `lm enrich`
    * In chat, tell the AI which column contains what: *"The email addresses are in column C"*
    * Run `lm analyze` to see what the CLI detected
  </Accordion>
</AccordionGroup>

## Connection Issues

<AccordionGroup>
  <Accordion title="API request failed" icon="wifi">
    **Possible causes:**

    * No internet connection
    * LeadMagic API is temporarily down
    * Your OAuth session is invalid or expired

    **Solutions:**

    1. Check your internet connection
    2. Verify your account session:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm dashboard
    ```

    3. Check the API status at [leadmagic.io/status](https://leadmagic.io/status)
  </Accordion>

  <Accordion title="AI chat not responding" icon="robot">
    **Cause:** The AI Gateway (`ai.leadmagic.io`) may be unreachable.

    **Solutions:**

    1. Check you're logged in:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm doctor
    ```

    2. Re-authenticate:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm login
    lm dashboard
    ```

    3. Try with debug logging to see the actual error:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    lm --debug chat
    ```
  </Accordion>
</AccordionGroup>

## Common Error Messages

| Error                     | Cause                                   | Solution                                                      |
| ------------------------- | --------------------------------------- | ------------------------------------------------------------- |
| `Not logged in`           | No local OAuth session                  | `lm login`                                                    |
| `Authentication required` | Command needs an account-backed session | `lm login`                                                    |
| `Session expired`         | OAuth token expired                     | `lm login`                                                    |
| `Database is locked`      | Another process holds the lock          | `lm db unlock`                                                |
| `File exceeds row limit`  | CSV has >10,000 rows                    | Split the file or use the API directly                        |
| `Insufficient credits`    | No credits remaining                    | [Purchase credits](https://app.leadmagic.io/settings/billing) |
| `Command not found: lm`   | CLI not in PATH                         | Open a new terminal or `source ~/.zshrc`                      |

## Reset Everything

If all else fails, you can reset your entire CLI installation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
lm db reset --confirm      # Reset the database
rm ~/.leadmagic/config.json # Remove config (keeps exports)
lm init                    # Re-initialize
lm login                   # Re-authenticate
```

<Warning>
  This preserves your exported files in `.leadmagic/export/` but removes all loaded data and configuration.
</Warning>

## Still Need Help?

<CardGroup>
  <Card title="Help Center" icon="life-ring" href="https://help.leadmagic.io/en">
    Contact support for account or billing issues.
  </Card>

  <Card title="API Status" icon="signal" href="https://leadmagic.io/status">
    Check if the LeadMagic API is operational.
  </Card>
</CardGroup>


# Authentication
Source: https://leadmagic.io/docs/mcp/authentication

OAuth authentication for the LeadMagic MCP server

The LeadMagic MCP server uses OAuth. Add `https://mcp.leadmagic.io/mcp` in a compatible AI client, then sign in when the client opens the LeadMagic authorization flow.

## How Authentication Works

Your AI client discovers the protected resource metadata from `mcp.leadmagic.io`, sends you through LeadMagic sign-in, and receives an access token for MCP tool calls.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://mcp.leadmagic.io/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
```

<CardGroup>
  <Card title="OAuth sign-in" icon="right-to-bracket">
    Your client sends you through a LeadMagic authorization flow.
  </Card>

  <Card title="Bearer tokens" icon="key">
    MCP requests use OAuth bearer tokens rather than copied API keys.
  </Card>

  <Card title="Credit-Based" icon="coins">
    Each tool call deducts credits from your account balance.
  </Card>
</CardGroup>

## Connect

<Steps>
  <Step title="Add the MCP server">
    Use `https://mcp.leadmagic.io/mcp` as the server URL in your AI client.
  </Step>

  <Step title="Authorize">
    Complete the LeadMagic sign-in flow when your AI client prompts you.
  </Step>

  <Step title="Test the connection">
    Ask your AI assistant to check your LeadMagic credits.
  </Step>
</Steps>

## Discovery metadata

<ResponseField name="Protected resource" type="URL">
  `https://mcp.leadmagic.io/.well-known/oauth-protected-resource`
</ResponseField>

<ResponseField name="Authorization server" type="URL">
  `https://mcp.leadmagic.io/.well-known/oauth-authorization-server`
</ResponseField>

<ResponseField name="MCP endpoint" type="URL">
  `https://mcp.leadmagic.io/mcp`
</ResponseField>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Do not paste OAuth secrets into docs or chat" icon="lock">
    OAuth client secrets are shown once when generated. If a secret is exposed, rotate it before using the integration.
  </Accordion>

  <Accordion title="Use the OAuth flow when available" icon="shield">
    Prefer clients that can complete OAuth for remote MCP servers. Avoid static token or header configurations unless your workspace explicitly requires them.
  </Accordion>

  <Accordion title="Revoke access if compromised" icon="arrows-rotate">
    If an OAuth client or token is exposed, revoke or rotate it from your LeadMagic app settings.
  </Accordion>

  <Accordion title="Monitor usage" icon="chart-line">
    Check your credit consumption regularly. Use `check_credit_balance` for balance checks, `get_account_analytics` for usage and rate-limit headroom, or visit your [dashboard](https://app.leadmagic.io).
  </Accordion>
</AccordionGroup>

## Authentication Errors

| Error              | Cause                           | Solution                                                                            |
| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid bearer token | Reconnect the MCP server and complete OAuth sign-in                                 |
| `403 Forbidden`    | No credits remaining            | [Purchase credits](https://app.leadmagic.io/settings/billing) or check your balance |
| `invalid_token`    | Token expired or revoked        | Reauthorize the MCP connection                                                      |

<Tip>
  Test your authentication by asking your AI assistant to "check my LeadMagic credits." The `check_credit_balance` tool is free and confirms your connection is working.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Setup Guide" icon="gear" href="/mcp/setup">
    Configure your MCP client.
  </Card>

  <Card title="Credits & Pricing" icon="coins" href="/v1/credits">
    Understand credit costs and manage your balance.
  </Card>
</CardGroup>


# LeadMagic MCP Server
Source: https://leadmagic.io/docs/mcp/introduction

Use LeadMagic enrichment, bulk jobs, analytics, and account intelligence directly inside AI assistants

# MCP Server <Badge>Beta</Badge>

The LeadMagic MCP server lets AI assistants call LeadMagic directly. Ask your AI to validate contacts, find emails, enrich companies, submit bulk jobs, check account analytics, or build an account brief - the assistant uses the right LeadMagic tool and returns the result in context.

<Warning>
  **Beta** — The MCP server is fully functional but still in beta. Tools, parameters, and behavior may change. We'd love your feedback — reach out at [support@leadmagic.io](mailto:support@leadmagic.io) or via the [Help Center](https://help.leadmagic.io/en).
</Warning>

<Note>
  **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI assistants use external tools. LeadMagic's MCP server exposes contact, company, jobs, bulk, analytics, and workflow tools that compatible AI clients can call.
</Note>

## What You Can Do

Ask your AI assistant questions like:

* *"Find the work email for Alex Rivera at Example Robotics"*
* *"Validate these 50 email addresses before my campaign"*
* *"What's the tech stack at example.com?"*
* *"Find and validate the CEO, CRO, and VP Sales at Example Robotics"*
* *"Open the upload widget and enrich this company list"*
* *"How much did I use today and am I close to my limits?"*
* *"Give me account intel on Example Robotics: funding, competitors, jobs, and tech stack"*

The AI calls the right LeadMagic tool automatically - no code, no API calls, no context switching.

## What The MCP Can Do

<Tabs>
  <Tab title="Contacts" icon="user">
    | Tool                             | What It Does                                                                         |
    | -------------------------------- | ------------------------------------------------------------------------------------ |
    | `validate_work_email`            | Verify deliverability before outreach                                                |
    | `find_work_email`                | Name + company/domain to work email                                                  |
    | `find_mobile_number`             | Profile/email to direct mobile                                                       |
    | `linkedin_profile_to_work_email` | Profile URL to work email                                                            |
    | `email_to_b2b_profile`           | Email to B2B profile URL                                                             |
    | `search_profile`                 | Profile URL to professional profile                                                  |
    | `find_personal_email`            | Profile URL to personal email                                                        |
    | `detect_job_change`              | Check whether a contact moved jobs                                                   |
    | `enrich_contact`                 | Composite dossier across validation, profile, personal email, mobile, and job change |
  </Tab>

  <Tab title="Company" icon="building">
    | Tool                         | What It Does                                                       |
    | ---------------------------- | ------------------------------------------------------------------ |
    | `enrich_company`             | Firmographics by domain, name, or LinkedIn URL                     |
    | `research_account`           | Concise company brief with firmographics and funding context       |
    | `find_company_funding`       | Funding rounds, investors, and financial context                   |
    | `list_company_competitors`   | Competitor and similar-company discovery                           |
    | `get_company_technographics` | Company technology stack                                           |
    | `find_company_employees`     | Employee lists by company/domain                                   |
    | `find_people_by_role`        | Role and title discovery                                           |
    | `find_decision_makers`       | Composite role search plus email discovery and validation          |
    | `account_intel`              | Composite account brief with research, competitors, tech, and jobs |
  </Tab>

  <Tab title="Bulk" icon="file-csv">
    | Tool                                        | What It Does                                                    |
    | ------------------------------------------- | --------------------------------------------------------------- |
    | `create_bulk_upload_session`                | Open the LeadMagic CSV upload widget                            |
    | `process_attached_csv`                      | Start the correct upload flow for attached CSV/JSON/JSONL files |
    | `submit_detected_bulk_job`                  | Submit a file after enrichment type and columns are detected    |
    | `submit_company_firmographics_bulk`         | Fast path for company list firmographics                        |
    | `submit_bulk_job`                           | Generic bulk submit for supported products                      |
    | `list_bulk_jobs`                            | List recent bulk jobs                                           |
    | `get_bulk_job_status`                       | Inspect status, queue, progress, and links                      |
    | `get_bulk_job_rows`                         | Read completed row output                                       |
    | `get_bulk_job_errors`                       | Read failed rows and row errors                                 |
    | `get_bulk_job_logs` / `get_bulk_job_events` | Debug queue, retry, progress, and completion events             |
  </Tab>

  <Tab title="Jobs & Account" icon="briefcase">
    | Tool                                               | What It Does                                                                                             |
    | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
    | `find_jobs`                                        | Search job postings by company, role, location, remote status, seniority, and recency                    |
    | `search_jobs`                                      | Advanced Jobs Search with v3 warehouse filters, vector, facets, deep mode, tags, and occupation taxonomy |
    | `resolve_job_search_filters`                       | Resolve company, tag, title, occupation taxonomy, and location filters before search                     |
    | `get_job_search_catalogs` / `get_job_search_stats` | Free jobs warehouse catalogs, dimensions, and freshness stats                                            |
    | `list_job_countries`                               | Supported job country codes                                                                              |
    | `list_job_types`                                   | Supported job types                                                                                      |
    | `list_job_company_types`                           | Supported company type filters                                                                           |
    | `list_job_industries`                              | Supported job industry filters                                                                           |
    | `list_job_regions`                                 | Supported job regions                                                                                    |
    | `check_credit_balance`                             | Credit balance                                                                                           |
    | `get_account_analytics`                            | Balance, rate-limit headroom, concurrency, usage, and top tools                                          |
    | `preview_cost`                                     | Free credit estimate before expensive or composite actions                                               |
  </Tab>
</Tabs>

<Tip>
  See the full [tool reference](/docs/mcp/tools) for tool categories, parameters, examples, cost behavior, resources, and prompts.
</Tip>

## Supported Clients

Works with any MCP client that supports Streamable HTTP transport — 13 clients and counting.

<CardGroup>
  <Card title="Cursor" icon="code" href="/mcp/setup">
    Native Streamable HTTP support.
  </Card>

  <Card title="VS Code / Copilot" icon="window" href="/mcp/setup">
    Secure input variables supported.
  </Card>

  <Card title="Claude Desktop" icon="message" href="/mcp/setup">
    Via `mcp-remote` proxy.
  </Card>

  <Card title="Claude Code" icon="terminal" href="/mcp/setup">
    One CLI command to add.
  </Card>

  <Card title="Windsurf" icon="wind" href="/mcp/setup">
    Native Streamable HTTP.
  </Card>

  <Card title="Zed" icon="code" href="/mcp/setup#more-clients">
    Via `mcp-remote` proxy.
  </Card>

  <Card title="Cline" icon="puzzle-piece" href="/mcp/setup#more-clients">
    Remote URL with OAuth.
  </Card>

  <Card title="Roo Code" icon="code-branch" href="/mcp/setup#more-clients">
    Project or global config.
  </Card>

  <Card title="OpenCode" icon="laptop-code" href="/mcp/setup#more-clients">
    Remote type with OAuth.
  </Card>

  <Card title="Gemini CLI" icon="wand-magic-sparkles" href="/mcp/setup#more-clients">
    CLI or settings.json.
  </Card>

  <Card title="JetBrains IDEs" icon="laptop" href="/mcp/setup#more-clients">
    IntelliJ, WebStorm, PyCharm, etc.
  </Card>

  <Card title="Amazon Q" icon="cloud" href="/mcp/setup#more-clients">
    HTTP transport in IDE or CLI.
  </Card>

  <Card title="Copilot Agent" icon="github" href="/mcp/setup#more-clients">
    GitHub coding agent.
  </Card>
</CardGroup>

## How It Works

1. You add the LeadMagic MCP server URL to your AI client
2. Your client opens the LeadMagic OAuth sign-in flow
3. The AI discovers the available LeadMagic tools automatically
4. When you ask a question, the AI calls the right tool with the right parameters
5. LeadMagic returns structured data, and the AI presents it in context

For bulk files, the MCP can open an upload widget, map columns, submit jobs, poll progress, inspect failures, and fetch completed rows. For account operations, it can estimate credit usage, check credits, and read analytics before running expensive work.

The server runs at `https://mcp.leadmagic.io/mcp` using the Streamable HTTP transport. Claude remote connectors should use `https://mcp.leadmagic.io`.

## Get Started

<CardGroup>
  <Card title="Setup Guide" icon="gear" href="/mcp/setup">
    Step-by-step setup for Cursor, VS Code, Claude, and Windsurf.
  </Card>

  <Card title="Tool Reference" icon="wrench" href="/mcp/tools">
    All MCP tools with parameters, cost notes, resources, and prompts.
  </Card>

  <Card title="Authentication" icon="key" href="/mcp/authentication">
    OAuth setup and troubleshooting.
  </Card>

  <Card title="Troubleshooting" icon="circle-question" href="/mcp/troubleshooting">
    Common issues and how to fix them.
  </Card>
</CardGroup>


# Setup
Source: https://leadmagic.io/docs/mcp/setup

Connect LeadMagic MCP with OAuth in Cursor, Claude, ChatGPT, VS Code, and other MCP clients

Connect LeadMagic MCP by adding the hosted server URL to your AI client. OAuth-capable clients will open a LeadMagic sign-in flow and store the resulting token for future tool calls.

<Note>
  The hosted MCP server runs at `https://mcp.leadmagic.io/mcp` using Streamable HTTP. Do not paste OAuth client secrets into config files, source code, docs, or chats.
</Note>

## Server URLs

| Use case                    | URL                                                             |
| --------------------------- | --------------------------------------------------------------- |
| Most MCP clients            | `https://mcp.leadmagic.io/mcp`                                  |
| Claude remote connector     | `https://mcp.leadmagic.io`                                      |
| Server catalog              | `https://mcp.leadmagic.io/`                                     |
| Protected resource metadata | `https://mcp.leadmagic.io/.well-known/oauth-protected-resource` |

## Setup flow

<Steps>
  <Step title="Add the server URL">
    In your AI client, add `https://mcp.leadmagic.io/mcp` as a remote MCP server. For Claude remote connectors, use `https://mcp.leadmagic.io`.
  </Step>

  <Step title="Complete OAuth sign-in">
    When your client prompts you, sign in with LeadMagic and approve the connection.
  </Step>

  <Step title="Test the connection">
    Ask your AI assistant to check your LeadMagic credits. The `check_credit_balance` tool is free.
  </Step>
</Steps>

## Client notes

<AccordionGroup>
  <Accordion title="Cursor" icon="code">
    Add a remote MCP server using `https://mcp.leadmagic.io/mcp`. If Cursor opens a browser sign-in flow, complete the OAuth authorization and restart Cursor if needed.
  </Accordion>

  <Accordion title="Claude" icon="message">
    For Claude remote connectors, use the origin URL `https://mcp.leadmagic.io`. The MCP worker also accepts `POST /mcp` for clients that require a path-scoped endpoint.
  </Accordion>

  <Accordion title="ChatGPT" icon="comment">
    ChatGPT-compatible MCP setup should use OAuth. Add the remote server URL and complete the LeadMagic sign-in flow when prompted.
  </Accordion>

  <Accordion title="VS Code and Copilot" icon="window">
    Use the remote HTTP MCP server URL `https://mcp.leadmagic.io/mcp` when your client supports OAuth for remote MCP servers.
  </Accordion>

  <Accordion title="Other MCP clients" icon="plug">
    Use `https://mcp.leadmagic.io/mcp` with Streamable HTTP. If your client does not support OAuth for remote MCP servers, use a supported client or the REST API.
  </Accordion>
</AccordionGroup>

## Verify the connection

After setup, ask:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Check my LeadMagic credit balance
```

If the server is connected, your assistant will call `check_credit_balance` and return your current balance.

## Next steps

<CardGroup>
  <Card title="Tool reference" icon="wrench" href="/mcp/tools">
    See all MCP tools with parameters and example prompts.
  </Card>

  <Card title="Authentication" icon="key" href="/mcp/authentication">
    Learn how OAuth works for LeadMagic MCP.
  </Card>
</CardGroup>


# Tools, Resources & Prompts
Source: https://leadmagic.io/docs/mcp/tools

Complete reference for LeadMagic MCP tools, resources, prompts, bulk workflows, analytics, and cost controls

The LeadMagic MCP server exposes contact, company, jobs, bulk, account, and composite workflow tools to compatible AI assistants. Tools are read-only unless they submit a bulk job or open an upload workflow.

<Tip>
  Estimate credits with `preview_cost` before expensive composite work, and use `check_credit_balance` or `get_account_analytics` before large bulk jobs.
</Tip>

## Cost And Safety Model

| Pattern          | What to expect                                                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| Single lookups   | Charged only when the underlying LeadMagic product returns data, unless noted otherwise              |
| Email validation | 0.25 credits per validation                                                                          |
| Jobs             | 1 credit per job returned; job company autocomplete is 1 credit per request                          |
| Bulk jobs        | Charged asynchronously per processed row and product                                                 |
| Free tools       | Credit checks, credit estimates, analytics reads, most job filter lists, and many no-result outcomes |
| Composite tools  | Chain multiple lookups; estimate cost with `preview_cost` before large runs                          |

## Contact Tools

| Tool                             | Use it for                                 | Key inputs                                                    | Cost behavior                           |
| -------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | --------------------------------------- |
| `validate_work_email`            | Email deliverability before outreach       | `email`                                                       | 0.25 credits per validation             |
| `find_work_email`                | Work email discovery from person + company | `first_name`, `last_name`, `company_domain` or `company_name` | 1 credit per lookup                     |
| `find_mobile_number`             | Direct mobile lookup                       | `profile_url`, `work_email`, or `personal_email`              | 5 credits when found, free if no match  |
| `linkedin_profile_to_work_email` | Profile URL to work email                  | `profile_url`, optional name/company hints                    | 1 credit per lookup                     |
| `email_to_b2b_profile`           | Email to LinkedIn/B2B profile URL          | `work_email` or `personal_email`                              | 10 credits when found, free if no match |
| `search_profile`                 | Full professional profile                  | `profile_url`                                                 | 2 credits when found, free if no match  |
| `find_personal_email`            | Personal email fallback                    | `profile_url`                                                 | 2 credits when found, free if no match  |
| `detect_job_change`              | Employment-change detection                | `profile_url` or `work_email`, plus company hint when needed  | 1 credit per check                      |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Validate alex.rivera@example.com before I send outreach.
Find the work email for Alex Rivera at example.com.
Get the mobile number for this LinkedIn profile.
Has alex.rivera@example.com moved jobs?
```

## Company And Account Tools

| Tool                         | Use it for                                                 | Key inputs                                                       | Cost behavior                  |
| ---------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------ |
| `enrich_company`             | Single-company firmographics                               | `company_domain`, `company_name`, or `profile_url`               | 1 credit per match             |
| `research_account`           | Concise company brief with funding context                 | `company_domain` or `company_name`                               | 2 credits per account          |
| `find_company_funding`       | Funding rounds, investors, last round, and revenue context | `company_domain` or `company_name`                               | 4 credits when data exists     |
| `list_company_competitors`   | Competitors and similar companies                          | `company_domain`, `company_url`, or `company_name`               | 5 credits when found           |
| `get_company_technographics` | Technology stack and vendor signals                        | `company_name`, optional `company_domain`                        | 1 credit when signals exist    |
| `find_people_by_role`        | One role or title at a company                             | `company_name`, optional `job_title`, `location`                 | 1 credit per match             |
| `find_company_employees`     | Broad employee discovery                                   | `company_domain` or `company_name`, optional `location`, `limit` | 1 credit per employee returned |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Give me firmographics for example.com.
Who competes with Example Robotics?
What technology stack does Example Robotics use?
Find the VP Sales at Example Robotics.
List 25 employees at example.com.
```

## Composite Tools

Composite tools chain multiple LeadMagic calls server-side so the assistant can produce a richer answer in one step.

| Tool                   | What it chains                                                     | Best for                                       | Cost controls                                                                     |
| ---------------------- | ------------------------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------- |
| `find_decision_makers` | Role search, work email discovery, and validation                  | Finding executives or buying committee members | `titles` max 5, `include_email_discovery`, `include_validation`, `validate_limit` |
| `account_intel`        | Company research, competitors, technographics, and jobs            | Account prep and GTM research                  | `include_*` flags, `jobs_limit`, `jobs_per_page`                                  |
| `enrich_contact`       | Validation, profile lookup, personal email, mobile, and job change | Full contact dossier                           | `include_*` flags, `auto_resolve_profile`                                         |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Find and validate the CEO, CRO, and Head of RevOps at Example Robotics.
Give me account intel on Example Robotics, but limit jobs to 5.
Enrich alex.rivera@example.com but skip mobile lookup.
```

## Jobs Tools

| Tool                             | Use it for                                                                        | Inputs                                                                                                                                                                          | Cost                             |
| -------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `find_jobs`                      | Search open jobs and hiring intent                                                | `company_name`, `company_website`, `job_title`, `job_description`, `experience_level`, `has_remote`, `location`, `city_name`, `country_id`, `posted_within`, `page`, `per_page` | 1 credit per returned job        |
| `search_jobs`                    | Advanced Jobs Search with v3 warehouse filters                                    | `titles`, `company_domains`, `countries`, `occupation_level*`, `tags`, `vector`, `include_facets`, `mode`, `limit`                                                              | 1 credit per returned job signal |
| `resolve_job_search_filters`     | Resolve companies, tags, titles, occupation taxonomy, and countries before search | `company_domains`, `tags`, `occupation_level*`, `titles`, `countries`                                                                                                           | 1 credit per request             |
| `search_job_companies`           | Autocomplete job company filters                                                  | `q`, `domain`, `limit`                                                                                                                                                          | 1 credit per request             |
| `search_job_tags`                | Autocomplete jobs tags/tools/skills                                               | `q`, `tag_type`, `limit`                                                                                                                                                        | Free                             |
| `search_job_titles`              | Autocomplete normalized job titles                                                | `q`, `limit`                                                                                                                                                                    | Free                             |
| `search_job_occupation_taxonomy` | Autocomplete occupation taxonomy levels                                           | `q`, `level`, `limit`                                                                                                                                                           | Free                             |
| `search_job_locations`           | Autocomplete countries, regions, states, and cities                               | `q`, `type`, `limit`                                                                                                                                                            | Free                             |
| `get_job_search_catalogs`        | Fetch job filter catalogs                                                         | none                                                                                                                                                                            | Free                             |
| `get_job_search_stats`           | Fetch jobs warehouse freshness and dimension counts                               | none                                                                                                                                                                            | Free                             |
| `list_job_countries`             | Resolve supported country filters                                                 | none                                                                                                                                                                            | Free                             |
| `list_job_types`                 | See supported job type filters                                                    | none                                                                                                                                                                            | Free                             |
| `list_job_company_types`         | See company type filters                                                          | none                                                                                                                                                                            | Free                             |
| `list_job_industries`            | See supported industry filters                                                    | none                                                                                                                                                                            | Free                             |
| `list_job_regions`               | See supported region filters                                                      | none                                                                                                                                                                            | Free                             |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Find senior remote engineering jobs at Example Robotics posted in the last 30 days.
Search jobs for DevOps engineers in the US using occupation taxonomy and tags.
Resolve job search filters for Example Robotics, Kubernetes, and DevOps.
Which countries can I use as job filters?
Show job industries supported by LeadMagic.
```

## Bulk Tools

Use bulk tools for lists, uploaded files, and multi-row work. The assistant should not loop single-record tools across a CSV.

| Tool                                | Use it for                                                                |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `create_bulk_upload_session`        | Open the LeadMagic upload widget for CSV/JSON/JSONL files                 |
| `process_attached_csv`              | Route an attached file into the upload widget with the right enrichment   |
| `resolve_bulk_upload_mapping`       | Widget-internal column mapping helper                                     |
| `submit_company_firmographics_bulk` | Company firmographics bulk jobs with domain/name mapping                  |
| `submit_detected_bulk_job`          | Bulk jobs after enrichment type and columns are detected                  |
| `submit_bulk_job`                   | Generic bulk submit with explicit endpoint, product, and input mapping    |
| `list_bulk_jobs`                    | List recent jobs with optional status/product filters                     |
| `get_bulk_job_status`               | Check queue position, throttling/backoff, progress, completion, and links |
| `get_bulk_job_rows`                 | Read paginated result rows                                                |
| `get_bulk_job_errors`               | Read failed rows and error messages                                       |
| `get_bulk_job_logs`                 | Read recent worker logs                                                   |
| `get_bulk_job_events`               | Read worker event history                                                 |

Supported detected bulk enrichments:

| Enrichment               | Typical columns                                      |
| ------------------------ | ---------------------------------------------------- |
| `company_firmographics`  | `domain`, `company`, `name`, `website`               |
| `company_technographics` | `company`, `domain`                                  |
| `company_competitors`    | `company`, `domain`, `linkedin_url`                  |
| `company_jobs`           | `company`, `domain`                                  |
| `company_funding`        | `company`, `domain`                                  |
| `email_validation`       | `email`, `work_email`, `business_email`              |
| `work_email_finder`      | `first_name`, `last_name`, `domain`, `company`       |
| `linkedin_to_email`      | `profile_url`, `linkedin_url`                        |
| `mobile_finder`          | `email`, `work_email`, `profile_url`, `linkedin_url` |
| `job_change`             | `email`, `profile_url`, `domain`, `company`          |
| `employee_finder`        | `company`, `domain`                                  |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Open the upload widget so I can enrich a company list.
This CSV has first name, last name, and domain columns. Find work emails in bulk.
Check the status of bulk job job_123.
Show failed rows for that bulk job.
```

## Account Tools

| Tool                    | Use it for                                                                                                              | Cost |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---- |
| `check_credit_balance`  | Current credit balance                                                                                                  | Free |
| `get_account_analytics` | Credit balance, rate-limit headroom, concurrency, calls, credits used, average cost, and top tools for today/week/month | Free |
| `preview_cost`          | Credit estimate for any MCP tool, including composite workflows                                                         | Free |

Example prompts:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
How many credits do I have left?
Show usage today and rate-limit headroom.
Estimate the cost of account_intel for 10 jobs before running it.
```

## Resources

| Resource                    | URI                | Type            | Description                                                          |
| --------------------------- | ------------------ | --------------- | -------------------------------------------------------------------- |
| LeadMagic API Documentation | `leadmagic://docs` | `text/markdown` | Credit costs, rate limits, best practices, and API reference context |

AI clients can read this resource to understand parameter preferences, cost behavior, and credit-saving patterns.

## Prompts

The server provides built-in prompts for common workflows.

| Prompt             | Use it for                                                         | Arguments                                                            |
| ------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `account_research` | Research a single company and summarize GTM signals                | `company_domain`, `company_name`                                     |
| `contact_lookup`   | Find or validate a work email, with bulk-file guidance when needed | `first_name`, `last_name`, `company_domain`, `company_name`, `email` |

## Recommended Tool Selection

| User asks for            | Prefer                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------- |
| One email validation     | `validate_work_email`                                                               |
| One work email           | `find_work_email` or `linkedin_profile_to_work_email`                               |
| One full contact dossier | `enrich_contact`                                                                    |
| Executives at an account | `find_decision_makers`                                                              |
| One company profile      | `enrich_company`                                                                    |
| Full account prep        | `account_intel`                                                                     |
| A CSV or list            | `process_attached_csv`, `create_bulk_upload_session`, or `submit_detected_bulk_job` |
| Job postings             | `find_jobs`                                                                         |
| Credit usage or limits   | `get_account_analytics`                                                             |
| Cost estimate            | `preview_cost`                                                                      |


# Troubleshooting
Source: https://leadmagic.io/docs/mcp/troubleshooting

Common issues and solutions for the LeadMagic MCP server

Common issues and solutions for the LeadMagic MCP server.

## Quick Diagnostics

Ask your AI assistant: *"Check my LeadMagic credit balance."*

* **Works?** Your connection and authentication are fine.
* **Doesn't work?** Follow the troubleshooting steps below.

## Connection Issues

<AccordionGroup>
  <Accordion title="Server not found or tools not appearing" icon="plug">
    **Symptoms:** AI assistant doesn't recognize LeadMagic tools, "no tools available," or server appears disconnected.

    **Solutions:**

    1. **Verify the URL** — ensure your config uses exactly `https://mcp.leadmagic.io/mcp` (note the `/mcp` path).
    2. **Restart your client** — most MCP clients require a restart after config changes:
       * **Cursor:** Restart the application
       * **VS Code:** Run `Developer: Reload Window`
       * **Claude Desktop:** Fully quit and reopen
       * **Windsurf:** Restart the application
    3. **Check JSON syntax** — a missing comma or bracket in your config file will silently fail. Validate your JSON at [jsonlint.com](https://jsonlint.com).
    4. **Check the config file location** — make sure you're editing the right file for your client (see [setup guide](/docs/mcp/setup)).
  </Accordion>

  <Accordion title="Connection timeout or slow responses" icon="clock">
    **Symptoms:** Tools take a long time to respond or time out entirely.

    **Solutions:**

    1. **Check your internet connection** — the MCP server runs at `mcp.leadmagic.io` and requires internet access.
    2. **Try the health endpoint** — run this in your terminal to verify the server is reachable:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl https://mcp.leadmagic.io/health
    ```

    You should see `{"ok":true,"service":"lm-mcp",...}`.

    3. **Rate limits** — the LeadMagic API has rate limits. If you're making many rapid requests, you may be temporarily throttled.
  </Accordion>
</AccordionGroup>

## Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    **Cause:** Missing, expired, or revoked OAuth bearer token.

    **Solutions:**

    1. **Reconnect the server** — remove and re-add the MCP server in your AI client.
    2. **Complete OAuth sign-in** — sign in when the client opens the LeadMagic authorization flow.
    3. **Check the server URL** — use `https://mcp.leadmagic.io/mcp` for most clients and `https://mcp.leadmagic.io` for Claude remote connectors.
    4. **Retry after refresh** — some clients need a restart after completing OAuth.
  </Accordion>

  <Accordion title="403 Forbidden — No credits" icon="coins">
    **Cause:** Your account has no remaining credits.

    **Solutions:**

    1. Check your balance at [app.leadmagic.io](https://app.leadmagic.io).
    2. [Purchase credits](https://app.leadmagic.io/settings/billing) or set up auto top-up.
    3. See [Credits & Pricing](/docs/v1/credits) for plan options.
  </Accordion>
</AccordionGroup>

## Client-Specific Issues

<Tabs>
  <Tab title="Cursor">
    ### Cursor

    **Config not picked up:**

    * Ensure the file is at `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
    * Restart Cursor after any config change.

    **Multiple configs:**

    * Project-level config (`.cursor/mcp.json`) takes priority over global (`~/.cursor/mcp.json`).
    * If you have both, the project-level config wins.
  </Tab>

  <Tab title="VS Code">
    ### VS Code

    **Config not picked up:**

    * Ensure the file is at `.vscode/mcp.json` in your workspace root.
    * Run `Developer: Reload Window` after changes.

    **Input variable prompt not appearing:**

    * Make sure the `inputs` array is at the top level of your `mcp.json`, not nested inside `servers`.
    * The prompt appears when the MCP server first connects in a session.
  </Tab>

  <Tab title="Claude Desktop">
    ### Claude Desktop

    **`mcp-remote` not found:**

    * Ensure Node.js 18+ is installed (`node --version`).
    * `npx` should be available in your PATH. Try running `npx mcp-remote --help` in your terminal.

    **Server keeps disconnecting:**

    * `mcp-remote` spawns a local process per session. If Claude Desktop crashes or is force-quit, the process may linger. Check for orphaned `mcp-remote` processes.
    * Update `mcp-remote` to the latest version: `npx mcp-remote@latest`.

    **Config file location:**

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux:** `~/.config/Claude/claude_desktop_config.json`
  </Tab>

  <Tab title="Claude Code">
    ### Claude Code

    **Server not appearing:**

    * Run `claude mcp list` to see registered servers.
    * If `leadmagic` is not listed, re-run the add command (see [setup guide](/docs/mcp/setup)).

    **Wrong scope:**

    * `--scope local` (default) only applies to the current project directory.
    * Use `--scope user` to make LeadMagic available everywhere.
  </Tab>

  <Tab title="Windsurf">
    ### Windsurf

    **Config not picked up:**

    * The config file location may vary by Windsurf version. Try both `~/.codeium/mcp_config.json` and `~/.codeium/windsurf/mcp_config.json`.
    * Restart Windsurf after changes.

    **Env var interpolation:**

    * Use `"${env:LEADMAGIC_API_KEY}"` syntax. Make sure the environment variable is set in your shell profile, not just the current session.
  </Tab>
</Tabs>

## Tool Errors

<AccordionGroup>
  <Accordion title="Tool returns an error response" icon="triangle-exclamation">
    MCP tool errors are returned as `isError: true` with a message. Common causes:

    * **Missing required parameters** — check the [tool reference](/docs/mcp/tools) for required fields.
    * **Invalid parameter format** — emails must be valid format, LinkedIn URLs must be full URLs (e.g., `https://linkedin.com/in/username`).
    * **API rate limit** — wait a moment and try again.
  </Accordion>

  <Accordion title="No data found" icon="magnifying-glass">
    A `not_found` result means LeadMagic doesn't have data for that query. This is **free** — no credits are charged.

    **Tips to improve results:**

    * Use `domain` instead of `company_name` for company lookups.
    * Use LinkedIn profile URLs when available — they're the most reliable identifier.
    * For `find_work_email`, provide both first and last name plus the company domain.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Is my OAuth token stored on the server?" icon="shield">
    The hosted MCP server uses OAuth bearer tokens for supported clients. Do not paste OAuth client secrets or access tokens into source code, docs, or chats.
  </Accordion>

  <Accordion title="Can multiple team members use the same key?" icon="users">
    Yes, but each person using the key consumes credits from the same account. For team usage, consider using separate keys or an organization account with shared credits.
  </Accordion>

  <Accordion title="What's the difference between MCP and the REST API?" icon="code">
    They use the same underlying API. The MCP server wraps each API endpoint as an MCP tool so AI assistants can call them directly. Credit costs are identical. If you need programmatic access from your own code, use the [REST API](/docs/v1/reference/introduction) directly.
  </Accordion>

  <Accordion title="Does the MCP server support SSE transport?" icon="signal-stream">
    No. The server uses **Streamable HTTP** transport only (MCP 2025 spec). There is no SSE endpoint. Most supported clients work with Streamable HTTP natively. Claude Desktop and Zed use `mcp-remote` to bridge the transport.
  </Accordion>

  <Accordion title="Can I use this with ChatGPT?" icon="comment">
    Yes, use the OAuth-capable remote MCP setup in ChatGPT and connect to `https://mcp.leadmagic.io/mcp`.
  </Accordion>
</AccordionGroup>

## Still Need Help?

<CardGroup>
  <Card title="Help Center" icon="life-ring" href="https://help.leadmagic.io/en">
    Contact support for account or billing issues.
  </Card>

  <Card title="API Reference" icon="code" href="/v1/reference/introduction">
    Full REST API documentation with interactive playground.
  </Card>
</CardGroup>


# Authentication
Source: https://leadmagic.io/docs/v1/authentication

Secure your API requests with API key authentication

The LeadMagic API uses **API key authentication** to secure all requests. Your API key must be included in the header of every request.

## Getting Your API Key

<Steps>
  <Step title="Log in to LeadMagic">
    Visit [app.leadmagic.io](https://app.leadmagic.io/sign-in) and sign in to
    your account.
  </Step>

  <Step title="Navigate to Account Settings">
    Click on your profile icon and select "Account Profile" or "API Keys".
  </Step>

  <Step title="Copy your API Key">
    Your API key will be displayed. Click to copy it to your clipboard.

    <Warning>
      Treat your API key like a password. Never share it publicly.
    </Warning>
  </Step>
</Steps>

## Using Your API Key

Include your API key in the `X-API-Key` header of every request:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.leadmagic.io/v1/people/email-validation",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.LEADMAGIC_API_KEY,
      },
      body: JSON.stringify({ email: "test@example.com" }),
    },
  );
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/email-validation',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': os.environ['LEADMAGIC_API_KEY']
      },
      json={'email': 'test@example.com'}
  )
  ```
</CodeGroup>

## Authentication Errors

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/invalid_api_key",
      "title": "Invalid API key. The key does not exist or is incorrect.",
      "status": 401,
      "code": "invalid_api_key"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-05T12:00:00.000Z"
  }
}
```

<AccordionGroup>
  <Accordion title="Common authentication issues" icon="circle-exclamation">
    | Issue                 | Solution                                                        |
    | --------------------- | --------------------------------------------------------------- |
    | Missing header        | Ensure `X-API-Key` header is included                           |
    | Header name variation | Header names are case-insensitive; use `X-API-Key` as canonical |
    | Invalid key           | Verify your key in the dashboard                                |
    | Expired key           | Regenerate your API key                                         |
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup>
  <Card title="Use Environment Variables" icon="terminal">
    Store your API key in environment variables, not in your code.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export LEADMAGIC_API_KEY="your_key_here"
    ```
  </Card>

  <Card title="Server-Side Only" icon="server">
    Never expose your API key in client-side JavaScript or mobile apps.
  </Card>

  <Card title="Use Secrets Managers" icon="vault">
    For production, use AWS Secrets Manager, HashiCorp Vault, or similar.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Regenerate your API key periodically and if you suspect compromise.
  </Card>
</CardGroup>

<Warning>
  **When team members leave:** Always regenerate your API key when employees with access leave your organization. This prevents unauthorized access.
</Warning>

## Checking Your Credits

<Tip>
  See the [Credits & Pricing](/docs/v1/credits) page for details on monitoring your balance, the [Check Credits endpoint](/docs/v1/reference/check-credits), and subscription plans.
</Tip>

## Regenerating Your API Key

If you need to regenerate your API key:

<Steps>
  <Step title="Go to Account Settings">
    Navigate to your Account Profile in the LeadMagic dashboard.
  </Step>

  <Step title="Click Regenerate">
    Find the API Key section and click "Regenerate Key".
  </Step>

  <Step title="Update your applications">
    Replace the old key in all your applications with the new one.

    <Warning>
      The old key will stop working immediately after regeneration.
    </Warning>
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Making API Calls" icon="code" href="/v1/making-api-calls">
    Learn the basics of making requests to our API.
  </Card>

  <Card title="Email Validation" icon="envelope-circle-check" href="/v1/reference/email-validation">
    Try our most popular endpoint.
  </Card>
</CardGroup>


# Credits & Pricing
Source: https://leadmagic.io/docs/v1/credits

Understand how LeadMagic credits work and optimize your usage

LeadMagic uses a flexible credit-based system that gives you control over how you use our data enrichment services. Credits function as a flexible currency that can be used across all our enrichment services.

<Note>
  **Try before you buy** - Test any endpoint in our [API
  Playground](/docs/v1/reference/email-validation) to see exactly what you get before
  using credits.
</Note>

## How Credits Work

<CardGroup>
  <Card title="Pay for Success" icon="check">
    Credits are only deducted when enrichment is successful
  </Card>

  <Card title="Flexible Usage" icon="arrows-rotate">
    Use credits across all enrichment services based on your needs
  </Card>

  <Card title="Team Sharing" icon="users">
    Share credits across team members within your organization
  </Card>
</CardGroup>

## Credit Costs by Service

<Tabs>
  <Tab title="Email & Validation" icon="envelope">
    | Service               | Credits | What You Get             |
    | --------------------- | ------- | ------------------------ |
    | **Email Validation**  | 1       | **4 validations**        |
    | Email Finder          | 1       | 1 email found            |
    | Personal Email Finder | 2       | 1 personal email         |
    | Profile to Email      | 5       | 1 email from profile URL |

    <Check>
      **Best Value**: Email Validation uses 0.25 credits per email (4 validations per credit). On higher tiers, per-validation cost drops to about **half a cent** or less.
    </Check>
  </Tab>

  <Tab title="Mobile & Profiles" icon="phone">
    | Service             | Credits | What You Get                         |
    | ------------------- | ------- | ------------------------------------ |
    | Profile Search      | 1       | 1 full profile                       |
    | **People Search**   | 1+      | Search employees and decision-makers |
    | Role Finder         | 2       | 1 role at company                    |
    | **Mobile Finder**   | 5       | 1 mobile number                      |
    | Email to Profile    | 10      | 1 complete profile                   |
    | Job Change Detector | 3       | 1 job change check                   |

    <Tip>
      Mobile numbers are premium data - verify your contact list first with
      Email Validation to maximize ROI.
    </Tip>
  </Tab>

  <Tab title="Company Data" icon="building">
    | Service           | Credits | What You Get         |
    | ----------------- | ------- | -------------------- |
    | Company Search    | 1       | 1 returned company   |
    | Technographics    | 1       | Tech stack data      |
    | Company Funding   | 4       | Funding history      |
    | Company Lookalike | 5       | Similar company list |
  </Tab>

  <Tab title="Ads Intelligence" icon="rectangle-ad">
    | Service           | Credits | What You Get      |
    | ----------------- | ------- | ----------------- |
    | Google Ads Search | 1       | **5 ad lookups**  |
    | Meta Ads Search   | 1       | **5 ad lookups**  |
    | B2B Ads Search    | 1       | **5 ad lookups**  |
    | B2B Ad Details    | 2       | Full ad breakdown |
  </Tab>
</Tabs>

## What's Free?

<CardGroup>
  <Card title="Email Validation" icon="gift">
    **Free for inconclusive results**

    * `unknown` — could not determine email validity

    You only pay for definitive results: `valid` and `invalid`.
  </Card>

  <Card title="All Other Endpoints" icon="circle-xmark">
    **No Charge when nothing found**

    Email Finder only charges 1 credit when a `valid` email is returned. `null` results are free. Other endpoints follow the same pattern — `not_found` results are always free.
  </Card>
</CardGroup>

## Subscription Plans

| Plan             | Credits/mo | Price | Per Credit | Best For          |
| ---------------- | ---------- | ----- | ---------- | ----------------- |
| **Trial**        | 100        | Free  | —          | Try the API       |
| **Basic**        | 2,000      | \$49  | \$0.0245   | Individuals       |
| **Essential**    | 5,000      | \$99  | \$0.0198   | Small teams       |
| **Growth**       | 20,000     | \$249 | \$0.01245  | Growing companies |
| **Professional** | 50,000     | \$499 | \$0.00998  | Agencies          |
| **Ultimate**     | 100,000    | \$849 | \$0.00849  | High volume       |

<AccordionGroup>
  <Accordion title="What's Included" icon="check">
    **All plans include:**

    * Access to all API endpoints
    * API Playground access
    * Priority support
    * Usage analytics

    **Essential plan and above:**

    * Credit rollover (unused credits carry forward)
    * Team organization (5 members)
    * Shared credit pools
  </Accordion>

  <Accordion title="Credit Rollover" icon="rotate">
    On **Essential plan and above**, unused credits roll over to the next month.

    * Credits accumulate month-over-month
    * No "use it or lose it" pressure
    * Plan with confidence

    <Note>Basic plan credits expire at the end of each billing cycle.</Note>
  </Accordion>
</AccordionGroup>

## Managing Your Credits

### Check Your Balance

Use the [Check Credits endpoint](/docs/v1/reference/check-credits) to monitor your balance programmatically:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET 'https://api.leadmagic.io/v1/credits' \
  -H 'X-API-Key: YOUR_API_KEY'
```

### Dashboard View

Your current usage statistics are displayed on the main dashboard in the top left of the display. For detailed reports:

1. Go to **Settings > Credit History**
2. View detailed reports on credits consumed and API usage

### Auto Top-Up

Never run out mid-enrichment:

<Steps>
  <Step title="Go to Settings">
    Navigate to [Settings > Billing](https://app.leadmagic.io/settings/billing) in your dashboard.
  </Step>

  <Step title="Enable Auto Top-Up">
    Set a threshold (e.g., 500 credits) and purchase amount.
  </Step>

  <Step title="Relax">
    Credits are automatically purchased when your balance drops below the threshold.
  </Step>
</Steps>

### Manual Top-Up

Need credits immediately?

1. Go to [Settings > Billing](https://app.leadmagic.io/settings/billing)
2. Click "Purchase Credits"
3. Select a credit package
4. Complete payment - credits are added instantly

## Optimize Your Credit Usage

<AccordionGroup>
  <Accordion title="Validate First, Enrich Later" icon="filter">
    **Save 80%+ on wasted credits**

    Before running expensive enrichments (mobile finder, full profiles), validate your email list:

    1. Run Email Validation (4 per credit)
    2. Filter for `valid` results only
    3. Then run premium enrichments on verified contacts

    This prevents spending credits on invalid contacts.
  </Accordion>

  <Accordion title="Use Conditional Logic" icon="code-branch">
    In your code or Clay workflows, only enrich when conditions are met:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // Only find mobile for VPs and above
    if (contact.title.includes('VP') || contact.title.includes('Director')) {
      await findMobile(contact.linkedin_url);
    }
    ```
  </Accordion>

  <Accordion title="Batch Your Requests" icon="layer-group">
    Process records in batches rather than one-by-one:

    * Reduce API overhead
    * Handle errors gracefully
    * Monitor credit consumption per batch
    * Stop early if results are poor
  </Accordion>

  <Accordion title="Prioritize by Value" icon="ranking-star">
    Focus expensive enrichments on high-value prospects:

    1. Score leads by ICP fit
    2. Enrich top-tier leads first
    3. Use cheaper validation for lower tiers
    4. Re-evaluate before scaling
  </Accordion>
</AccordionGroup>

## Team Credit Management

<Info>Available on Essential plan and above.</Info>

### Share Credits Across Your Team

1. Click your name in the top left
2. Switch from "Personal Account" to your organization
3. Go to Settings > Team
4. Use the three dots next to each member to allocate credits

### Track Team Usage

Monitor which team members consume the most credits:

1. Go to Settings > Usage & Billing
2. Review the Credit Usage Report
3. Identify high-consumption activities
4. Adjust allocations as needed

## Billing & Payments

### Payment Methods

LeadMagic accepts:

<CardGroup>
  <Card title="Visa" icon="cc-visa" />

  <Card title="Mastercard" icon="cc-mastercard" />

  <Card title="AMEX" icon="cc-amex" />

  <Card title="Discover" icon="cc-discover" />

  <Card title="Bank ACH" icon="building-columns" />
</CardGroup>

### Upgrading Your Plan

* You can upgrade your plan at any time
* Existing credits transfer as you upgrade
* Your current subscription will end immediately, and the new subscription date will begin at that time

### Downgrading Your Plan

* You can downgrade your plan at any time
* It will go into effect at the end of your current billing cycle
* An Essential plan is required for credits to rollover each month

### Invoices

We deliver the invoice upon charging you for your subscription. You can access past invoices and/or setup invoice forwarding in the platform under **Settings > Billing**.

## Ready to Start?

<CardGroup>
  <Card title="Try the API Playground" icon="play" href="/v1/reference/email-validation">
    Test any endpoint - see exactly what you get before using credits.
  </Card>

  <Card title="View Plans" icon="credit-card" href="https://leadmagic.io/pricing">
    Choose the right plan for your needs.
  </Card>
</CardGroup>


# Developer Experience
Source: https://leadmagic.io/docs/v1/developer-experience

Comprehensive guide to LeadMagic API's developer-friendly features

LeadMagic is built with developers in mind. Every response includes rich metadata, standardized headers, and detailed error messages to make debugging and monitoring effortless.

## Why We Build This Way

<Info>
  **Our Philosophy:** APIs should be predictable, transparent, and never surprise you. Every decision in our API design prioritizes developer happiness and operational confidence.
</Info>

### Design Principles

<CardGroup>
  <Card title="Standards-First" icon="certificate">
    We follow **RFC 9457** for errors, **IETF draft-ietf-httpapi-ratelimit-headers** for rate limits, and **RFC 7807** patterns throughout. No proprietary formats to learn.
  </Card>

  <Card title="Observable by Default" icon="eye">
    Every response includes 15+ headers giving you complete visibility into credits, rate limits, concurrency, and usage - without extra API calls.
  </Card>

  <Card title="Graceful Degradation" icon="shield-halved">
    Soft-mode rate limiting, automatic retries, and fallback mechanisms mean our limits guide you rather than break you.
  </Card>

  <Card title="Context-Rich Errors" icon="message-exclamation">
    Errors include actionable suggestions, documentation links, and machine-readable context so you can handle them programmatically.
  </Card>
</CardGroup>

### Why Response Headers Matter

Traditional APIs force you to make extra calls to check your balance or limits. LeadMagic embeds everything in response headers:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# One request = Full operational context
curl -I 'https://api.leadmagic.io/v1/people/email-validation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com"}'
```

**Every response includes:**

* Your remaining credits (`X-Credits-Remaining`)
* Rate limit status (`RateLimit-Remaining`, `RateLimit-Reset`)
* Daily quota (`X-RateLimit-Remaining-Daily`)
* Usage percentages (`X-RateLimit-Daily-Usage-Percent`)
* Soft mode status (`X-RateLimit-Soft-Mode`)

This means you can build dashboards, set up alerts, and implement smart rate limiting without polling separate endpoints.

***

## Response Headers

Every API response includes comprehensive headers for monitoring, debugging, and rate limit management.

<Tabs>
  <Tab title="Rate Limits" icon="gauge">
    ### IETF Standard Headers (Recommended)

    Following the [IETF draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) standard:

    | Header                | Description           | Example |
    | --------------------- | --------------------- | ------- |
    | `RateLimit-Limit`     | Max requests/min      | `300`   |
    | `RateLimit-Remaining` | Remaining this minute | `2847`  |
    | `RateLimit-Reset`     | Seconds until reset   | `42`    |

    ### Legacy X- Headers (Backwards Compatible)

    | Header                  | Description           | Example      |
    | ----------------------- | --------------------- | ------------ |
    | `X-RateLimit-Limit`     | Max requests/min      | `300`        |
    | `X-RateLimit-Remaining` | Remaining this minute | `2847`       |
    | `X-RateLimit-Reset`     | Unix timestamp reset  | `1706745600` |

    ### Daily Limit Headers

    | Header                        | Description          | Example      |
    | ----------------------------- | -------------------- | ------------ |
    | `X-RateLimit-Limit-Daily`     | Max requests/day     | `500000`     |
    | `X-RateLimit-Remaining-Daily` | Remaining today      | `485000`     |
    | `X-RateLimit-Reset-Daily`     | Unix timestamp reset | `1706832000` |
  </Tab>

  <Tab title="Credits & Usage" icon="coins">
    ### Credit Tracking

    | Header                | Description            | Example    |
    | --------------------- | ---------------------- | ---------- |
    | `X-Credits-Remaining` | Current credit balance | `15432.50` |
    | `X-Credits-Cost`      | Credits consumed       | `1`        |

    ### Usage Percentages

    | Header                            | Description            | Example |
    | --------------------------------- | ---------------------- | ------- |
    | `X-RateLimit-Daily-Usage-Percent` | Daily usage %          | `15`    |
    | `X-RateLimit-RPM-Usage-Percent`   | Current minute usage % | `5`     |

    <Tip>
      Use these headers to build dashboards, set up alerts at 50%/80%/95% thresholds, or implement automatic top-ups when credits run low.
    </Tip>
  </Tab>

  <Tab title="Soft Mode & Concurrency" icon="shield">
    ### Soft Mode

    LeadMagic uses "soft mode" rate limiting by default — we warn but don't block:

    | Header                      | Description                | Example |
    | --------------------------- | -------------------------- | ------- |
    | `X-RateLimit-Soft-Mode`     | Soft mode enabled          | `true`  |
    | `X-RateLimit-Soft-Exceeded` | Limit exceeded but allowed | `true`  |

    <Info>
      **Soft Mode** means we log rate limit violations but allow requests through. This prevents unexpected failures while giving you visibility into usage patterns.
    </Info>

    ### Concurrency

    | Header                  | Description                     | Example |
    | ----------------------- | ------------------------------- | ------- |
    | `X-Concurrent-Requests` | Current active requests         | `12`    |
    | `X-Active-Reservations` | Credit reservations in progress | `5`     |
    | `X-Peak-Concurrency`    | Peak concurrent this minute     | `45`    |
  </Tab>
</Tabs>

### Complete Header Reference

Here's a real-world example showing all headers in a typical response:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/2 200 OK
Content-Type: application/json

# IETF Standard Rate Limit Headers (Use these!)
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 42

# Legacy Rate Limit Headers (Backwards compatible)
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1706745600

# Daily Limits
X-RateLimit-Limit-Daily: 500000
X-RateLimit-Remaining-Daily: 485000
X-RateLimit-Reset-Daily: 1706832000

# Credits Tracking
X-Credits-Remaining: 15432.50
X-Credits-Cost: 0.25

# Usage Metrics (percentages for easy alerting)
X-RateLimit-Daily-Usage-Percent: 3
X-RateLimit-RPM-Usage-Percent: 5

# Soft Mode (we warn but don't block)
X-RateLimit-Soft-Mode: true

# Concurrency
X-Concurrent-Requests: 12
X-Active-Reservations: 0
X-Peak-Concurrency: 45

# Request Tracking
X-Request-ID: req_abc123def456
```

<Tip>
  **Pro Tip:** Log these headers after every request. When debugging issues, you'll have complete visibility into your API state at that exact moment.
</Tip>

***

## Request Headers

### Required Headers

| Header         | Description                        | Example             |
| -------------- | ---------------------------------- | ------------------- |
| `X-API-Key`    | Your API key (case-insensitive)    | `lm_live_abc123...` |
| `Content-Type` | Always `application/json` for POST | `application/json`  |

<Info>
  **Case-Insensitive Authentication:** The `X-API-Key` header accepts any case variation: `X-API-Key`, `X-API-KEY`, `x-api-key` all work identically.
</Info>

### Optional Headers

| Header         | Description                 | Use Case                                                              |
| -------------- | --------------------------- | --------------------------------------------------------------------- |
| `User-Agent`   | Identifies your application | Used for timeout optimization (Clay integrations get longer timeouts) |
| `X-Request-ID` | Your request tracking ID    | Returned in error responses for debugging                             |
| `Accept`       | Response format             | `application/json` (default)                                          |

***

## Success Messages

Every endpoint returns a human-readable `message` field that tells you exactly what happened. These are designed to be user-friendly and can be displayed directly in your UI.

<Tabs>
  <Tab title="Email Validation" icon="envelope">
    | Message                               | Meaning                          |
    | ------------------------------------- | -------------------------------- |
    | `Email is valid.`                     | Email verified as deliverable    |
    | `Email is invalid.`                   | Email doesn't exist or bounces   |
    | `Unable to determine email validity.` | Verification inconclusive (free) |
  </Tab>

  <Tab title="Email Finder" icon="magnifying-glass">
    | Message                                           | Meaning                             |
    | ------------------------------------------------- | ----------------------------------- |
    | `Valid email found.`                              | Email found and verified (1 credit) |
    | `No email found for this person at this company.` | No email found (free)               |
  </Tab>

  <Tab title="Mobile Finder" icon="phone">
    | Message                                    | Meaning                             |
    | ------------------------------------------ | ----------------------------------- |
    | `Mobile number found.`                     | Phone number successfully retrieved |
    | `No mobile number found for this contact.` | No phone data available             |
  </Tab>

  <Tab title="Profile Search" icon="user">
    | Message                                | Meaning                             |
    | -------------------------------------- | ----------------------------------- |
    | `Profile found.`                       | Full profile data returned          |
    | `Profile not found or not accessible.` | Profile doesn't exist or is private |
  </Tab>

  <Tab title="Company Search" icon="building">
    | Message             | Meaning               |
    | ------------------- | --------------------- |
    | `Company found`     | Company data returned |
    | `Company not found` | No matching company   |
  </Tab>

  <Tab title="Role Finder" icon="briefcase">
    | Message                                   | Meaning                         |
    | ----------------------------------------- | ------------------------------- |
    | `Role Found`                              | Person with matching role found |
    | `No matching role found at this company.` | No matching role exists         |
  </Tab>

  <Tab title="People Search" icon="users">
    | Message           | Meaning                                      |
    | ----------------- | -------------------------------------------- |
    | `People found`    | People list returned                         |
    | `No people found` | No matching people for the requested filters |
  </Tab>

  <Tab title="Job Change Detector" icon="right-left">
    | Message                                                       | Meaning                    |
    | ------------------------------------------------------------- | -------------------------- |
    | `No job change detected. Still employed at expected company.` | Person still at company    |
    | `Job change detected. Person has moved to a new company.`     | Person changed jobs        |
    | `Never worked at the expected company.`                       | No employment record found |
  </Tab>
</Tabs>

<Note>
  **Why Messages Matter:** These aren't just for humans - they're also machine-readable. Check the `message` field to determine success vs. not-found scenarios, especially when `credits_consumed` might still be > 0 for verified "not found" results.
</Note>

## Analytics Endpoints

Monitor your API usage programmatically with our comprehensive analytics suite.

<Note>
  **All analytics endpoints are FREE** - they don't consume any credits and are exempt from rate limiting.
</Note>

### Dashboard Overview

Get a real-time snapshot of your account status:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v1/analytics/dashboard' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const dashboard = await response.json();
  console.log(`Credits: ${dashboard.credits.current}`);
  console.log(`RPM Used: ${dashboard.rate_limit.minute.used}/${dashboard.rate_limit.minute.limit}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v1/analytics/dashboard',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  dashboard = response.json()
  print(f"Credits: {dashboard['credits']['current']}")
  print(f"Daily Used: {dashboard['rate_limit']['daily']['used']}")
  ```
</CodeGroup>

**Response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "user": {
    "id": "user_abc123",
    "email": "developer@company.com"
  },
  "credits": {
    "current": 15432.50,
    "formatted": "$154.33"
  },
  "rate_limit": {
    "minute": {
      "limit": 300,
      "used": 45,
      "remaining": 255,
      "utilization": 15.0
    },
    "daily": {
      "limit": 500000,
      "used": 12500,
      "remaining": 487500,
      "utilization": 2.5
    }
  },
  "concurrency": {
    "current": 0,
    "peak": 23,
    "active_reservations": 0
  },
  "stats": {
    "today": {
      "requests": 1250,
      "credits": 875.50,
      "chargeable_requests": 1100,
      "chargeable_rate": 88.0,
      "unique_products": 5
    },
    "this_week": {
      "requests": 8500,
      "credits": 5200.25,
      "chargeable_requests": 7200,
      "chargeable_rate": 84.7,
      "unique_products": 8
    },
    "this_month": {
      "requests": 45000,
      "credits": 28500.00,
      "chargeable_requests": 38000,
      "chargeable_rate": 84.4,
      "unique_products": 12
    }
  }
}
```

### Available Analytics Endpoints

<CardGroup>
  <Card title="GET /v1/analytics/dashboard" icon="gauge">
    Real-time dashboard with credits, rate limits, and usage stats for today, this week, and this month.
  </Card>

  <Card title="GET /v1/analytics/usage" icon="chart-bar">
    Daily usage summary with total requests, credits consumed, and chargeable rates.

    **Query params:** `?days=30` (1-90)
  </Card>

  <Card title="GET /v1/analytics/products" icon="boxes-stacked">
    Per-product breakdown showing requests, credits, success rates, and average costs.

    **Query params:** `?days=30` (1-90)
  </Card>

  <Card title="GET /v1/analytics/credits" icon="coins">
    Credit consumption history with daily breakdown and chargeable request analysis.

    **Query params:** `?days=30` (1-90)
  </Card>

  <Card title="GET /v1/analytics/summary" icon="calculator">
    All-time statistics including total requests, credits consumed, success rates, and first/last request timestamps.

    **Query params:** `?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`
  </Card>

  <Card title="GET /v1/analytics/daily" icon="calendar-days">
    Detailed daily metrics with latency percentiles, error rates, and performance data.

    **Query params:** `?days=30` (1-90)
  </Card>

  <Card title="GET /v1/analytics/day/:date" icon="calendar-day">
    Per-product breakdown for a specific day. Top 15 products plus aggregated "other" category.

    **Path param:** `:date` in YYYY-MM-DD format
  </Card>
</CardGroup>

### Usage Example: Daily Breakdown

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.leadmagic.io/v1/analytics/usage?days=7' \
  -H 'X-API-Key: YOUR_API_KEY'
```

**Response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-25",
    "end": "2026-11-01",
    "days": 7
  },
  "summary": {
    "total_requests": 8500,
    "chargeable_requests": 7200,
    "total_credits": 5200.25,
    "avg_credits_per_request": 0.61,
    "chargeable_rate": 84.7,
    "unique_products": 8
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "chargeable_requests": 1100,
      "total_credits": 875.50,
      "unique_products_used": 5
    }
    // ... more days
  ]
}
```

## Credits Endpoints

### Check Your Balance

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v1/credits' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/credits', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const { credits } = await response.json();
  console.log(`Available credits: ${credits}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v1/credits',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  print(f"Credits: {response.json()['credits']}")
  ```
</CodeGroup>

**Response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "credits": 15432.50
}
```

### Additional Credits Endpoints

| Endpoint                   | Method | Description                                      |
| -------------------------- | ------ | ------------------------------------------------ |
| `GET /v1/credits`          | GET    | Get current credit balance                       |
| `POST /v1/credits/refresh` | POST   | Force refresh credits from database              |
| `GET /v1/credits/health`   | GET    | Validate API key and check authentication status |

## Error Handling

LeadMagic follows [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) for standardized, machine-readable error responses.

### Error Response Format

```json {3,4,5,6,7,8} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/insufficient_credits",
      "title": "Insufficient credits: need 5, have 2.50. Add credits to continue.",
      "status": 402,
      "detail": "This request requires 5 credit(s) but your account only has 2.50 credits remaining.",
      "instance": "/v1/people/mobile-finder#req_abc123",
      "code": "insufficient_credits",
      "action": "Add credits to your account at https://app.leadmagic.io/billing",
      "docs": "https://leadmagic.io/docs/v1/credits",
      "context": {
        "credits_required": 5,
        "credits_available": 2.50,
        "credits_needed": 2.50
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-10-01T12:00:00.000Z",
    "environment": "production"
  }
}
```

### Response Fields Explained

| Field     | Description                                       |
| --------- | ------------------------------------------------- |
| `type`    | URI identifying the error type (machine-readable) |
| `title`   | Human-readable summary (safe to display to users) |
| `status`  | HTTP status code                                  |
| `detail`  | Specific explanation of what went wrong           |
| `code`    | Short error code for programmatic handling        |
| `action`  | Suggested fix or next steps                       |
| `docs`    | Link to relevant documentation                    |
| `context` | Machine-readable details (varies by error type)   |

### HTTP Status Codes

<CardGroup>
  <Card title="200" icon="circle-check">
    **Success** - Request completed
  </Card>

  <Card title="400" icon="circle-xmark">
    **Bad Request** - Invalid input
  </Card>

  <Card title="401" icon="lock">
    **Unauthorized** - Invalid API key
  </Card>

  <Card title="402" icon="credit-card">
    **Payment Required** - Low credits
  </Card>

  <Card title="429" icon="gauge-high">
    **Too Many Requests** - Rate limited
  </Card>

  <Card title="500" icon="server">
    **Server Error** - Our fault
  </Card>
</CardGroup>

### Error Types

<Tabs>
  <Tab title="401 Authentication" icon="key">
    **HTTP 401 - Unauthorized**

    | Code                       | Description                               |
    | -------------------------- | ----------------------------------------- |
    | `missing_authentication`   | No API key provided in `X-API-Key` header |
    | `invalid_api_key`          | API key doesn't exist or is incorrect     |
    | `insufficient_permissions` | API key lacks access to this resource     |

    ```json {4,5} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "errors": [{
        "type": "https://api.leadmagic.io/errors/invalid_api_key",
        "title": "Invalid API key. The key does not exist or is incorrect.",
        "status": 401,
        "code": "invalid_api_key",
        "docs": "https://leadmagic.io/docs/v1/authentication"
      }]
    }
    ```
  </Tab>

  <Tab title="400 Validation" icon="circle-exclamation">
    **HTTP 400 - Bad Request**

    | Code                     | Description                    |
    | ------------------------ | ------------------------------ |
    | `validation_error`       | Request validation failed      |
    | `missing_required_field` | Required field not provided    |
    | `invalid_json`           | Request body is not valid JSON |
    | `invalid_parameter`      | Parameter value is invalid     |

    ```json {4,5,7} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "errors": [{
        "type": "https://api.leadmagic.io/errors/validation_error",
        "title": "Request validation failed. Check your input parameters.",
        "status": 400,
        "code": "validation_error",
        "param": ["email"],
        "docs": "https://leadmagic.io/docs/v1/making-api-calls"
      }]
    }
    ```
  </Tab>

  <Tab title="429 Rate Limits" icon="gauge">
    **HTTP 429 - Too Many Requests**

    | Code                  | Description                        |
    | --------------------- | ---------------------------------- |
    | `rate_limit_exceeded` | Exceeded per-minute or daily limit |

    <Note>
      Includes `Retry-After` header with seconds until reset.
    </Note>

    ```json {4,5,8,9} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "errors": [{
        "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
        "title": "Rate limit exceeded: 300 requests per 1 minute.",
        "status": 429,
        "code": "rate_limit_exceeded",
        "detail": "You have exceeded the maximum allowed request rate.",
        "action": "Wait 42 seconds before retrying.",
        "context": {
          "limit": 300,
          "window": "1 minute",
          "remaining": 0,
          "reset_at": 1706745642,
          "retry_after_seconds": 42
        }
      }]
    }
    ```
  </Tab>

  <Tab title="402 Credits" icon="credit-card">
    **HTTP 402 - Payment Required**

    | Code                   | Description                         |
    | ---------------------- | ----------------------------------- |
    | `insufficient_credits` | Not enough credits for this request |

    ```json {4,5,8-11} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "errors": [{
        "type": "https://api.leadmagic.io/errors/insufficient_credits",
        "title": "Insufficient credits: need 5, have 2.50.",
        "status": 402,
        "code": "insufficient_credits",
        "context": {
          "credits_required": 5,
          "credits_available": 2.50,
          "credits_needed": 2.50
        }
      }]
    }
    ```
  </Tab>

  <Tab title="5xx Server" icon="server">
    **HTTP 5xx - Server Errors**

    | Code                     | Status | Description              |
    | ------------------------ | ------ | ------------------------ |
    | `internal_error`         | 500    | Unexpected server error  |
    | `external_service_error` | 502    | Upstream service failed  |
    | `service_unavailable`    | 503    | Service temporarily down |

    ```json {4,5,7} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "errors": [{
        "type": "https://api.leadmagic.io/errors/internal_error",
        "title": "Something went wrong on our end.",
        "status": 500,
        "code": "INTERNAL_ERROR",
        "action": "Wait 30 seconds and retry. Contact support@leadmagic.io if persistent."
      }]
    }
    ```
  </Tab>
</Tabs>

## Idempotency

Every request can include a unique identifier for tracking and debugging:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Request-ID: my-unique-request-id-123' \
  -H 'Content-Type: application/json' \
  -d '{"email": "test@example.com"}'
```

The `X-Request-ID` is returned in error responses and logged for debugging:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errors": [{
    "instance": "/v1/people/email-validation#my-unique-request-id-123"
  }],
  "meta": {
    "request_id": "my-unique-request-id-123"
  }
}
```

## Graceful Degradation

LeadMagic is designed to handle failures gracefully:

| Scenario                     | Behavior                            |
| ---------------------------- | ----------------------------------- |
| **DO Timeout**               | Falls back to direct database query |
| **Rate limit in soft mode**  | Logs warning but allows request     |
| **External service failure** | Returns 502 with retry guidance     |
| **Database unavailable**     | Returns 503 with retry timing       |

<Info>
  **High Availability:** Our Durable Objects provide sub-millisecond rate limiting with automatic failover to PostgreSQL when needed.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Implement Exponential Backoff" icon="clock">
    When you receive a 429 error, use the `Retry-After` header:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    async function callWithRetry(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        const response = await fn();

        if (response.status === 429) {
          const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
          await sleep(retryAfter * 1000);
          continue;
        }

        return response;
      }
      throw new Error('Max retries exceeded');
    }
    ```
  </Accordion>

  <Accordion title="Monitor Rate Limit Headers" icon="gauge">
    Build proactive monitoring using response headers:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    async function monitoredRequest(url, options) {
      const response = await fetch(url, options);

      const dailyUsage = response.headers.get('X-RateLimit-Daily-Usage-Percent');
      const creditsRemaining = response.headers.get('X-Credits-Remaining');

      if (parseInt(dailyUsage) > 80) {
        alert('Approaching daily rate limit: ' + dailyUsage + '%');
      }

      if (parseFloat(creditsRemaining) < 1000) {
        alert('Low credits: ' + creditsRemaining);
      }

      return response;
    }
    ```
  </Accordion>

  <Accordion title="Use Request IDs for Debugging" icon="bug">
    Always include a request ID for easier debugging:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const requestId = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

    const response = await fetch(url, {
      headers: {
        'X-API-Key': apiKey,
        'X-Request-ID': requestId,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    // Log for debugging
    console.log(`Request ${requestId}: ${response.status}`);
    ```
  </Accordion>

  <Accordion title="Cache Credits Check" icon="database">
    Don't call `/v1/credits` before every request. Cache and refresh periodically:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    let cachedCredits = null;
    let lastFetch = 0;
    const CACHE_TTL = 60000; // 1 minute

    async function getCredits() {
      if (cachedCredits && Date.now() - lastFetch < CACHE_TTL) {
        return cachedCredits;
      }

      const response = await fetch('https://api.leadmagic.io/v1/credits', {
        headers: { 'X-API-Key': apiKey }
      });

      const { credits } = await response.json();
      cachedCredits = credits;
      lastFetch = Date.now();
      return credits;
    }
    ```
  </Accordion>
</AccordionGroup>

## SDK Support

While we don't have official SDKs yet, our REST API works seamlessly with any HTTP client:

<CardGroup>
  <Card title="Node.js" icon="node-js">
    Use native `fetch` or `axios` for HTTP requests.
  </Card>

  <Card title="Python" icon="python">
    Use `requests` or `httpx` for async support.
  </Card>

  <Card title="Any Language" icon="code">
    Any HTTP client works - just send JSON with your API key.
  </Card>
</CardGroup>

***

## Why We Built It This Way

<AccordionGroup>
  <Accordion title="RFC 9457 Problem Details for Errors" icon="standard">
    Traditional APIs return cryptic errors like `{"error": "Bad request"}`. This leaves developers guessing what went wrong and how to fix it.

    **Our approach:** Every error follows [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457), a standard designed by the IETF specifically for HTTP API errors. This means:

    * **`type`**: A URI identifying the error type (bookmarkable, consistent)
    * **`title`**: Human-readable summary you can show users
    * **`status`**: HTTP status code (redundant but useful)
    * **`detail`**: Specific explanation of what went wrong
    * **`action`**: Suggested fix (unique to LeadMagic)
    * **`docs`**: Link to relevant documentation
    * **`context`**: Machine-readable details (credits needed, rate limits, etc.)

    This isn't just for show - your code can programmatically handle errors based on `type` while showing users the `title` and `action`.
  </Accordion>

  <Accordion title="IETF Rate Limit Headers" icon="gauge">
    We implement the [IETF draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) standard for rate limit headers:

    ```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
    RateLimit-Limit: 300
    RateLimit-Remaining: 287
    RateLimit-Reset: 42
    ```

    **Why this matters:**

    * These headers are on track to become an official standard
    * Libraries already support them (many HTTP clients auto-parse)
    * Consistent across all modern APIs that implement the spec
    * No need to learn LeadMagic-specific header names

    We also include legacy `X-RateLimit-*` headers for backwards compatibility.
  </Accordion>

  <Accordion title="Soft Mode Rate Limiting" icon="shield-heart">
    Most APIs hard-block you when you hit limits. This causes:

    * Unexpected failures in production
    * Data loss if you're mid-batch
    * Frustrated developers

    **Our approach:** Soft mode warns but doesn't block. When you exceed limits, we:

    1. Log the violation
    2. Set `X-RateLimit-Soft-Exceeded: true`
    3. **Still process your request**

    This gives you time to fix your implementation without breaking production. Watch for the header in logs and fix before we have to enforce limits.
  </Accordion>

  <Accordion title="Credits in Every Response" icon="coins">
    Checking your balance shouldn't require extra API calls. Every enrichment response includes:

    ```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
    X-Credits-Remaining: 15432.50
    X-Credits-Cost: 1
    ```

    **Benefits:**

    * Build credit alerts without polling
    * Log spend per-request for cost attribution
    * Pause automatically when credits run low
    * Never wonder "how much did that cost?"
  </Accordion>

  <Accordion title="Meaningful Success Messages" icon="message-check">
    Our `message` field isn't just "success" - it tells you what actually happened:

    * `"Email is valid."` - Great, use it!
    * `"Email is invalid."` - Do not email
    * `"Unable to determine email validity."` - Unknown result (free)

    This lets you:

    * Display messages directly to end users
    * Make programmatic decisions based on outcomes
    * Distinguish between "not found" and "error"
  </Accordion>

  <Accordion title="Zero-Cost Analytics" icon="chart-pie">
    All analytics endpoints are **FREE** - no credits consumed, no rate limits. This means you can:

    * Poll `/v1/analytics/dashboard` every minute
    * Build real-time dashboards
    * Set up alerting without worrying about cost
    * Audit your usage as often as needed

    We want you to have complete visibility into your API usage.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/v1/authentication">
    Deep dive into API key management and security best practices.
  </Card>

  <Card title="Credits Guide" icon="coins" href="/v1/credits">
    Understand credit costs, billing, and optimization strategies.
  </Card>

  <Card title="API Reference" icon="book" href="/v1/reference/email-validation">
    Explore all available endpoints in the interactive playground.
  </Card>

  <Card title="Integrations" icon="plug" href="/v1/integrations">
    Connect LeadMagic with Clay, Make, Zapier, and more.
  </Card>
</CardGroup>


# Integrations
Source: https://leadmagic.io/docs/v1/integrations

Use LeadMagic in Clay, Bitscale, Instantly, Example Robotics, Salesforge, Email Bison, Apollo, and more

LeadMagic integrates natively with popular sales and marketing platforms. Use our data enrichment without writing any code.

<Tip>
  **Prefer the API?** Jump to our [API
  Playground](/docs/v1/reference/email-validation) to test endpoints directly.
</Tip>

## Supported Platforms

<CardGroup>
  <Card title="Clay" icon="shapes" href="#clay-integration">
    \#1 ranked in Clay waterfalls. Native enrichment actions.
  </Card>

  <Card title="Instantly" icon="bolt" href="#instantly-integration">
    Email validation and lead enrichment.
  </Card>

  <Card title="Example Robotics" icon="envelope" href="#smartlead-integration">
    Bounce prevention and list enrichment.
  </Card>

  <Card title="Email Bison" icon="envelope-circle-check" href="#email-bison">
    Auto-validation and enrichment workflows.
  </Card>

  <Card title="Salesforge" icon="fire" href="#salesforge">
    Pre-send validation and AI personalization.
  </Card>

  <Card title="Apollo" icon="rocket" href="#apollo-integration">
    Waterfall enrichment to fill data gaps.
  </Card>

  <Card title="Zapier" icon="bolt" href="#zapier-integration">
    No-code automation with triggers and actions.
  </Card>

  <Card title="Make" icon="gear" href="#make-integration">
    HTTP module for custom workflows.
  </Card>

  <Card title="Example CRM" icon="cloud" href="#salesforce-integration">
    CRM field mapping and sync.
  </Card>

  <Card title="Bitscale" icon="diagram-project" href="#bitscale-integration">
    Waterfall GTM enrichment with LeadMagic as a data provider.
  </Card>
</CardGroup>

***

## Bitscale Integration

Bitscale is a GTM platform for outbound at scale. LeadMagic is available as a data provider inside Bitscale's waterfall enrichment so you can find and validate contacts before campaigns go live.

### Available LeadMagic enrichments in Bitscale

| Enrichment                | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| **Email Finder**          | Verified professional emails from name and company context |
| **Mobile Finder**         | Direct mobile numbers for decision-makers                  |
| **Profile Search**        | Enrich from a B2B profile URL                              |
| **Personal Email Finder** | Personal addresses when work email is missing              |
| **Email Validation**      | Deliverability checks before send                          |
| **Email To B2B Profiler** | Structured B2B profile from an email address               |
| **Company Finder**        | Company context from domain or signals                     |

### Learn more

See the [Bitscale integration page](https://leadmagic.io/integrations/bitscale) for positioning, FAQs, and how Bitscale compares to other enrichment-first tools.

***

## Clay Integration

<Note>
  **LeadMagic is the #1 ranked provider in Clay waterfalls** for data quality,
  match rates, and value.
</Note>

### Why LeadMagic in Clay?

<CardGroup>
  <Card title="Highest Accuracy" icon="bullseye">
    Best match rates for emails and mobile numbers.
  </Card>

  <Card title="Best Value" icon="coins">
    Credits never expire. Lower cost per enrichment.
  </Card>

  <Card title="Fastest Response" icon="bolt">
    Real-time API with high uptime.
  </Card>
</CardGroup>

### Available Actions in Clay

| Action                  | Description                             | Use Case               |
| ----------------------- | --------------------------------------- | ---------------------- |
| **Company Search**      | Get firmographic data from LinkedIn URL | Account research       |
| **Find Work Email**     | Find email from name + domain           | Outreach campaigns     |
| **Find Mobile Number**  | Get direct mobile via LinkedIn          | Multi-channel outreach |
| **Find Social Profile** | LinkedIn from email address             | Profile enrichment     |
| **Validate Email**      | Verify email deliverability             | List cleaning          |

### Setup: Connect Your API Key

<Steps>
  <Step title="Get your API key">
    Log in to [LeadMagic](https://app.leadmagic.io/settings/api) and copy your
    API key.
  </Step>

  <Step title="Open a LeadMagic enrichment in Clay">
    In your Clay table, click "Add Enrichment" and search for "LeadMagic".
  </Step>

  <Step title="Connect your account">
    Click "Add new account" → "Use your own API key" → Paste your key.
  </Step>

  <Step title="Start enriching">
    Your LeadMagic credits are now connected. Enrichments use your LeadMagic
    balance.
  </Step>
</Steps>

<Info>
  **Two options in Clay:** 1. **Clay-managed account** (default) - Uses Clay
  credits at Clay's rates 2. **Your own API key** (recommended) - Uses your
  LeadMagic credits at better rates
</Info>

### Waterfall Strategy

For maximum data coverage, place LeadMagic first in your waterfalls:

```
1. LeadMagic (primary - highest quality)
2. Backup provider #1
3. Backup provider #2
```

LeadMagic's high match rates mean you'll need fewer fallback calls.

<Accordion title="Clay Credit Comparison">
  | Feature  | Using Clay-Managed         | Using Your API Key             |
  | -------- | -------------------------- | ------------------------------ |
  | Billing  | Charged from Clay balance  | Charged from LeadMagic balance |
  | Rate     | Clay's per-enrichment rate | LeadMagic's lower rate         |
  | Setup    | No setup required          | Requires API key connection    |
  | Best For | Testing                    | Regular use                    |
</Accordion>

***

## Instantly Integration

Enrich and validate leads directly in your Instantly cold email campaigns for higher deliverability and response rates.

<CardGroup>
  <Card title="Email Validation" icon="envelope-circle-check">
    Verify emails before sending to reduce bounces.
  </Card>

  <Card title="Lead Enrichment" icon="user-plus">
    Add missing data like company, title, and phone.
  </Card>

  <Card title="Real-time Sync" icon="rotate">
    Automatic enrichment on lead import.
  </Card>
</CardGroup>

### Setup Instructions

<Steps>
  <Step title="Access Integrations">
    In Instantly, go to **Settings → Integrations → Data Enrichment**.
  </Step>

  <Step title="Find LeadMagic">
    Search for "LeadMagic" in the integration marketplace.
  </Step>

  <Step title="Connect with API key">
    Paste your [LeadMagic API key](https://app.leadmagic.io/settings/api) and click Connect.
  </Step>

  <Step title="Configure enrichment rules">
    Select which enrichments to run:

    * **Email Validation** — Verify all emails before campaigns
    * **Email Finder** — Find missing emails from name + company
    * **Mobile Finder** — Add phone numbers for multi-channel
  </Step>

  <Step title="Enable auto-enrichment">
    Toggle "Auto-enrich new leads" to process imports automatically.
  </Step>
</Steps>

<Tip>
  **Pro tip:** Enable email validation on all campaigns to maintain your sender reputation and reduce bounce rates below 2%.
</Tip>

### Use Cases

| Workflow                | LeadMagic Feature | Benefit                                   |
| ----------------------- | ----------------- | ----------------------------------------- |
| Pre-campaign validation | Email Validation  | Reduce bounces, protect sender reputation |
| Lead list enrichment    | Profile Search    | Add titles, companies, social links       |
| Multi-channel outreach  | Mobile Finder     | Enable SMS and cold calling               |

***

## Example Robotics Integration

Supercharge your Example Robotics campaigns with LeadMagic's real-time email validation and enrichment.

<CardGroup>
  <Card title="Bounce Prevention" icon="shield-check">
    Validate emails before sending.
  </Card>

  <Card title="List Enrichment" icon="database">
    Fill in missing lead data.
  </Card>

  <Card title="Webhook Sync" icon="webhook">
    Push enriched data automatically.
  </Card>
</CardGroup>

### Setup Instructions

<Steps>
  <Step title="Access Integrations">
    In Example Robotics, navigate to **Settings → Integrations**.
  </Step>

  <Step title="Find LeadMagic">
    Search for "LeadMagic" in the available integrations.
  </Step>

  <Step title="Connect with API key">
    Paste your [LeadMagic API key](https://app.leadmagic.io/settings/api).
  </Step>

  <Step title="Configure validation settings">
    Enable automatic email validation for new leads:

    * **Reject invalid emails** — Automatically exclude bouncing addresses
    * **Skip unknown results** — Inconclusive validations are free, retry later
  </Step>

  <Step title="Set up webhook (optional)">
    Configure a webhook in LeadMagic to push enriched data directly to your Example Robotics campaigns.
  </Step>
</Steps>

<Info>
  **Webhook URL:** Find your Example Robotics webhook URL in Settings → Webhooks → Inbound. Paste this into LeadMagic to enable real-time sync.
</Info>

### Example Robotics + LeadMagic Workflow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
graph LR
    A[Import Leads] --> B[LeadMagic Validation]
    B --> C{Valid?}
    C -->|Yes| D[Add to Campaign]
    C -->|No| E[Exclude/Review]
    D --> F[Send Emails]
```

***

## Email Bison Integration

Connect LeadMagic with Email Bison for automated lead enrichment and validation in your cold email workflows.

<CardGroup>
  <Card title="Auto-Validation" icon="check-double">
    Validate emails on import.
  </Card>

  <Card title="Enrichment" icon="sparkles">
    Add company and contact data.
  </Card>

  <Card title="API Integration" icon="code">
    Direct API connection.
  </Card>
</CardGroup>

### Setup Instructions

<Steps>
  <Step title="Access Email Bison Settings">
    In Email Bison, go to **Settings → Integrations → API Connections**.
  </Step>

  <Step title="Add LeadMagic">
    Click "Add New Integration" and select "Custom API" or find LeadMagic if listed.
  </Step>

  <Step title="Configure API endpoint">
    Enter the LeadMagic API details:

    * **Base URL:** `https://api.leadmagic.io/v1`
    * **Auth Header:** `X-API-Key`
    * **API Key:** Your [LeadMagic API key](https://app.leadmagic.io/settings/api)
  </Step>

  <Step title="Map data fields">
    Configure which Email Bison fields map to LeadMagic request parameters:

    * `email` → Email Validation
    * `first_name` + `last_name` + `company` → Email Finder
  </Step>

  <Step title="Enable automation">
    Set up triggers to automatically enrich new leads on import.
  </Step>
</Steps>

### Recommended Workflow

<Accordion title="Email Bison Enrichment Workflow">
  1. **Import leads** into Email Bison
  2. **Trigger LeadMagic validation** on all emails
  3. **Remove invalid emails** automatically
  4. **Enrich remaining leads** with company data
  5. **Start campaign** with clean, enriched list

  This workflow typically improves deliverability by 15-25%.
</Accordion>

***

## Salesforge Integration

Integrate LeadMagic with Salesforge to validate and enrich leads before AI-powered outreach.

<CardGroup>
  <Card title="Pre-Send Validation" icon="envelope-circle-check">
    Verify emails before Salesforge sends.
  </Card>

  <Card title="Data Enrichment" icon="database">
    Add context for AI personalization.
  </Card>

  <Card title="Real-time API" icon="bolt">
    Fast enrichment for high-volume.
  </Card>
</CardGroup>

### Setup Instructions

<Steps>
  <Step title="Access Salesforge Integrations">
    In Salesforge, navigate to **Settings → Integrations → Data Providers**.
  </Step>

  <Step title="Add LeadMagic">
    Click "Add Provider" and select LeadMagic, or choose "Custom API".
  </Step>

  <Step title="Enter API credentials">
    Configure the connection:

    * **API Key:** Your [LeadMagic API key](https://app.leadmagic.io/settings/api)
    * **Endpoint:** `https://api.leadmagic.io/v1`
  </Step>

  <Step title="Configure enrichment flow">
    Set up which LeadMagic features to use:

    * **Email Validation** — Verify all emails (recommended)
    * **Profile Search** — Get job titles for personalization
    * **Company Search** — Get firmographics for targeting
  </Step>

  <Step title="Enable auto-enrichment">
    Toggle automatic enrichment for new leads added to sequences.
  </Step>
</Steps>

<Tip>
  **AI + Enrichment:** Use LeadMagic's company and profile data to give Salesforge's AI more context for better personalization.
</Tip>

### Salesforge Use Cases

| Use Case             | LeadMagic Endpoint | Benefit                       |
| -------------------- | ------------------ | ----------------------------- |
| Email verification   | Email Validation   | Protect sender reputation     |
| Personalization data | Profile Search     | Job title, experience, skills |
| Company targeting    | Company Search     | Industry, size, tech stack    |
| Multi-channel        | Mobile Finder      | Add phone for calls/SMS       |

***

## Apollo Integration

Add LeadMagic to Apollo's waterfall enrichment for better data coverage.

<Steps>
  <Step title="Open Apollo Waterfall Settings">
    Navigate to Settings → Enrichment → Waterfall Configuration.
  </Step>

  <Step title="Add LeadMagic as a Provider">
    Click "Add Provider" and select LeadMagic.
  </Step>

  <Step title="Enter your API key">
    Paste your [LeadMagic API key](https://app.leadmagic.io/settings/api).
  </Step>

  <Step title="Set priority">
    Drag LeadMagic to the top of your waterfall for best results.
  </Step>
</Steps>

***

## Zapier Integration

Automate enrichments with Zapier triggers and actions.

<CardGroup>
  <Card title="Trigger: New Lead" icon="plus">
    When a new lead is added to your CRM...
  </Card>

  <Card title="Action: Enrich with LeadMagic" icon="wand-magic-sparkles">
    ...automatically enrich with email, phone, company data.
  </Card>
</CardGroup>

### Example Zaps

* **Example Robotics → LeadMagic → Example Robotics**: Enrich new contacts automatically
* **Typeform → LeadMagic → Slack**: Validate emails from form submissions
* **Google Sheets → LeadMagic → Google Sheets**: Batch enrich spreadsheet data

***

## Make (Integromat)

Build visual workflows with LeadMagic HTTP modules.

<Accordion title="Make HTTP Module Setup">
  1. Add an HTTP module to your scenario
  2. Set method to `POST`
  3. Set URL to the LeadMagic endpoint (e.g., `https://api.leadmagic.io/v1/people/email-validation`)
  4. Add headers:
     * `Content-Type: application/json`
     * `X-API-Key: YOUR_API_KEY`
  5. Set body type to JSON and add your parameters
</Accordion>

***

## Webhooks

Push enriched data to any system with webhooks. No additional credits charged.

<Note>
  Webhooks allow you to receive enrichment results automatically when processing
  is complete — perfect for real-time workflows.
</Note>

### Supported Destinations

<CardGroup>
  <Card title="Clay" icon="table">
    Push to Clay tables
  </Card>

  <Card title="Example Robotics" icon="envelope">
    Sync with campaigns
  </Card>

  <Card title="Instantly" icon="bolt">
    Real-time lead enrichment
  </Card>

  <Card title="Email Bison" icon="envelope-open-text">
    Automated validation
  </Card>

  <Card title="Salesforge" icon="robot">
    AI-powered outreach
  </Card>

  <Card title="Custom Webhook" icon="webhook">
    Any HTTP endpoint
  </Card>
</CardGroup>

### Setting Up Webhooks

<Steps>
  <Step title="Access webhook settings">
    In LeadMagic, find the three-dot menu next to your enrichment history.
  </Step>

  <Step title="Select your platform">
    Choose from Clay, Example Robotics, or Instantly.
  </Step>

  <Step title="Paste webhook URL">
    Enter the webhook URL from your destination platform.
  </Step>

  <Step title="Verify connection">
    The system validates the connection automatically.
  </Step>
</Steps>

### Webhook Payload Example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "event": "enrichment.completed",
  "data": {
    "email": "alex.rivera@example.com",
    "status": "valid",
    "company": {
      "name": "Example Inc",
      "domain": "example.com"
    }
  },
  "timestamp": "2026-10-15T10:30:00Z"
}
```

***

## Example CRM Integration

Sync enriched data directly to Example CRM.

<Steps>
  <Step title="Connect Example CRM">
    Go to [Settings > Integrations](https://app.leadmagic.io/settings/integrations) and click "Connect Example CRM".
  </Step>

  <Step title="Authorize access">
    Log in to Example CRM and grant LeadMagic access.
  </Step>

  <Step title="Map fields">
    Configure which LeadMagic fields map to which Example CRM fields.
  </Step>

  <Step title="Enable sync">
    Choose automatic sync or manual push.
  </Step>
</Steps>

***

## API for Custom Integrations

Need a custom integration? Our RESTful API works with any platform.

<CardGroup>
  <Card title="API Playground" icon="play" href="/v1/reference/email-validation">
    Test endpoints interactively.
  </Card>

  <Card title="Authentication" icon="key" href="/v1/authentication">
    Learn about API authentication.
  </Card>

  <Card title="Making API Calls" icon="code" href="/v1/making-api-calls">
    Code examples in multiple languages.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/v1/making-api-calls#rate-limits">
    Understand rate limiting.
  </Card>
</CardGroup>

## Need Help?

<Card title="Contact Support" icon="headset" href="/v1/support">
  Our team can help with custom integrations and enterprise setups.
</Card>


# Introduction
Source: https://leadmagic.io/docs/v1/introduction

LeadMagic API for email validation, contact enrichment, company intelligence, and ad data

# B2B Data Enrichment API

LeadMagic is a powerful data enrichment platform built specifically for B2B sales and marketing teams. 20+ endpoints across email, contact, company, jobs, and ads data — all accessible through a single API key.

<Note>
  **Ready to try it?** Jump straight into our [API
  Playground](/docs/v1/reference/email-validation) and test any endpoint in seconds -
  no setup required. To plan a workflow first, browse [Use Cases](/docs/v1/use-cases).
</Note>

## Try the API Now

<CardGroup>
  <Card title="Email Validation Playground" icon="envelope-circle-check" href="/v1/reference/email-validation">
    **Most Popular** - Verify emails instantly. Get 4 validations per credit.
  </Card>

  <Card title="Email Finder Playground" icon="magnifying-glass" href="/v1/reference/email-finder">
    Find professional emails from name + company. Try it live.
  </Card>

  <Card title="Mobile Finder Playground" icon="phone" href="/v1/reference/mobile-finder">
    Discover direct mobile numbers for outreach campaigns.
  </Card>

  <Card title="Company Search Playground" icon="building" href="/v1/reference/company-search">
    Enrich company data by domain or LinkedIn URL.
  </Card>
</CardGroup>

## Why teams use LeadMagic

<Tabs>
  <Tab title="Transparent Pricing" icon="coins">
    ### Clear, usage-based credits

    | Service          | What You Get      | Cost      |
    | ---------------- | ----------------- | --------- |
    | Email Validation | **4 validations** | 1 credit  |
    | Email Finder     | 1 email found     | 1 credit  |
    | Profile Search   | 1 profile         | 1 credit  |
    | Mobile Finder    | 1 number          | 5 credits |

    <Tip>
      **Email Validation free results**: `unknown` results cost nothing — you only pay for `valid` and `invalid`. Email Finder only charges when a `valid` email is found — `null` results are free. Other endpoints only charge when data is found.
    </Tip>
  </Tab>

  <Tab title="Data Quality" icon="bullseye">
    ### High-signal enrichment

    * **99%+ email validation accuracy** with real-time SMTP verification
    * **Definitive results** — clear `valid`, `invalid`, or `unknown` statuses
    * **Real-time validation** at the moment of request
    * **Multiple data sources** cross-referenced for accuracy

    <Check>
      Use the API Playground to test result quality against your own data before
      integrating in production.
    </Check>
  </Tab>

  <Tab title="Easy Integration" icon="plug">
    ### Works Everywhere

    <CardGroup>
      <Card title="RESTful API" icon="code">
        Simple HTTP requests with JSON responses. Works with any language.
      </Card>

      <Card title="API Playground" icon="play">
        Test endpoints directly in your browser - no code needed.
      </Card>

      <Card title="Clay Integration" icon="shapes">
        Native integration - use LeadMagic in Clay workflows.
      </Card>

      <Card title="Zapier & Make" icon="bolt">
        No-code automation with popular platforms.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Quick Start

<Steps>
  <Step title="Get Your API Key" icon="key">
    [Sign up for free](https://app.leadmagic.io/sign-up) or [log in](https://app.leadmagic.io) and grab your API key from Settings > API.
  </Step>

  <Step title="Try the Playground" icon="play">
    Head to any [API Reference page](/docs/v1/reference/email-validation) and use the interactive playground to test endpoints with your key.
  </Step>

  <Step title="Integrate & Scale" icon="rocket">
    Copy the code examples and integrate into your application. Scale from 1 to 1 million enrichments.
  </Step>
</Steps>

<Card title="Explore Use Cases" icon="sparkles" href="/v1/use-cases">
  See common workflows for outbound prospecting, inbound enrichment, hiring intent, CRM cleanup, competitor research, and AI assistant automations.
</Card>

<Warning>
  **Don't have an account yet?** [Sign up now](https://app.leadmagic.io/sign-up)
  to get free credits and start testing immediately.
</Warning>

## Credit System

LeadMagic uses a flexible credit-based system. You only pay when we find data — `not_found` results are always free. Credits work across all services and never expire on paid plans.

<Tip>
  See [Credits & Pricing](/docs/v1/credits) for full cost breakdowns, subscription plans, and optimization tips.
</Tip>

## All API Products

<Tabs>
  <Tab title="People Data" icon="user">
    <CardGroup>
      <Card title="Email Validation" icon="envelope-circle-check" href="/v1/reference/email-validation">
        Verify emails with 99%+ accuracy. 4 per credit.
      </Card>

      <Card title="Email Finder" icon="magnifying-glass" href="/v1/reference/email-finder">
        Find work emails from name + company.
      </Card>

      <Card title="Mobile Finder" icon="phone" href="/v1/reference/mobile-finder">
        Get direct mobile numbers.
      </Card>

      <Card title="Profile Search" icon="user-magnifying-glass" href="/v1/reference/profile-search">
        Enrich with work history, education, skills.
      </Card>

      <Card title="Email to Profile" icon="id-card" href="/v1/reference/email-to-profile">
        Find professional profiles from email addresses.
      </Card>

      <Card title="Profile to Email" icon="at" href="/v1/reference/profile-to-email">
        Get work email from a profile URL.
      </Card>

      <Card title="Personal Email Finder" icon="envelope" href="/v1/reference/personal-email-finder">
        Find personal email addresses.
      </Card>

      <Card title="Role Finder" icon="user-tie" href="/v1/reference/role-finder">
        Find specific roles at companies.
      </Card>

      <Card title="People Search" icon="users" href="/v1/reference/people-search">
        Search employees and decision-makers with all people and company filters.
      </Card>

      <Card title="Job Change Detector" icon="arrow-right-arrow-left" href="/v1/reference/job-change-detector">
        Track when contacts change jobs.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Company Data" icon="building">
    <CardGroup>
      <Card title="Company Search" icon="building-magnifying-glass" href="/v1/reference/company-search">
        Enrich company data by domain or name.
      </Card>

      <Card title="Company Lookalike" icon="users-between-lines" href="/v1/reference/company-lookalike">
        Discover similar companies from a seed account.
      </Card>

      <Card title="Company Funding" icon="money-bill-trend-up" href="/v1/reference/company-funding">
        Access funding rounds and investor data.
      </Card>

      <Card title="Technographics" icon="microchip" href="/v1/reference/technographics">
        Identify tech stacks companies use.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Jobs & Ads" icon="briefcase">
    <CardGroup>
      <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
        Search job listings across industries.
      </Card>

      <Card title="Google Ads Search" icon="magnifying-glass-chart" href="/v1/reference/google-ads-search">
        Analyze competitor search ads.
      </Card>

      <Card title="Meta Ads Search" icon="rectangle-ad" href="/v1/reference/meta-ads-search">
        Research social media ads.
      </Card>

      <Card title="B2B Ads Search" icon="rectangle-ad" href="/v1/reference/b2b-ads-search">
        B2B advertising intelligence.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Platform Integrations

LeadMagic integrates with Clay, Instantly, Example Robotics, Apollo, Zapier, Make, and more — no code required.

<Tip>
  See the [Integrations](/docs/v1/integrations) page for step-by-step setup instructions for each platform.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Quickstart Guide" icon="bolt" href="/v1/quickstart">
    Make your first API call in under 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/v1/authentication">
    API key setup, security best practices, and key rotation.
  </Card>

  <Card title="Credits & Pricing" icon="coins" href="/v1/credits">
    Understand costs, subscription plans, and optimization tips.
  </Card>

  <Card title="API Reference" icon="code" href="/v1/reference/introduction">
    Full endpoint reference with interactive playgrounds.
  </Card>
</CardGroup>


# Making API Calls
Source: https://leadmagic.io/docs/v1/making-api-calls

Learn how to integrate LeadMagic's Data Enrichment API into your applications

This guide covers request format, rate limits, and error handling for the LeadMagic API. If you haven't made your first call yet, start with the [Quickstart](/docs/v1/quickstart).

## Request Format

All API requests should:

<CardGroup>
  <Card title="Use POST Method" icon="paper-plane">
    All enrichment endpoints use HTTP POST requests with JSON body.
  </Card>

  <Card title="Include Headers" icon="heading">
    Set `Content-Type: application/json` and `X-API-Key` headers.
  </Card>

  <Card title="Send JSON Body" icon="brackets-curly">
    Request parameters go in the JSON body, not query string.
  </Card>

  <Card title="Handle Responses" icon="reply">
    Parse JSON responses and check the `status` field.
  </Card>
</CardGroup>

## Base URL

<Note>
  All API requests should be made to `https://api.leadmagic.io`.
</Note>

## Rate Limits

<Note>
  Rate limits are subject to change. Need higher throughput? Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
</Note>

| Endpoint              | Rate Limit |
| --------------------- | ---------- |
| Email Validation      | 300/min    |
| Email Finder          | 300/min    |
| Personal Email Finder | 300/min    |
| Profile to Email      | 300/min    |
| Profile Search        | 100/min    |
| Email to Profile      | 300/min    |
| Mobile Finder         | 300/min    |
| Job Change Detector   | 300/min    |
| Role Finder           | 300/min    |
| People Search         | 300/min    |
| Company Search        | 500/min    |
| Company Funding       | 300/min    |
| Company Lookalike     | 500/min    |
| Technographics        | 300/min    |
| Jobs Finder           | 100/min    |
| Google Ads Search     | 300/min    |
| Meta Ads Search       | 300/min    |
| B2B Ads Search        | 300/min    |
| B2B Ad Details        | 300/min    |
| Analytics (all)       | No limit   |

Every response includes rate limit headers:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 42
X-Credits-Remaining: 15432.50
X-Credits-Cost: 1
```

<Tip>
  See our [Developer Experience](/docs/v1/developer-experience) guide for complete header documentation and monitoring best practices.
</Tip>

## Error Handling

LeadMagic uses [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) for standardized error responses:

| Code  | Description         | Common Causes                                    |
| ----- | ------------------- | ------------------------------------------------ |
| `200` | Success             | Request completed successfully                   |
| `400` | Bad Request         | Invalid parameters, malformed JSON               |
| `401` | Unauthorized        | Missing or invalid API key                       |
| `402` | Payment Required    | Insufficient credits                             |
| `404` | Not Found           | Profile or resource not found                    |
| `429` | Too Many Requests   | Rate limit exceeded (check `Retry-After` header) |
| `500` | Server Error        | Temporary issue - retry with backoff             |
| `502` | Bad Gateway         | External service error                           |
| `503` | Service Unavailable | Service temporarily down                         |

<Accordion title="Example Error Response">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "success": false,
    "errors": [{
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": ["email"],
      "detail": "Email format is invalid",
      "action": "Provide a valid email address in the 'email' field",
      "docs": "https://leadmagic.io/docs/v1/making-api-calls"
    }],
    "meta": {
      "request_id": "req_abc123",
      "timestamp": "2026-10-01T12:00:00.000Z"
    }
  }
  ```
</Accordion>

<Info>
  Every error includes a `request_id` for debugging, suggested `action` to resolve, and link to relevant `docs`.
</Info>

## Security

<Tip>
  See the [Authentication](/docs/v1/authentication) guide for API key security best practices, including environment variables, server-side usage, and key rotation.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Developer Experience" icon="code" href="/v1/developer-experience">
    Comprehensive guide to headers, analytics, error handling, and best practices.
  </Card>

  <Card title="Authentication Details" icon="key" href="/v1/authentication">
    Learn more about API authentication and security.
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/v1/reference/analytics">
    Monitor your usage with real-time dashboards and detailed metrics.
  </Card>

  <Card title="Email Validation" icon="envelope-circle-check" href="/v1/reference/email-validation">
    Start validating emails with our most popular endpoint.
  </Card>
</CardGroup>


# Quickstart
Source: https://leadmagic.io/docs/v1/quickstart

Make your first API call in under 5 minutes

Get started with LeadMagic in minutes. This guide walks you through making your first API call and exploring our interactive playground.

<Note>
  **Fastest way to start**: Skip the code and use our [API
  Playground](/docs/v1/reference/email-validation) - test any endpoint directly in
  your browser!
</Note>

## Step 1: Get Your API Key

<Steps>
  <Step title="Create an account">
    [Sign up for free](https://app.leadmagic.io/sign-up) or [log in](https://app.leadmagic.io) if you already have an account.
  </Step>

  <Step title="Navigate to API Settings">
    Go to [Settings > API](https://app.leadmagic.io/settings/api) in your dashboard.
  </Step>

  <Step title="Copy your API key">
    Click the copy button to copy your API key to clipboard.

    <Warning>
      Keep your API key secret. Never expose it in client-side code or public repositories.
    </Warning>
  </Step>
</Steps>

## Step 2: Try the API Playground

The fastest way to test LeadMagic is our interactive API Playground. No code required!

<CardGroup>
  <Card title="Email Validation" icon="envelope-circle-check" href="/v1/reference/email-validation">
    Verify an email address instantly.
  </Card>

  <Card title="Email Finder" icon="magnifying-glass" href="/v1/reference/email-finder">
    Find an email from name + company.
  </Card>
</CardGroup>

### How to Use the Playground

<Steps>
  <Step title="Go to any API Reference page">
    Click any endpoint in the sidebar or the cards above.
  </Step>

  <Step title="Enter your API key">
    Paste your API key in the authentication section.
  </Step>

  <Step title="Fill in the parameters">
    Enter test data (e.g., an email to validate).
  </Step>

  <Step title="Click 'Send'">See the live response immediately!</Step>
</Steps>

<Tip>
  The playground shows you exactly what your code will return - perfect for
  testing before integration.
</Tip>

## Step 3: Make Your First API Call

Ready to integrate? Here's how to call the API from your code:

<Tabs>
  <Tab title="cURL" icon="terminal">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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@leadmagic.io"}'
    ```
  </Tab>

  <Tab title="JavaScript" icon="js">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.LEADMAGIC_API_KEY
      },
      body: JSON.stringify({ email: 'test@leadmagic.io' })
    });

    const data = await response.json();
    console.log(data.email_status); // "valid", "invalid", or "unknown"
    ```
  </Tab>

  <Tab title="Python" icon="python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import requests
    import os

    response = requests.post(
        'https://api.leadmagic.io/v1/people/email-validation',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['LEADMAGIC_API_KEY']
        },
        json={'email': 'test@leadmagic.io'}
    )

    data = response.json()
    print(data['email_status'])  # "valid", "invalid", or "unknown"
    ```
  </Tab>
</Tabs>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "email_status": "valid",
  "email": "test@leadmagic.io",
  "domain": "leadmagic.io",
  "credits_consumed": 0.25,
  "company": {
    "name": "LeadMagic",
    "domain": "leadmagic.io",
    "linkedin_url": "https://linkedin.com/company/leadmagichq"
  }
}
```

<Check>
  **Bonus**: Every email validation includes free company enrichment data!
</Check>

## Step 4: Explore More Endpoints

Now that you've made your first call, explore other powerful endpoints:

<CardGroup>
  <Card title="Find Emails" icon="magnifying-glass" href="/v1/reference/email-finder">
    Get professional emails from name + company domain.
  </Card>

  <Card title="Find Mobile Numbers" icon="phone" href="/v1/reference/mobile-finder">
    Discover direct mobile numbers for outreach.
  </Card>

  <Card title="Enrich Profiles" icon="user" href="/v1/reference/profile-search">
    Get complete professional profiles with work history.
  </Card>

  <Card title="Search Companies" icon="building" href="/v1/reference/company-search">
    Enrich company data by domain or name.
  </Card>
</CardGroup>

<Tip>
  These are our most popular endpoints. See [Use Cases](/docs/v1/use-cases) for workflow ideas, or the full [API Reference](/docs/v1/reference/introduction) for all endpoints across email, contact, people, company, jobs, and ads data.
</Tip>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Clean Your Email List" icon="broom">
    **Goal**: Remove invalid emails before a campaign

    1. Loop through your email list
    2. Call [Email Validation](/docs/v1/reference/email-validation) for each
    3. Keep only `valid` emails
    4. Remove `invalid`, skip `unknown` (free, retry later)

    **Result**: Higher deliverability, protected sender reputation
  </Accordion>

  <Accordion title="Build a Prospect List" icon="list-check">
    **Goal**: Get contact info for target accounts

    1. Start with company domains
    2. Use [Role Finder](/docs/v1/reference/role-finder) to find decision-makers
    3. Use [Email Finder](/docs/v1/reference/email-finder) for work emails
    4. Use [Mobile Finder](/docs/v1/reference/mobile-finder) for phone numbers

    **Result**: Complete contact list for outreach
  </Accordion>

  <Accordion title="Enrich CRM Data" icon="database">
    **Goal**: Fill in missing CRM fields

    1. Export contacts with LinkedIn URLs
    2. Use [Profile Search](/docs/v1/reference/profile-search) for full profiles
    3. Use [Company Search](/docs/v1/reference/company-search) for company data
    4. Import enriched data back to CRM

    **Result**: Rich CRM data for better personalization
  </Accordion>
</AccordionGroup>

<Card title="More Use Cases" icon="sparkles" href="/v1/use-cases">
  Browse outbound, inbound, CRM cleanup, hiring intent, market research, MCP, and bulk enrichment workflows.
</Card>

## What's Next?

<CardGroup>
  <Card title="Making API Calls" icon="code" href="/v1/making-api-calls">
    Production request patterns, status codes, and retries.
  </Card>

  <Card title="Authentication Guide" icon="key" href="/v1/authentication">
    Secure API key usage and key rotation best practices.
  </Card>

  <Card title="Developer Experience" icon="terminal" href="/v1/developer-experience">
    Headers, observability, error handling, and analytics endpoints.
  </Card>

  <Card title="API Playground" icon="play" href="/v1/reference/email-validation">
    Test any endpoint interactively.
  </Card>
</CardGroup>


# Analytics API
Source: https://leadmagic.io/docs/v1/reference/analytics

get /v1/analytics/dashboard
Monitor your API usage with comprehensive analytics endpoints

# Usage Analytics

Get detailed insights into your API usage, credit consumption, and performance metrics. All analytics endpoints are **free** and don't consume credits.

<Info>
  **100% Free:** All analytics endpoints consume zero credits and have no rate limits. Use them to build dashboards, monitoring systems, and usage alerts.
</Info>

## Quick Reference

| Endpoint                  | Method | Description                | Best For                       |
| ------------------------- | ------ | -------------------------- | ------------------------------ |
| `/v1/analytics/dashboard` | GET    | Real-time account status   | Live dashboards, health checks |
| `/v1/analytics/usage`     | GET    | Daily usage summary        | Weekly/monthly reports         |
| `/v1/analytics/products`  | GET    | Per-product breakdown      | Cost optimization              |
| `/v1/analytics/credits`   | GET    | Credit consumption history | Spend tracking                 |
| `/v1/analytics/summary`   | GET    | All-time statistics        | Account overview               |
| `/v1/analytics/daily`     | GET    | Daily performance metrics  | SLA monitoring                 |
| `/v1/analytics/day/:date` | GET    | Single day breakdown       | Debugging, audits              |

***

## Dashboard

Get a real-time snapshot of your account status including credits, rate limits, and usage statistics.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/dashboard
```

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v1/analytics/dashboard' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const dashboard = await response.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v1/analytics/dashboard',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  dashboard = response.json()
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  req, _ := http.NewRequest("GET", "https://api.leadmagic.io/v1/analytics/dashboard", nil)
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "user": {
    "id": "user_abc123",
    "email": "developer@leadmagic.io"
  },
  "credits": {
    "current": 15432.50,
    "formatted": "$154.33"
  },
  "rate_limit": {
    "minute": {
      "limit": 300,
      "used": 45,
      "remaining": 255,
      "utilization": 15.0
    },
    "daily": {
      "limit": 500000,
      "used": 12500,
      "remaining": 487500,
      "utilization": 2.5
    }
  },
  "concurrency": {
    "current": 0,
    "peak": 23,
    "active_reservations": 0
  },
  "stats": {
    "today": {
      "requests": 1250,
      "credits": 875.50,
      "chargeable_requests": 1100,
      "chargeable_rate": 88.0,
      "unique_products": 5
    },
    "this_week": {
      "requests": 8500,
      "credits": 5200.25,
      "chargeable_requests": 7200,
      "chargeable_rate": 84.7,
      "unique_products": 8
    },
    "this_month": {
      "requests": 45000,
      "credits": 28500.00,
      "chargeable_requests": 38000,
      "chargeable_rate": 84.4,
      "unique_products": 12
    }
  }
}
```

### Response Fields

<ResponseField name="user" type="object">
  Your account information

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user identifier</ResponseField>
    <ResponseField name="email" type="string">Account email address</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="credits" type="object">
  Current credit balance

  <Expandable title="properties">
    <ResponseField name="current" type="number">Raw credit balance (1 credit = \$0.01)</ResponseField>
    <ResponseField name="formatted" type="string">Human-readable dollar value</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rate_limit" type="object">
  Real-time rate limit status

  <Expandable title="properties">
    <ResponseField name="minute.limit" type="number">Requests per minute allowed</ResponseField>
    <ResponseField name="minute.used" type="number">Requests used this minute</ResponseField>
    <ResponseField name="minute.remaining" type="number">Requests remaining this minute</ResponseField>
    <ResponseField name="minute.utilization" type="number">Percentage of limit used (0-100)</ResponseField>
    <ResponseField name="daily.limit" type="number">Requests per day allowed</ResponseField>
    <ResponseField name="daily.used" type="number">Requests used today</ResponseField>
    <ResponseField name="daily.remaining" type="number">Requests remaining today</ResponseField>
    <ResponseField name="daily.utilization" type="number">Percentage of daily limit used</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="concurrency" type="object">
  Concurrent request tracking

  <Expandable title="properties">
    <ResponseField name="current" type="number">Currently in-flight requests</ResponseField>
    <ResponseField name="peak" type="number">Peak concurrent requests (session)</ResponseField>
    <ResponseField name="active_reservations" type="number">Credit reservations pending</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object">
  Usage statistics for today, this week, and this month

  <Expandable title="properties">
    <ResponseField name="requests" type="number">Total API requests</ResponseField>
    <ResponseField name="credits" type="number">Total credits consumed</ResponseField>
    <ResponseField name="chargeable_requests" type="number">Requests that consumed credits</ResponseField>
    <ResponseField name="chargeable_rate" type="number">Percentage of requests charged</ResponseField>
    <ResponseField name="unique_products" type="number">Number of different endpoints used</ResponseField>
  </Expandable>
</ResponseField>

***

## Usage Summary

Get aggregated usage metrics over a time period with daily breakdown.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/usage?days=30
```

<ParamField type="number">
  Number of days to include (1-90)
</ParamField>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "total_credits": 28500.00,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4,
    "unique_products": 12
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "chargeable_requests": 1100,
      "total_credits": 875.50,
      "unique_products_used": 5
    }
  ]
}
```

<Tip>
  **Chargeable Rate** shows what percentage of your requests consumed credits. A lower rate means more free results (unknown validations, not-found responses, etc.).
</Tip>

***

## Products Breakdown

Get per-product usage with requests, credits, and success rates. Essential for cost optimization.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/products?days=30
```

<ParamField type="number">
  Number of days to include (1-90)
</ParamField>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "products": {
    "email_validation": {
      "total_requests": 20000,
      "total_credits": 5000.00,
      "successful_requests": 19500,
      "failed_requests": 500,
      "success_rate": 97.5,
      "avg_credits_per_request": 0.25
    },
    "email_finder": {
      "total_requests": 10000,
      "total_credits": 8500.00,
      "successful_requests": 8500,
      "failed_requests": 1500,
      "success_rate": 85.0,
      "avg_credits_per_request": 0.85
    }
  },
  "daily": [...]
}
```

<Warning>
  **Success rate** means we found data. For email finder, 85% success means 85% of lookups returned an email. You only pay for successful results.
</Warning>

***

## Credit History

Get credit consumption history with daily breakdown. Perfect for spend tracking and budgeting.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/credits?days=30
```

<ParamField type="number">
  Number of days to include (1-90)
</ParamField>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_credits": 28500.00,
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_credits": 875.50,
      "total_requests": 1250,
      "chargeable_requests": 1100
    }
  ]
}
```

***

## All-Time Summary

Get lifetime statistics for your account, or specify a custom date range.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/summary
GET /v1/analytics/summary?start_date=2026-10-01&end_date=2026-11-01
```

<ParamField type="string">
  Start date (YYYY-MM-DD format). Optional.
</ParamField>

<ParamField type="string">
  End date (YYYY-MM-DD format). Optional.
</ParamField>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_api_requests": 1250000,
  "total_credits_consumed": 425000.50,
  "unique_products_used": 15,
  "successful_requests": 1150000,
  "failed_requests": 100000,
  "success_rate": 92.0,
  "avg_response_time_ms": 245,
  "first_request": "2023-06-15T10:30:00.000Z",
  "last_request": "2026-11-01T14:22:00.000Z"
}
```

***

## Daily Metrics

Get detailed daily metrics including latency percentiles and error rates. Essential for SLA monitoring.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/daily?days=30
```

<ParamField type="number">
  Number of days to include (1-90)
</ParamField>

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "data": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "successful_requests": 1175,
      "failed_requests": 75,
      "total_credits": 875.50,
      "p50_latency_ms": 180,
      "p95_latency_ms": 450,
      "p99_latency_ms": 890,
      "error_rate": 6.0
    }
  ]
}
```

### Latency Percentiles

| Metric           | Description                            |
| ---------------- | -------------------------------------- |
| `p50_latency_ms` | Median response time (50th percentile) |
| `p95_latency_ms` | 95% of requests faster than this       |
| `p99_latency_ms` | 99% of requests faster than this       |

***

## Day Breakdown

Get per-product breakdown for a specific day. Perfect for debugging and audits.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/analytics/day/2026-11-01
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "date": "2026-11-01",
  "summary": {
    "total_credits": 875.50,
    "total_requests": 1250,
    "products_count": 8
  },
  "products": [
    {
      "product_id": "email_validation",
      "requests": 500,
      "credits": 125.00,
      "credits_percentage": 14.29,
      "avg_credits_per_request": 0.25,
      "max_credits": 0.25
    },
    {
      "product_id": "email_finder",
      "requests": 350,
      "credits": 297.50,
      "credits_percentage": 34.00,
      "avg_credits_per_request": 0.85,
      "max_credits": 1.00
    }
  ]
}
```

***

## Practical Examples

<Tabs>
  <Tab title="Monitoring Dashboard" icon="chart-line">
    ### Build a Real-Time Dashboard

    Fetch all metrics in parallel for a comprehensive dashboard:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const headers = { 'X-API-Key': process.env.LEADMAGIC_API_KEY };

    async function getDashboardMetrics() {
      const [dashboard, usage, products, daily] = await Promise.all([
        fetch('https://api.leadmagic.io/v1/analytics/dashboard', { headers }),
        fetch('https://api.leadmagic.io/v1/analytics/usage?days=7', { headers }),
        fetch('https://api.leadmagic.io/v1/analytics/products?days=7', { headers }),
        fetch('https://api.leadmagic.io/v1/analytics/daily?days=7', { headers })
      ]).then(responses => Promise.all(responses.map(r => r.json())));
      
      return {
        // Account health
        credits: dashboard.data.credits.current,
        creditsFormatted: dashboard.data.credits.formatted,
        
        // Rate limits
        minuteUtilization: dashboard.data.rate_limit.minute.utilization,
        dailyUtilization: dashboard.data.rate_limit.daily.utilization,
        
        // Weekly stats
        weeklyRequests: usage.data.summary.total_requests,
        weeklyCredits: usage.data.summary.total_credits,
        chargeableRate: usage.data.summary.chargeable_rate,
        
        // Top products by spend
        topProducts: Object.entries(products.data.products)
          .sort((a, b) => b[1].total_credits - a[1].total_credits)
          .slice(0, 5),
        
        // Performance
        avgLatency: daily.data.data.reduce((sum, d) => sum + d.p50_latency_ms, 0) / daily.data.data.length,
        avgErrorRate: daily.data.data.reduce((sum, d) => sum + d.error_rate, 0) / daily.data.data.length
      };
    }
    ```
  </Tab>

  <Tab title="Alerting" icon="bell">
    ### Set Up Usage Alerts

    Monitor credits and rate limits to prevent service interruptions:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    async function checkAndAlert() {
      const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
        headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
      });
      const { data } = await response.json();
      
      const alerts = [];
      
      // Credit alerts
      if (data.credits.current < 100) {
        alerts.push({
          level: 'critical',
          message: `Credits critically low: ${data.credits.formatted}`
        });
      } else if (data.credits.current < 1000) {
        alerts.push({
          level: 'warning', 
          message: `Credits running low: ${data.credits.formatted}`
        });
      }
      
      // Rate limit alerts
      if (data.rate_limit.daily.utilization > 90) {
        alerts.push({
          level: 'warning',
          message: `Daily rate limit at ${data.rate_limit.daily.utilization}%`
        });
      }
      
      if (data.rate_limit.minute.utilization > 80) {
        alerts.push({
          level: 'warning',
          message: `Minute rate limit at ${data.rate_limit.minute.utilization}%`
        });
      }
      
      // Send alerts via Slack, email, PagerDuty, etc.
      for (const alert of alerts) {
        await sendAlert(alert);
      }
      
      return alerts;
    }

    // Run every 5 minutes
    setInterval(checkAndAlert, 5 * 60 * 1000);
    ```
  </Tab>

  <Tab title="Cost Optimization" icon="coins">
    ### Analyze and Optimize Spending

    Identify which products consume the most credits:

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import requests

    def analyze_spending():
        headers = {'X-API-Key': 'YOUR_API_KEY'}
        
        # Get last 30 days of product usage
        response = requests.get(
            'https://api.leadmagic.io/v1/analytics/products?days=30',
            headers=headers
        )
        data = response.json()['data']
        
        # Calculate cost breakdown
        products = data['products']
        total_credits = sum(p['total_credits'] for p in products.values())
        
        print(f"Total spend: ${total_credits * 0.01:.2f}")
        print("\nBreakdown by product:")
        
        for product_id, stats in sorted(
            products.items(), 
            key=lambda x: x[1]['total_credits'], 
            reverse=True
        ):
            percentage = (stats['total_credits'] / total_credits) * 100
            cost = stats['total_credits'] * 0.01
            
            print(f"  {product_id}:")
            print(f"    Requests: {stats['total_requests']:,}")
            print(f"    Credits: {stats['total_credits']:,.2f} ({percentage:.1f}%)")
            print(f"    Cost: ${cost:.2f}")
            print(f"    Success rate: {stats['success_rate']}%")
            print(f"    Avg per request: {stats['avg_credits_per_request']:.3f}")
            print()
    ```
  </Tab>

  <Tab title="SLA Monitoring" icon="gauge">
    ### Track Performance SLAs

    Monitor latency and error rates against your SLA targets:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const SLA_TARGETS = {
      p95_latency_ms: 1000,  // 1 second
      p99_latency_ms: 2000,  // 2 seconds
      error_rate: 5.0        // 5%
    };

    async function checkSLA() {
      const response = await fetch(
        'https://api.leadmagic.io/v1/analytics/daily?days=7',
        { headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY } }
      );
      const { data } = await response.json();
      
      const violations = [];
      
      for (const day of data.data) {
        if (day.p95_latency_ms > SLA_TARGETS.p95_latency_ms) {
          violations.push({
            date: day.date,
            metric: 'p95_latency',
            value: day.p95_latency_ms,
            target: SLA_TARGETS.p95_latency_ms
          });
        }
        
        if (day.error_rate > SLA_TARGETS.error_rate) {
          violations.push({
            date: day.date,
            metric: 'error_rate',
            value: day.error_rate,
            target: SLA_TARGETS.error_rate
          });
        }
      }
      
      return {
        period: data.period,
        violations,
        slaCompliant: violations.length === 0
      };
    }
    ```
  </Tab>
</Tabs>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Cache dashboard responses" icon="database">
    Analytics endpoints are free, but caching improves your dashboard performance:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    let cache = { data: null, timestamp: 0 };
    const CACHE_TTL = 60 * 1000; // 1 minute

    async function getCachedDashboard() {
      if (cache.data && Date.now() - cache.timestamp < CACHE_TTL) {
        return cache.data;
      }
      
      const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
        headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
      });
      
      cache = { data: await response.json(), timestamp: Date.now() };
      return cache.data;
    }
    ```
  </Accordion>

  <Accordion title="Use response headers instead" icon="heading">
    Every API response includes `X-Credits-Remaining` — use this instead of polling the dashboard:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
      method: 'POST',
      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'test@example.com' })
    });

    const creditsRemaining = response.headers.get('X-Credits-Remaining');
    const requestId = response.headers.get('X-Request-Id');

    console.log(`Credits after request: ${creditsRemaining}`);
    ```
  </Accordion>

  <Accordion title="Batch analytics calls" icon="layer-group">
    Fetch multiple analytics endpoints in parallel:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const [dashboard, products, daily] = await Promise.all([
      fetch('/v1/analytics/dashboard', { headers }),
      fetch('/v1/analytics/products?days=30', { headers }),
      fetch('/v1/analytics/daily?days=30', { headers })
    ]).then(responses => Promise.all(responses.map(r => r.json())));
    ```
  </Accordion>

  <Accordion title="Set up regular reporting" icon="calendar">
    Schedule weekly reports using cron or serverless functions:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // Weekly summary report
    async function generateWeeklyReport() {
      const [usage, products] = await Promise.all([
        fetch('/v1/analytics/usage?days=7', { headers }).then(r => r.json()),
        fetch('/v1/analytics/products?days=7', { headers }).then(r => r.json())
      ]);
      
      return {
        period: usage.data.period,
        totalRequests: usage.data.summary.total_requests,
        totalCredits: usage.data.summary.total_credits,
        topProducts: Object.entries(products.data.products)
          .sort((a, b) => b[1].total_credits - a[1].total_credits)
          .slice(0, 5)
          .map(([id, stats]) => ({ id, ...stats }))
      };
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="Check Credits" icon="coins" href="/v1/reference/check-credits">
    Simple endpoint to check your current balance.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/v1/making-api-calls#rate-limits">
    Learn about rate limiting and how to stay within limits.
  </Card>
</CardGroup>


# B2B Ad Details
Source: https://leadmagic.io/docs/v1/reference/b2b-ad-details

post /v1/ads/b2b-ads-details
Get detailed information about a specific B2B advertisement using its URL.

# B2B Ad Details

Get detailed information about a specific B2B professional network advertisement. Includes full creative content, video data, targeting, and performance metrics.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                    |
    | -------------- | ------------------------ |
    | **Cost**       | **2 credits** per ad     |
    | **No Results** | **FREE** if ad not found |

    <Tip>
      Use the ad ID from [B2B Ads Search](/docs/v1/reference/b2b-ads-search) to get complete details.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/ads/b2b-ads-details' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"ad_url": "https://www.linkedin.com/ad-library/detail/633872143"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/ads/b2b-ads-details', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ad_url: 'https://www.linkedin.com/ad-library/detail/633872143'
    })
  });
  const data = await response.json();
  console.log(`Ad headline: ${data.headline}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/ads/b2b-ads-details',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'ad_url': 'https://www.linkedin.com/ad-library/detail/633872143'}
  )
  data = response.json()
  print(f"Ad headline: {data.get('headline', 'N/A')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  The Ad Library URL or ID (from B2B Ads Search).
</ParamField>

<Tip>
  Get the `ad_url` from the `link` field in [B2B Ads Search](/docs/v1/reference/b2b-ads-search) results.
</Tip>

***

## Response

<ResponseField name="ad_id" type="string">
  Ad identifier
</ResponseField>

<ResponseField name="headline" type="string">
  Ad headline
</ResponseField>

<ResponseField name="content" type="string">
  Full ad copy
</ResponseField>

<ResponseField name="advertiser" type="object">
  Advertiser company info (name, profile URL)
</ResponseField>

<ResponseField name="creative" type="object">
  Creative assets (images, videos)
</ResponseField>

<ResponseField name="targeting" type="object">
  Targeting criteria (if available)
</ResponseField>

<ResponseField name="started_running" type="string">
  When ad started
</ResponseField>

<ResponseField name="impressions" type="object">
  Impression range (if available)
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (2 if found, 0 if not)
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "ad_id": "633872143",
  "headline": "Transform your sales with AI",
  "content": "Our platform helps sales teams close more deals with AI-powered insights...",
  "advertiser": {
    "name": "LeadMagic",
    "profile_url": "linkedin.com/company/leadmagichq"
  },
  "creative": {
    "image_url": "https://...",
    "video_url": null,
    "format": "single_image"
  },
  "targeting": {
    "locations": ["United States", "Canada"],
    "industries": ["Technology", "Finance"]
  },
  "started_running": "2026-01-15",
  "impressions": {
    "min": 10000,
    "max": 50000
  },
  "credits_consumed": 2,
  "message": "Ad details found."
}
```

***

## Success Messages

| Message             | Meaning                     | Cost      |
| ------------------- | --------------------------- | --------- |
| `Ad details found.` | Full ad data returned       | 2 credits |
| `Ad not found.`     | Ad doesn't exist or expired | FREE      |

***

## Workflow

<Steps>
  <Step title="Search for Ads">
    Use [B2B Ads Search](/docs/v1/reference/b2b-ads-search) to find ads for a company.
  </Step>

  <Step title="Get Ad IDs">
    Extract the `link` field from search results.
  </Step>

  <Step title="Fetch Details">
    Use this endpoint to get full creative and targeting data.
  </Step>

  <Step title="Analyze">
    Study messaging, targeting, and creative approaches.
  </Step>
</Steps>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Batch strategically" icon="layer-group">
    Only fetch details for the most relevant ads from search results.
  </Accordion>

  <Accordion title="Study targeting" icon="bullseye">
    Targeting data reveals which audiences competitors prioritize.
  </Accordion>

  <Accordion title="Download video content" icon="video">
    Video URLs allow you to analyze video ad creative in detail.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Creative Analysis" icon="palette">
    Study complete ad creative including video content.
  </Card>

  <Card title="Targeting Intelligence" icon="bullseye">
    Understand competitor audience targeting strategies.
  </Card>

  <Card title="Performance Benchmarks" icon="chart-bar">
    Use impression data to benchmark ad performance.
  </Card>

  <Card title="Competitive Reports" icon="file-lines">
    Build detailed competitive advertising reports.
  </Card>
</CardGroup>


# B2B Search Ads
Source: https://leadmagic.io/docs/v1/reference/b2b-ads-search

post /v1/ads/b2b-ads-search
Search for B2B ads by company domain or name.

# B2B Ads

Search for B2B professional network ads run by a company. Perfect for understanding B2B advertising strategies and competitive positioning.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric          | Value                      |
    | --------------- | -------------------------- |
    | **Cost**        | **0.2 credits** per search |
    | **Calculation** | 5 searches = 1 credit      |
    | **No Results**  | **FREE** if no ads found   |

    <Tip>
      Very cost-effective for B2B ad intelligence at just 0.2 credits per search.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/ads/b2b-ads-search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"company_domain": "leadmagic.io"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/ads/b2b-ads-search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_domain: 'leadmagic.io' })
  });
  const data = await response.json();
  console.log(`Found ${data.ads?.length || 0} B2B ads`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/ads/b2b-ads-search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'company_domain': 'leadmagic.io'}
  )
  data = response.json()
  print(f"Found {len(data.get('ads', []))} B2B ads")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Company website domain (preferred).
</ParamField>

<ParamField type="string">
  Company name.
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` (or both).
</Warning>

***

## Response

<ResponseField name="company_name" type="string">
  Company searched
</ResponseField>

<ResponseField name="ads" type="array">
  Array of ad creatives
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (0.2 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Ad Object

| Field       | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| `content`   | string | Ad copy/headline                        |
| `link`      | string | Ad Library ID (use with B2B Ad Details) |
| `image_url` | string | Ad image URL                            |

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "company_name": "Example CRM",
  "ads": [
    {
      "content": "Transform your business with the #1 CRM",
      "link": "633872143",
      "image_url": "https://..."
    }
  ],
  "credits_consumed": 0.2,
  "message": "Ads found."
}
```

***

## Success Messages

| Message                          | Meaning               | Cost        |
| -------------------------------- | --------------------- | ----------- |
| `Ads found.`                     | B2B Ads data returned | 0.2 credits |
| `No ads found for this company.` | No B2B Ads found      | FREE        |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Get full ad details" icon="expand">
    Use the `link` field with [B2B Ad Details](/docs/v1/reference/b2b-ad-details) for complete creative data.
  </Accordion>

  <Accordion title="Analyze B2B messaging" icon="message">
    B2B ads reveal competitor positioning and value propositions.
  </Accordion>

  <Accordion title="See how target accounts advertise" icon="building">
    Understand how your prospects market to their customers.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Competitive Intelligence" icon="binoculars">
    Monitor competitor B2B advertising strategies.
  </Card>

  <Card title="Messaging Research" icon="message">
    Study B2B value propositions and positioning.
  </Card>

  <Card title="Account Research" icon="building">
    See how target accounts advertise to their customers.
  </Card>

  <Card title="Market Analysis" icon="chart-line">
    Analyze B2B advertising trends in your industry.
  </Card>
</CardGroup>


# Check Credits
Source: https://leadmagic.io/docs/v1/reference/check-credits

get /v1/credits
Check your current credit balance.

# Credit Balance

Monitor your credit balance programmatically. Use this endpoint to:

* Track usage across your applications
* Set up alerts before running low
* Build internal dashboards

<Info>
  This endpoint is **FREE** - no credits consumed and no rate limiting applied.
</Info>

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v1/credits' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/credits', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const { credits } = await response.json();
  console.log(`Available: ${credits} credits`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v1/credits',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  print(f"Credits: {response.json()['credits']}")
  ```
</CodeGroup>

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "credits": 15432.50
}
```

## Response Fields

| Field     | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `credits` | number | Your current credit balance |

## Additional Endpoints

| Endpoint                   | Method | Description                                                      |
| -------------------------- | ------ | ---------------------------------------------------------------- |
| `GET /v1/credits`          | GET    | Get current credit balance                                       |
| `POST /v1/credits/refresh` | POST   | Force refresh credits from database (use if balance seems stale) |
| `GET /v1/credits/health`   | GET    | Validate API key and check authentication status                 |

## Best Practices

<AccordionGroup>
  <Accordion title="Cache the response" icon="database">
    Don't call this endpoint before every API request. Cache the balance and refresh periodically (e.g., every 5 minutes).

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    let cachedCredits = null;
    let lastFetch = 0;
    const CACHE_TTL = 60000; // 1 minute

    async function getCredits() {
      if (cachedCredits && Date.now() - lastFetch < CACHE_TTL) {
        return cachedCredits;
      }

      const response = await fetch('https://api.leadmagic.io/v1/credits', {
        headers: { 'X-API-Key': apiKey }
      });

      const { credits } = await response.json();
      cachedCredits = credits;
      lastFetch = Date.now();
      return credits;
    }
    ```
  </Accordion>

  <Accordion title="Use response headers instead" icon="heading">
    Every API response includes `X-Credits-Remaining` header - use this instead of making a separate call:

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(endpoint, options);
    const creditsRemaining = response.headers.get('X-Credits-Remaining');
    console.log(`Credits after request: ${creditsRemaining}`);
    ```
  </Accordion>

  <Accordion title="Set up alerts" icon="bell">
    Implement alerts when credits fall below a threshold to avoid service interruptions.

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const { credits } = await checkCredits();

    if (credits < 100) {
      sendCriticalAlert('CRITICAL: Credits below 100!');
    } else if (credits < 1000) {
      sendWarning('Low credit balance: ' + credits);
    }
    ```
  </Accordion>
</AccordionGroup>

## Need More Analytics?

For comprehensive usage analytics, see our [Analytics API](/docs/v1/reference/analytics) which includes:

* Real-time dashboard with rate limits and usage stats
* Daily and monthly credit consumption history
* Per-product breakdown with success rates
* Latency percentiles and error tracking

<Card title="Analytics API" icon="chart-line" href="/v1/reference/analytics">
  Get detailed insights into your API usage with our comprehensive analytics suite.
</Card>


# Company Funding
Source: https://leadmagic.io/docs/v1/reference/company-funding

post /v1/companies/company-funding
Provide the Company Domain or Company Name and get back the complete funding details of the company.

# Company Funding

Discover comprehensive funding data for companies including investment rounds, funding amounts, investor information, and leadership details.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                             |
    | -------------- | --------------------------------- |
    | **Cost**       | **4 credits** per company         |
    | **No Results** | **FREE** if no funding data found |

    <Tip>
      Includes detailed funding history, investor lists, and CEO/founder information.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/companies/company-funding' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"company_domain": "leadmagic.io"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/companies/company-funding', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_domain: 'leadmagic.io' })
  });
  const data = await response.json();
  console.log(`Total Funding: ${data.total_funding}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/companies/company-funding',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'company_domain': 'leadmagic.io'}
  )
  data = response.json()
  print(f"Total Funding: {data.get('total_funding', 'Unknown')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Company website domain (preferred).
</ParamField>

<ParamField type="string">
  Company name.
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` (or both).
</Warning>

***

## Response

<ResponseField name="company_name" type="string">
  Company name
</ResponseField>

<ResponseField name="total_funding" type="string">
  Total funding raised (formatted)
</ResponseField>

<ResponseField name="latest_round" type="string">
  Most recent funding round type (Series A, B, etc.)
</ResponseField>

<ResponseField name="latest_round_amount" type="string">
  Amount raised in latest round
</ResponseField>

<ResponseField name="latest_round_date" type="string">
  Date of latest round
</ResponseField>

<Expandable title="Funding Rounds">
  <ResponseField name="funding_rounds" type="array">
    Array of funding rounds with type, amount, date, and investors
  </ResponseField>
</Expandable>

<Expandable title="Investors">
  <ResponseField name="investors" type="array">
    List of investor names
  </ResponseField>

  <ResponseField name="lead_investors" type="array">
    Lead investors in recent rounds
  </ResponseField>
</Expandable>

<Expandable title="Leadership">
  <ResponseField name="leadership.ceo.firstName" type="string">
    CEO first name
  </ResponseField>

  <ResponseField name="leadership.ceo.lastName" type="string">
    CEO last name
  </ResponseField>

  <ResponseField name="leadership.ceo.designation" type="string">
    CEO title
  </ResponseField>

  <ResponseField name="leadership.ceo.b2b_profile" type="string">
    CEO profile URL
  </ResponseField>
</Expandable>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "company_name": "LeadMagic",
  "total_funding": "$8.7B",
  "latest_round": "Series I",
  "latest_round_amount": "$600M",
  "latest_round_date": "2023-03-15",
  "funding_rounds": [
    {
      "type": "Series I",
      "amount": "$600M",
      "date": "2023-03-15",
      "investors": ["Andreessen Horowitz", "Founders Fund"]
    }
  ],
  "investors": ["Andreessen Horowitz", "Sequoia Capital", "General Catalyst"],
  "leadership": {
    "ceo": {
      "firstName": "Alex",
      "lastName": "Rivera",
      "designation": "CEO & Co-Founder",
      "b2b_profile": "linkedin.com/in/patrickcollison"
    }
  },
  "credits_consumed": 4,
  "message": "Funding data found."
}
```

***

## Success Messages

| Message                                   | Meaning                      | Cost      |
| ----------------------------------------- | ---------------------------- | --------- |
| `Funding data found.`                     | Full funding data returned   | 4 credits |
| `No funding data found for this company.` | No funding records available | FREE      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Target recently funded companies" icon="rocket">
    Companies with recent funding have budget and are actively investing in growth.
  </Accordion>

  <Accordion title="Track investor portfolios" icon="briefcase">
    Companies backed by the same investors often have similar needs.
  </Accordion>

  <Accordion title="Use for lead scoring" icon="star">
    Funding stage and amount are strong signals for company budget and growth trajectory.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Prioritization" icon="ranking-star">
    Prioritize outreach to recently funded companies with budget.
  </Card>

  <Card title="Market Intelligence" icon="chart-line">
    Track funding trends in your target market.
  </Card>

  <Card title="Lead Scoring" icon="star">
    Score leads based on funding stage and amount.
  </Card>

  <Card title="Account Research" icon="magnifying-glass">
    Understand financial position before outreach.
  </Card>
</CardGroup>


# Company Lookalike
Source: https://leadmagic.io/docs/v1/reference/company-lookalike

post /v3/companies/lookalike
Find similar companies from a seed domain or description with full company output.

# Company Lookalike

`POST /v3/companies/lookalike` finds similar companies from a seed domain, website, or text description. It returns the same full company output row as [Company Search](/docs/v1/reference/company-search), plus lookalike scoring fields when available.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                                               |
    | -------------- | --------------------------------------------------- |
    | **Cost**       | **5 credits** when lookalike companies are returned |
    | **No Results** | **FREE**                                            |

    <Tip>
      Lookalike requests return full company rows, so you usually do not need a second lookup for each result.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value                       |
    | ------------------- | --------------------------- |
    | **Requests/Minute** | 500                         |
    | **Burst Capacity**  | Subject to workspace limits |
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/companies/lookalike' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "company_domain": "leadmagic.io",
      "company_filters": {
        "country_codes": ["US"],
        "employee_ranges": ["51 to 200", "201 to 500"],
        "has_tech_stack": true
      },
      "limit": 25
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/companies/lookalike', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company_domain: 'leadmagic.io',
      company_filters: {
        country_codes: ['US'],
        employee_ranges: ['51 to 200', '201 to 500'],
        has_tech_stack: true
      },
      limit: 25
    })
  });

  const data = await response.json();
  console.log(`${data.count} lookalike companies found`);
  ```
</CodeGroup>

## Request Body

Provide either a seed domain/website or a text description.

<ParamField type="string">
  Seed company domain. Preferred for strongest vector lookalike matching.
</ParamField>

<ParamField type="string">
  Alias for `company_domain`.
</ParamField>

<ParamField type="string">
  Seed website URL or domain. Normalized to a domain.
</ParamField>

<ParamField type="object">
  Optional seed object. Supports `seed.domain`, `seed.domains`, and `seed.description`.
</ParamField>

<ParamField type="string">
  Free-text company description to embed for lookalike discovery when you do not have a seed domain.
</ParamField>

<ParamField type="string">
  Seed company name used as text intent when no domain is supplied. Domains are more precise.
</ParamField>

<ParamField type="object">
  Same full company filter family as [Company Search](/docs/v1/reference/company-search), applied after vector similarity.
</ParamField>

<ParamField type="integer">
  Number of lookalike companies to return. Maximum is `2000`.
</ParamField>

<ParamField type="integer">
  Offset for pagination.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Human-readable result summary.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  `5` when lookalikes are returned in a paid request, otherwise `0`.
</ResponseField>

<ResponseField name="companies" type="object[]">
  Full company rows matching the seed and filters.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of lookalike companies returned.
</ResponseField>

<ResponseField name="interpreted_search" type="object">
  Normalized seed and company filters used by the backend.
</ResponseField>

Returned company rows include the full Company Search output fields such as firmographics, funding, location, contact coverage, classification, website status, and technology columns. Lookalike rows can also include:

| Field                | Type     | Description                                                           |
| -------------------- | -------- | --------------------------------------------------------------------- |
| `similarity`         | `number` | Vector similarity score for the matched company.                      |
| `source_seed_domain` | `string` | Seed domain that produced the match when multiple seeds are supplied. |
| `match_context`      | `string` | Embedding text or context that helped produce the match.              |

## Related endpoints

<CardGroup>
  <Card title="Company Search" icon="building-magnifying-glass" href="/v1/reference/company-search">
    Build filtered account lists with the same output row shape.
  </Card>

  <Card title="People Search" icon="users" href="/v1/reference/people-search">
    Search contacts inside one company or a filtered company set.
  </Card>
</CardGroup>


# Company Search
Source: https://leadmagic.io/docs/v1/reference/company-search

post /v3/companies/search
Canonical V3 company lookup with all company filters.

# Company Search

`POST /v3/companies/search` is the single V3 company lookup endpoint for building and paging through account lists from structured criteria.

Use Company Search for both one-company lookup and filtered company lists. Send a single identifier such as `company_domain`, `domain`, `website`, `company_name`, `profile_url`, or `linkedin_url` for one company, or use `company_filters` for account lists.

<Info>
  Existing clients that send one-company search bodies such as `company_domain`, `domain`, `website`, `company_name`, `profile_url`, or `linkedin_url` can keep using the same request shape. When no broad filters or explicit `limit` are supplied, the API treats the request as a one-row lookup and returns the richer company record plus legacy-friendly aliases such as `companyName`, `companyDomain`, and `websiteUrl`.
</Info>

<Tip>
  You can pass multiple company identities at once using `company_domains`, `company_websites`, B2B company profile inputs, and `company_names`. Those identity filters are treated as alternatives, then the rest of your filters narrow the matched set.
</Tip>

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                                            |
    | -------------- | ------------------------------------------------ |
    | **Search**     | **1 credit** per returned company                |
    | **No results** | **FREE**                                         |
    | **Page cap**   | `limit` max is `50`; use `offset` for pagination |

    <Tip>
      Credits finalize by returned company count, not by requested limit.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value                       |
    | ------------------- | --------------------------- |
    | **Requests/Minute** | 500                         |
    | **Burst Capacity**  | Subject to workspace limits |
  </Tab>
</Tabs>

***

## Quick Examples

Use **one** of the patterns below. They hit the same endpoint but return different response shapes.

<Tabs>
  <Tab title="One company lookup" icon="building">
    Send a single company identifier at the request root. Do **not** include `company_filters`, `query`, or `limit` unless you want list mode.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
        -H 'X-API-Key: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "company_domain": "leadmagic.io"
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
        method: 'POST',
        headers: {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          company_domain: 'leadmagic.io'
        })
      });

      const data = await response.json();
      console.log(data.companyName, data.company?.company_domain);
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api.leadmagic.io/v3/companies/search',
          headers={'X-API-Key': 'YOUR_API_KEY'},
          json={'company_domain': 'leadmagic.io'}
      )

      data = response.json()
      print(data.get('companyName'), data.get('company', {}).get('company_domain'))
      ```
    </CodeGroup>

    **Accepted root fields:** `company_domain` (preferred), `domain`, `website`, `company_name`, `profile_url`, `linkedin_url` (and aliases listed below).

    **Response extras:** `found`, `company`, `companyName`, `companyDomain`, `websiteUrl`, `linkedinUrl` plus `companies[]` with one row.
  </Tab>

  <Tab title="Filtered company list" icon="list">
    Send structured filters to build or page through an account list.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
        -H 'X-API-Key: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "limit": 10,
          "offset": 0,
          "company_filters": {
            "company_domains": ["leadmagic.io"],
            "country_codes": ["US"],
            "min_total_contacts": 1
          }
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
        method: 'POST',
        headers: {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          limit: 10,
          offset: 0,
          company_filters: {
            company_domains: ['leadmagic.io'],
            country_codes: ['US'],
            min_total_contacts: 1
          }
        })
      });

      const data = await response.json();
      console.log(`${data.count} companies`);
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api.leadmagic.io/v3/companies/search',
          headers={'X-API-Key': 'YOUR_API_KEY'},
          json={
              'limit': 10,
              'offset': 0,
              'company_filters': {
                  'company_domains': ['leadmagic.io'],
                  'country_codes': ['US']
              }
          }
      )

      data = response.json()
      print(f"{data['count']} companies")
      ```
    </CodeGroup>

    **Response focus:** `companies[]`, `count`, `limit_applied`, `offset`, `interpreted_search`. Legacy single-company aliases are omitted in list mode.
  </Tab>
</Tabs>

<Warning>
  Adding `limit`, `company_filters`, or `query` switches the request to **list mode**. For a single-company lookup, send only identity fields such as `company_domain` or `linkedin_url`.
</Warning>

## Request Body

<ParamField type="string">
  One-company lookup: company domain (preferred). Aliases: `domain`, `website`, `company_website`.
</ParamField>

<ParamField type="string">
  One-company lookup: company name. Aliases: `name`.
</ParamField>

<ParamField type="string">
  One-company lookup: B2B company profile URL. Aliases: `linkedin_url`, `company_linkedin_url`, `company_url`, `url`.
</ParamField>

<ParamField type="object">
  List search: primary filter object. You may also send the same fields inside `filters` or at the request root; `company_filters` is preferred for new integrations.
</ParamField>

<ParamField type="string">
  Optional natural-language/company keyword query. Use structured fields when you know the exact filters.
</ParamField>

<ParamField type="integer">
  Number of companies to return. Maximum is `50` for this public API route.
</ParamField>

<ParamField type="integer">
  Offset for pagination. Increase by `limit` to fetch the next page.
</ParamField>

## Company Identity Filters

| Field                                   | Type       | Matching behavior                                   |
| --------------------------------------- | ---------- | --------------------------------------------------- |
| `company_domains`                       | `string[]` | Exact normalized domain match, e.g. `leadmagic.io`  |
| `company_websites`                      | `string[]` | Normalized to domain-equivalent exact matches       |
| `linkedin_urls`                         | `string[]` | Exact normalized B2B company profile matches        |
| `company_names`                         | `string[]` | Exact case-insensitive company name match           |
| `company_domain`                        | `string`   | Single-value alias for `company_domains`            |
| `company_website` / `website`           | `string`   | Single-value aliases for `company_websites`         |
| `linkedin_url` / `company_linkedin_url` | `string`   | Single-value aliases for B2B company profile inputs |
| `company_name` / `name`                 | `string`   | Single-value aliases for company name search        |

## Firmographic Filters

| Field                                | Type                  | Description                                        |
| ------------------------------------ | --------------------- | -------------------------------------------------- |
| `country_codes` / `country_code`     | `string[]` / `string` | HQ country codes such as `US`, `GB`, `CA`          |
| `industries` / `industry`            | `string[]` / `string` | B2B industry labels                                |
| `employee_ranges` / `employee_range` | `string[]` / `string` | Ranges such as `51 to 200`, `201 to 500`, `10001+` |
| `min_employees`                      | `integer`             | Minimum employee count/range overlap               |
| `max_employees`                      | `integer`             | Maximum employee count/range overlap               |
| `revenue_ranges` / `revenue_range`   | `string[]` / `string` | Revenue labels such as `$10M to <$50M`             |
| `min_revenue`                        | `integer`             | Minimum revenue                                    |
| `max_revenue`                        | `integer`             | Maximum revenue                                    |
| `founded_after`                      | `integer`             | Minimum founded year                               |
| `founded_before`                     | `integer`             | Maximum founded year                               |
| `company_entity_types`               | `string[]`            | Legal/company entity type labels                   |
| `domain_tlds`                        | `string[]`            | Domain TLDs such as `io`, `com`, `ai`              |

## Location Filters

| Field           | Type       |
| --------------- | ---------- |
| `hq_countries`  | `string[]` |
| `hq_regions`    | `string[]` |
| `hq_cities`     | `string[]` |
| `hq_states`     | `string[]` |
| `hq_continents` | `string[]` |
| `hq_streets`    | `string[]` |
| `hq_postcodes`  | `string[]` |

## Funding And Social Filters

| Field                                                       | Type       | Description                                     |
| ----------------------------------------------------------- | ---------- | ----------------------------------------------- |
| `has_funding`                                               | `boolean`  | Require or exclude companies with known funding |
| `min_total_funding` / `max_total_funding`                   | `integer`  | Funding amount bounds                           |
| `last_funding_types`                                        | `string[]` | Funding round/type labels                       |
| `last_funding_after` / `last_funding_before`                | `string`   | Date bounds for last funding                    |
| `min_funding_investor_count` / `max_funding_investor_count` | `integer`  | Investor-count bounds                           |
| `lead_investors`                                            | `string[]` | Fuzzy lead investor text search                 |
| `min_profile_followers` / `max_profile_followers`           | `integer`  | B2B company profile follower bounds             |
| `min_profile_growth_rate` / `max_profile_growth_rate`       | `number`   | Profile follower growth-rate bounds             |
| `linkedin_claimed`                                          | `boolean`  | Claimed B2B company profile flag                |

## Contact Coverage Filters

| Field                                                 | Type      |
| ----------------------------------------------------- | --------- |
| `min_total_contacts` / `max_total_contacts`           | `integer` |
| `min_contacts_with_email` / `max_contacts_with_email` | `integer` |
| `min_contacts_with_phone` / `max_contacts_with_phone` | `integer` |
| `min_valid_email_count` / `max_valid_email_count`     | `integer` |

## Technology Filters

| Field                            | Type       | Description                                                     |
| -------------------------------- | ---------- | --------------------------------------------------------------- |
| `has_tech_stack`                 | `boolean`  | Require a detected tech stack                                   |
| `tech_stack` / `technologies`    | `string[]` | Generic technology search across indexed tech/specialty columns |
| `crm_tech`                       | `string[]` | CRM technologies                                                |
| `marketing_automation_tech`      | `string[]` | Marketing automation                                            |
| `sales_automation_tech`          | `string[]` | Sales automation                                                |
| `analytics_tech`                 | `string[]` | Analytics tools                                                 |
| `cloud_provider_tech`            | `string[]` | Cloud platforms such as AWS, GCP, Azure                         |
| `development_tech`               | `string[]` | Development frameworks/tools                                    |
| `ecommerce_tech`                 | `string[]` | Ecommerce platforms                                             |
| `erp_tech`                       | `string[]` | ERP platforms                                                   |
| `email_hosting_tech`             | `string[]` | Email hosting                                                   |
| `email_security_tech`            | `string[]` | Email security                                                  |
| `abm_tech`                       | `string[]` | ABM tools                                                       |
| `cms_tech`                       | `string[]` | CMS tools                                                       |
| `conversation_intelligence_tech` | `string[]` | Conversation intelligence tools                                 |
| `app_security_tech`              | `string[]` | Application security tools                                      |
| `cloud_security_tech`            | `string[]` | Cloud security tools                                            |
| `company_martech`                | `string[]` | Marketing technology                                            |

## Text And Classification Filters

| Field                | Type       |
| -------------------- | ---------- |
| `keyword`            | `string`   |
| `specialties`        | `string[]` |
| `company_headlines`  | `string[]` |
| `company_about`      | `string[]` |
| `company_phones`     | `string[]` |
| `sic_codes`          | `string[]` |
| `naics_codes`        | `string[]` |
| `sic_descriptions`   | `string[]` |
| `naics_descriptions` | `string[]` |

## Website Filters

| Field                                             | Type      |
| ------------------------------------------------- | --------- |
| `website_active`                                  | `boolean` |
| `website_for_sale`                                | `boolean` |
| `min_total_app_reviews` / `max_total_app_reviews` | `integer` |

## Sort

| Field        | Type     | Values                                                                                                               |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `sort_by`    | `string` | `company_domain`, `linkedin_followers`, `total_funding`, `linkedin_employee_count`, `founded_year`, `total_contacts` |
| `sort_order` | `string` | `asc`, `desc`                                                                                                        |

## Response

<ResponseField name="companies" type="object[]">
  Company records matching your criteria.
</ResponseField>

<ResponseField name="company" type="object">
  Present for one-company lookup requests. Contains the first returned company record.
</ResponseField>

<ResponseField name="found" type="boolean">
  Present for one-company lookup requests. `true` when a company row was returned.
</ResponseField>

<ResponseField name="companyName" type="string">
  Present for one-company lookup requests. Alias for `company.company_name`.
</ResponseField>

<ResponseField name="companyDomain" type="string">
  Present for one-company lookup requests. Alias for `company.company_domain`.
</ResponseField>

<ResponseField name="websiteUrl" type="string">
  Present for one-company lookup requests. Alias for `company.company_website`.
</ResponseField>

<ResponseField name="linkedinUrl" type="string">
  Present for one-company lookup requests. Alias for `company.linkedin_url`.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of companies returned.
</ResponseField>

<ResponseField name="returned_count" type="integer">
  Alias for `count`.
</ResponseField>

<ResponseField name="limit_applied" type="integer">
  Applied page size.
</ResponseField>

<ResponseField name="offset" type="integer">
  Applied offset.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Finalized credits charged (1 per returned company; `0` when no companies match).
</ResponseField>

<ResponseField name="interpreted_search" type="object">
  Normalized filters used by the backend.
</ResponseField>

### Example Responses

<CodeGroup>
  ```json One company lookup theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "message": "Companies found",
    "credits_consumed": 1,
    "found": true,
    "companyName": "LeadMagic",
    "companyDomain": "leadmagic.io",
    "websiteUrl": "https://leadmagic.io",
    "company": {
      "company_domain": "leadmagic.io",
      "company_name": "LeadMagic"
    },
    "companies": [
      {
        "company_domain": "leadmagic.io",
        "company_name": "LeadMagic"
      }
    ],
    "count": 1,
    "returned_count": 1,
    "limit_applied": 1,
    "offset": 0
  }
  ```

  ```json Filtered company list theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "message": "Companies found",
    "credits_consumed": 1,
    "companies": [
      {
        "company_domain": "leadmagic.io",
        "company_name": "LeadMagic",
        "hq_country_code": "US"
      }
    ],
    "count": 1,
    "returned_count": 1,
    "limit_applied": 10,
    "offset": 0,
    "interpreted_search": {
      "company_filters": {
        "company_domains": ["leadmagic.io"],
        "country_codes": ["US"]
      }
    }
  }
  ```
</CodeGroup>

Returned company rows can include:

`company_domain`, `company_name`, `company_website`, `company_industry_linkedin`, `employee_range`, `employee_min`, `employee_max`, `linkedin_employee_count`, `revenue_range`, `revenue_min`, `revenue_max`, `hq_country`, `hq_country_code`, `hq_city`, `hq_state`, `hq_street`, `hq_postcode`, `hq_region`, `hq_continent`, `founded_year`, `category`, `specialties`, `total_funding`, `funding_investor_count`, `last_funding_type`, `last_funding_date`, `last_funding_amount`, `lead_investors`, `linkedin_followers`, `linkedin_growth_rate`, `linkedin_url`, `linkedin_claimed`, `company_headline`, `company_about`, `company_logo_url`, `company_phone`, `company_entity_type`, `has_tech_stack`, `total_contacts`, `contacts_with_email`, `contacts_with_phone`, `valid_email_count`, `website_active`, `website_for_sale`, `sic_code`, `naics_code`, `sic_description`, `naics_description`, `domain_tld`, `total_app_reviews`, and all technology columns listed above.

## Related endpoints

<CardGroup>
  <Card title="Company Lookalike" icon="sparkles" href="/v1/reference/company-lookalike">
    Find similar accounts from a seed company and return the same full company row shape.
  </Card>

  <Card title="Technographics" icon="microchip" href="/v1/reference/technographics">
    Get detailed technology stack information for one company.
  </Card>

  <Card title="People Search" icon="users" href="/v1/reference/people-search">
    Search contacts across one company or a filtered company set.
  </Card>
</CardGroup>


# Email Finder
Source: https://leadmagic.io/docs/v1/reference/email-finder

post /v1/people/email-finder
Find a person's work email address using their name and company information.

# Find Work Email

Find professional email addresses from a person's name and company. Every email found is automatically validated for deliverability.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                               |
    | -------------- | ----------------------------------- |
    | **Cost**       | **1 credit** per valid email found  |
    | **No Results** | **FREE** if no email found (`null`) |

    <Tip>
      You only pay when we find a `valid` email. If no email is found (status `null`), you are not charged.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/email-finder' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "first_name": "Jesse",
      "last_name": "Ouellette",
      "domain": "leadmagic.io"
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/email-finder', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'Jesse',
      last_name: 'Ouellette',
      domain: 'leadmagic.io'
    })
  });
  const data = await response.json();
  if (data.status === 'valid') {
    console.log(`Found: ${data.email}`);
  } else {
    console.log('No email found (not charged)');
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/email-finder',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'first_name': 'Jesse',
          'last_name': 'Ouellette',
          'domain': 'leadmagic.io'
      }
  )
  data = response.json()
  if data.get('status') == 'valid':
      print(f"Found: {data['email']}")
  else:
      print('No email found (not charged)')
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Person's first name. Required if `full_name` not provided. If both are sent, `first_name` + `last_name` are used first.
</ParamField>

<ParamField type="string">
  Person's last name. Required if `full_name` not provided.
</ParamField>

<ParamField type="string">
  Person's full name. Alternative to `first_name` + `last_name`. Leave this field out when sending split names.
</ParamField>

<ParamField type="string">
  Company website domain (preferred). More accurate than `company_name`; if both are sent, `domain` is used first.
</ParamField>

<ParamField type="string">
  Company name. Use only if `domain` is not available.
</ParamField>

<Warning>
  You must provide at least one name field (`first_name`, `last_name`, or `full_name`) AND one company field (`domain` or `company_name`).
</Warning>

***

## Response

<ResponseField name="email" type="string">
  The found email address (`null` if not found)
</ResponseField>

<ResponseField name="status" type="string">
  Result status: `valid` or `null`
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (1 for `valid`, 0 for `null`)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="employment_verified" type="boolean">
  Whether employment at this company was verified
</ResponseField>

<Expandable title="Deliverability Intelligence">
  <ResponseField name="mx_record" type="string">
    Primary MX record
  </ResponseField>

  <ResponseField name="mx_provider" type="string">
    Email provider (Example Mail, Example Mail Suite, etc.)
  </ResponseField>

  <ResponseField name="has_mx" type="boolean">
    Whether the domain has valid MX records
  </ResponseField>
</Expandable>

<Expandable title="Company Data (Included Free)">
  <ResponseField name="company_name" type="string">
    Company name
  </ResponseField>

  <ResponseField name="company_industry" type="string">
    Company industry
  </ResponseField>

  <ResponseField name="company_size" type="string">
    Employee count range
  </ResponseField>

  <ResponseField name="company_profile_url" type="string">
    Professional profile URL
  </ResponseField>
</Expandable>

### Example Responses

<CodeGroup>
  ```json Valid Email Found theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "email": "jesse.ouellette@leadmagic.io",
    "status": "valid",
    "credits_consumed": 1,
    "message": "Valid email found.",
    "first_name": "Jesse",
    "last_name": "Ouellette",
    "domain": "leadmagic.io",
    "mx_provider": "Example Mail",
    "employment_verified": true,
    "company_name": "LeadMagic",
    "company_industry": "Technology"
  }
  ```

  ```json No Email Found (Free) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "email": null,
    "status": null,
    "credits_consumed": 0,
    "message": "No email found for this person at this company.",
    "first_name": "Jesse",
    "last_name": "Ouellette",
    "domain": "leadmagic.io"
  }
  ```
</CodeGroup>

***

## Status Codes

<CardGroup>
  <Card title="valid" icon="circle-check">
    **1 credit** - Email immediately

    Verified email found. Safe to send.
  </Card>

  <Card title="null" icon="circle-xmark">
    **FREE** - No email found

    No email found for this person at this company. Not charged.
  </Card>
</CardGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use domain over company name" icon="globe">
    Domain lookups are more accurate. `leadmagic.io` will always find the right company, while "LeadMagic" might match similar names.
  </Accordion>

  <Accordion title="Check employment verification" icon="badge-check">
    The `employment_verified` field tells you if we confirmed this person works at the company.
  </Accordion>

  <Accordion title="Handle null results gracefully" icon="rotate">
    If the result is `null`, try variations: different name spellings, company domain instead of name, or `full_name` instead of `first_name`/`last_name`.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Outreach" icon="envelope">
    Find decision-maker emails for personalized outreach campaigns.
  </Card>

  <Card title="Lead Enrichment" icon="database">
    Complete partial lead records with verified email addresses.
  </Card>

  <Card title="ABM Campaigns" icon="bullseye">
    Build contact lists for target accounts with verified emails.
  </Card>

  <Card title="Recruiting" icon="users">
    Reach passive candidates with verified work emails.
  </Card>
</CardGroup>


# Email Address to B2B Person Profile
Source: https://leadmagic.io/docs/v1/reference/email-to-profile

post /v1/people/b2b-profile
Use this endpoint to find a B2B person profile based on the provided email.

# Email to B2B Person Profile

Convert an email address into a B2B person profile. Find the professional identity behind any email.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                            |
    | -------------- | -------------------------------- |
    | **Cost**       | **10 credits** per profile found |
    | **No Results** | **FREE** if no profile found     |

    <Tip>
      Reverse lookup is more resource-intensive than forward lookup, hence the higher cost.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/b2b-profile' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"work_email": "alex.rivera@example.com"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/b2b-profile', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ work_email: 'alex.rivera@example.com' })
  });
  const data = await response.json();
  if (data.profile_url) {
    console.log(`Profile: ${data.profile_url}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/b2b-profile',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'work_email': 'alex.rivera@example.com'}
  )
  data = response.json()
  print(f"Profile: {data.get('profile_url', 'Not found')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Work email address to lookup. Preferred over personal\_email.
</ParamField>

<ParamField type="string">
  Personal email address to lookup. Alternative identifier.
</ParamField>

<Warning>
  You must provide either `work_email` or `personal_email` (or both for better match rates).
</Warning>

***

## Response

<ResponseField name="profile_url" type="string">
  B2B person profile URL or slug (null if not found)
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (10 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "profile_url": "linkedin.com/in/alex-rivera",
  "credits_consumed": 10,
  "message": "Profile URL found."
}
```

***

## Success Messages

| Message                            | Meaning                                    | Cost       |
| ---------------------------------- | ------------------------------------------ | ---------- |
| `Profile URL found`                | B2B person profile successfully identified | 10 credits |
| `No profile found for this email.` | No matching profile found                  | FREE       |

***

## Workflow

<Steps>
  <Step title="Submit Email">
    Send the work or personal email address.
  </Step>

  <Step title="B2B Person Profile Lookup">
    We search our database for matching B2B person profiles.
  </Step>

  <Step title="Get B2B Person Profile">
    Receive the B2B person profile.
  </Step>

  <Step title="Enrich Further">
    Use [B2B Person Profile](/docs/v1/reference/profile-search) to get full profile details.
  </Step>
</Steps>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use work email first" icon="building">
    Work emails have higher match rates than personal emails for professional profiles.
  </Accordion>

  <Accordion title="Chain with B2B Person Profile" icon="link">
    After finding a profile URL, use B2B Person Profile to get complete profile data.
  </Accordion>

  <Accordion title="Handle no matches gracefully" icon="circle-xmark">
    Not all emails have associated professional profiles. Plan for partial enrichment.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="CRM Enrichment" icon="database">
    Add B2B person profile links to your CRM contacts.
  </Card>

  <Card title="Lead Research" icon="magnifying-glass">
    Identify the professional identity behind inbound leads.
  </Card>

  <Card title="Visitor Identification" icon="eye">
    Match website visitors to professional profiles.
  </Card>

  <Card title="Data Completeness" icon="check-double">
    Fill in missing profile URLs in your contact database.
  </Card>
</CardGroup>


# Email Validation
Source: https://leadmagic.io/docs/v1/reference/email-validation

post /v1/people/email-validation
Validate an email address for deliverability and get company enrichment data.

# Validate Email

Verify email addresses with industry-leading accuracy. Our validation system combines SMTP verification with engagement data for the most reliable results.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric           | Value                                      |
    | ---------------- | ------------------------------------------ |
    | **Cost**         | **0.25 credits** per validation            |
    | **Calculation**  | 4 validations = 1 credit                   |
    | **Free Results** | `unknown` and RFC-invalid results are free |

    <Tip>
      You only pay for definitive SMTP results (`valid`, `invalid`). Inconclusive results (`unknown`) and RFC syntax failures are always free.
    </Tip>

    <Info>
      **RFC 5321/5322 Compliance:** Emails that fail RFC syntax validation are automatically marked `invalid` and returned instantly — **no credits charged**. This includes malformed addresses, invalid characters, and improper formatting.
    </Info>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"email": "alex.rivera@example.com"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email: 'alex.rivera@example.com' })
  });
  const data = await response.json();
  console.log(data.email_status); // 'valid', 'invalid', or 'unknown'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/email-validation',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'email': 'alex.rivera@example.com'}
  )
  data = response.json()
  print(f"Status: {data['email_status']}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  The email address to validate. Must be a properly formatted email address.
</ParamField>

***

## Response

<ResponseField name="email" type="string">
  The validated email address (normalized)
</ResponseField>

<ResponseField name="email_status" type="string">
  Validation result: `valid`, `invalid`, or `unknown`
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used for this request (0.25 for `valid`/`invalid`, 0 for `unknown`)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<ResponseField name="mx_record" type="string">
  Primary MX record for the domain
</ResponseField>

<ResponseField name="mx_provider" type="string">
  Email provider (Example Mail, Example Mail Suite, etc.)
</ResponseField>

<ResponseField name="mx_gateway" type="string">
  Security gateway vendor name (null if none)
</ResponseField>

<ResponseField name="mx_gateway_type" type="string">
  Security gateway type (null if none)
</ResponseField>

<ResponseField name="mx_security_gateway" type="boolean">
  Whether a security gateway is present
</ResponseField>

<Expandable title="Company Data (Included Free)">
  <ResponseField name="company_name" type="string">
    Company name derived from email domain
  </ResponseField>

  <ResponseField name="company_industry" type="string">
    Company industry
  </ResponseField>

  <ResponseField name="company_size" type="string">
    Employee count range
  </ResponseField>

  <ResponseField name="company_founded" type="integer">
    Year founded
  </ResponseField>

  <ResponseField name="company_type" type="string">
    Ownership type (private, public, etc.)
  </ResponseField>

  <ResponseField name="company_linkedin_url" type="string">
    B2B company profile URL
  </ResponseField>

  <ResponseField name="company_linkedin_id" type="string">
    B2B company profile ID
  </ResponseField>

  <ResponseField name="company_facebook_url" type="string">
    Facebook page URL (null if unavailable)
  </ResponseField>

  <ResponseField name="company_twitter_url" type="string">
    Twitter/X profile URL (null if unavailable)
  </ResponseField>

  <ResponseField name="company_location" type="object">
    Full location with city, state, country, coordinates
  </ResponseField>
</Expandable>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "email": "alex.rivera@example.com",
  "email_status": "valid",
  "credits_consumed": 0.25,
  "message": "Email is valid.",
  "mx_record": "mx1.example.com",
  "mx_provider": "Example Mail",
  "mx_gateway": null,
  "mx_gateway_type": null,
  "mx_security_gateway": false,
  "company_name": "Leadmagic",
  "company_industry": "Internet",
  "company_size": "11-50",
  "company_founded": 2022,
  "company_type": "Private",
  "company_location": {
    "name": "Boston, Massachusetts, United States",
    "locality": "Boston",
    "region": "Massachusetts",
    "metro": "Boston",
    "country": "United States",
    "continent": "North America",
    "street_address": "1 Seaport Lane",
    "address_line_2": null,
    "postal_code": "02210",
    "geo": null
  },
  "company_linkedin_url": "linkedin.com/company/leadmagichq",
  "company_linkedin_id": "75153174",
  "company_facebook_url": null,
  "company_twitter_url": null
}
```

***

## Status Codes

<CardGroup>
  <Card title="valid" icon="circle-check">
    **Safe to email** - Bounce rate \<1%

    Email verified by mail server. Costs 0.25 credits.
  </Card>

  <Card title="invalid" icon="circle-xmark">
    **Do NOT email** - Will bounce

    Mail server confirmed non-existent. Costs 0.25 credits.
  </Card>

  <Card title="unknown" icon="circle-question">
    **Inconclusive** - Could not determine validity

    Couldn't reach mail server or domain is unverifiable. **FREE** (no charge).
  </Card>
</CardGroup>

### RFC Compliance

Emails that don't comply with RFC 5321/5322 standards are **automatically marked `invalid`** — no credits charged:

| RFC Violation      | Example                  | Result           |
| ------------------ | ------------------------ | ---------------- |
| Missing `@` symbol | `johnleadmagic.io`       | `invalid` (FREE) |
| Invalid characters | `alex @example.com`      | `invalid` (FREE) |
| Missing domain     | `alex@`                  | `invalid` (FREE) |
| Double dots        | `john..doe@leadmagic.io` | `invalid` (FREE) |
| Invalid TLD        | `alex@leadmagic`         | `invalid` (FREE) |

<Info>
  RFC validation happens instantly before SMTP verification. Malformed emails are rejected immediately at no cost — reserved credits are rolled back.
</Info>

***

## Success Messages

| Message                                        | Status    | Cost |
| ---------------------------------------------- | --------- | ---- |
| `Email is valid.`                              | `valid`   | 0.25 |
| `Email is invalid.`                            | `invalid` | 0.25 |
| `Email is invalid (RFC non-compliant format).` | `invalid` | FREE |
| `Email is invalid (malformed address).`        | `invalid` | FREE |
| `Unable to determine email validity.`          | `unknown` | FREE |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Pre-validate format client-side" icon="code">
    Run basic regex validation before API calls to catch obvious RFC violations. While RFC failures are free, client-side checks reduce unnecessary API calls.

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // Basic RFC-compliant check before API call
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(email)) {
      // Skip API call - obviously invalid
      return { email_status: 'invalid', reason: 'malformed' };
    }
    ```

    <Info>
      Note: Our API catches all RFC violations, but client-side pre-validation can reduce unnecessary API calls.
    </Info>
  </Accordion>

  <Accordion title="Validate before sending campaigns" icon="paper-plane">
    Always validate your email list before sending to maintain high deliverability and protect your sender reputation. Invalid emails hurt your domain reputation.
  </Accordion>

  <Accordion title="Handle unknown results" icon="shield">
    For `unknown` results, consider retrying later or using Email Finder to verify the specific address exists before adding to campaigns.
  </Accordion>

  <Accordion title="Batch your validations" icon="layer-group">
    For large lists, batch your requests to stay within rate limits. Use the response headers to monitor your remaining quota.

    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const remaining = response.headers.get('RateLimit-Remaining');
    if (remaining < 100) {
      await sleep(1000); // Slow down if approaching limit
    }
    ```
  </Accordion>

  <Accordion title="Use response headers for monitoring" icon="chart-line">
    Every response includes `X-Credits-Remaining` so you can track spending without extra API calls.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="List Cleaning" icon="broom">
    Validate email lists before campaigns to reduce bounces and protect sender reputation.
  </Card>

  <Card title="Form Validation" icon="square-check">
    Validate emails at point of capture to ensure data quality from the start.
  </Card>

  <Card title="CRM Hygiene" icon="database">
    Regularly validate CRM contacts to maintain deliverability rates.
  </Card>

  <Card title="Lead Scoring" icon="star">
    Use validation status as a lead quality signal in your scoring models.
  </Card>
</CardGroup>


# Google Ads Search
Source: https://leadmagic.io/docs/v1/reference/google-ads-search

post /v1/ads/google-ads-search
Search for Google Ads run by a company to understand their advertising strategy.

# Google Ads

Search for Google Ads run by a company. Analyze competitor advertising strategies, messaging, and creative approaches.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric          | Value                      |
    | --------------- | -------------------------- |
    | **Cost**        | **0.2 credits** per search |
    | **Calculation** | 5 searches = 1 credit      |
    | **No Results**  | **FREE** if no ads found   |

    <Tip>
      Very cost-effective for competitive ad intelligence at just 0.2 credits per search.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/ads/google-ads-search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"company_domain": "leadmagic.io"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/ads/google-ads-search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_domain: 'leadmagic.io' })
  });
  const data = await response.json();
  console.log(`Found ${data.ads?.length || 0} ads`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/ads/google-ads-search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'company_domain': 'leadmagic.io'}
  )
  data = response.json()
  print(f"Found {len(data.get('ads', []))} ads")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Company website domain (preferred).
</ParamField>

<ParamField type="string">
  Company name.
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` (or both).
</Warning>

***

## Response

<ResponseField name="company_name" type="string">
  Company searched
</ResponseField>

<ResponseField name="ads" type="array">
  Array of ad creatives
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (0.2 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Ad Object

| Field         | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| `headline`    | string | Ad headline                         |
| `description` | string | Ad description                      |
| `display_url` | string | Display URL                         |
| `final_url`   | string | Landing page URL                    |
| `ad_type`     | string | Type of ad (text, responsive, etc.) |

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "company_name": "Example Robotics",
  "ads": [
    {
      "headline": "Free CRM Software | Example Robotics",
      "description": "Get started with free CRM. No credit card required.",
      "display_url": "leadmagic.io",
      "final_url": "https://leadmagic.io",
      "ad_type": "responsive_search"
    }
  ],
  "credits_consumed": 0.2,
  "message": "Ads found."
}
```

***

## Success Messages

| Message                          | Meaning                  | Cost        |
| -------------------------------- | ------------------------ | ----------- |
| `Ads found.`                     | Google Ads data returned | 0.2 credits |
| `No ads found for this company.` | No Google Ads found      | FREE        |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Analyze competitor messaging" icon="message">
    Study headlines and descriptions to understand positioning and value props.
  </Accordion>

  <Accordion title="Find landing page inspiration" icon="browser">
    Use final\_urls to analyze competitor landing pages.
  </Accordion>

  <Accordion title="Track ad changes over time" icon="clock">
    Regular monitoring reveals A/B tests and strategy shifts.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Competitive Intelligence" icon="binoculars">
    Understand competitor ad strategies and messaging.
  </Card>

  <Card title="Ad Copy Inspiration" icon="lightbulb">
    Find proven messaging patterns in your market.
  </Card>

  <Card title="Market Research" icon="chart-line">
    Analyze advertising trends in your industry.
  </Card>

  <Card title="Landing Page Analysis" icon="browser">
    Discover competitor landing pages and offers.
  </Card>
</CardGroup>


# API Reference
Source: https://leadmagic.io/docs/v1/reference/introduction

Complete reference for all LeadMagic API endpoints

## Overview

The LeadMagic API provides RESTful endpoints for B2B data enrichment, email validation, contact discovery, company intelligence, and advertising insights.

All endpoints use `POST` requests with JSON bodies and return JSON responses. Authentication is done via the `X-API-Key` header.

<Card title="OpenAPI Specification" icon="code" href="/v1/reference/openapi.yml">
  Download the full OpenAPI 3.1 specification for use with tools like Postman, Insomnia, or code generators.
</Card>

## Authentication

All API requests require an API key passed in the `X-API-Key` header:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email": "alex.rivera@example.com"}'
```

<Tip>
  Get your API key from the [API Settings](https://app.leadmagic.io/settings/api) page. The header name is case-insensitive — `X-API-Key`, `X-API-KEY`, and `x-api-key` all work.
</Tip>

## Base URL

```
https://api.leadmagic.io
```

## All Endpoints

20+ endpoints across email, contact, company, jobs, and ads data. Every endpoint includes an interactive playground — click any card to try it live.

<Tabs>
  <Tab title="Email" icon="envelope">
    <CardGroup>
      <Card title="Email Validation" icon="envelope-circle-check" href="/v1/reference/email-validation">
        Verify emails with 99%+ accuracy. 4 validations per credit.
      </Card>

      <Card title="Email Finder" icon="magnifying-glass" href="/v1/reference/email-finder">
        Find work emails from name + company. 1 credit.
      </Card>

      <Card title="Personal Email Finder" icon="envelope" href="/v1/reference/personal-email-finder">
        Find personal email addresses. 2 credits.
      </Card>

      <Card title="B2B Person Profile to Email" icon="at" href="/v1/reference/profile-to-email">
        Get work email from a B2B person profile. 5 credits.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Contact" icon="user">
    <CardGroup>
      <Card title="B2B Person Profile" icon="user-magnifying-glass" href="/v1/reference/profile-search">
        Full B2B person profile with work history, education, skills. 1 credit.
      </Card>

      <Card title="Email to B2B Person Profile" icon="id-card" href="/v1/reference/email-to-profile">
        Find B2B person profiles from email. 10 credits.
      </Card>

      <Card title="Mobile Finder" icon="phone" href="/v1/reference/mobile-finder">
        Direct mobile numbers for outreach. 5 credits.
      </Card>

      <Card title="Job Change Detector" icon="arrow-right-arrow-left" href="/v1/reference/job-change-detector">
        Track when contacts change jobs. 3 credits.
      </Card>

      <Card title="Role Finder" icon="user-tie" href="/v1/reference/role-finder">
        Find people by title at a company. 2 credits.
      </Card>

      <Card title="People Search" icon="users" href="/v1/reference/people-search">
        Search employees and decision-makers with all filters.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Company" icon="building">
    <CardGroup>
      <Card title="Company Search" icon="building-magnifying-glass" href="/v1/reference/company-search">
        Firmographic data by domain or name. 1 credit.
      </Card>

      <Card title="Technographics" icon="microchip" href="/v1/reference/technographics">
        Tech stacks companies use. 1 credit.
      </Card>

      <Card title="Company Funding" icon="money-bill-trend-up" href="/v1/reference/company-funding">
        Funding rounds and investor data. 4 credits.
      </Card>

      <Card title="Company Lookalike" icon="users-between-lines" href="/v1/reference/company-lookalike">
        Discover similar companies from a seed account. 5 credits.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Jobs" icon="briefcase">
    <CardGroup>
      <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
        Search job listings across industries. 1 credit.
      </Card>
    </CardGroup>

    **Filter endpoints** (free, no credits):

    <CardGroup>
      <Card title="Countries" icon="globe" href="/v1/reference/job-country">
        Country codes for job filtering.
      </Card>

      <Card title="Regions" icon="map" href="/v1/reference/job-regions">
        States/provinces for job filtering.
      </Card>

      <Card title="Employment Types" icon="list" href="/v1/reference/job-types">
        Full-time, part-time, contract, etc.
      </Card>

      <Card title="Company Types" icon="building" href="/v1/reference/job-company-types">
        Filter by company size/type.
      </Card>

      <Card title="Industries" icon="industry" href="/v1/reference/job-industry">
        Industry codes for filtering.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Ads" icon="rectangle-ad">
    <CardGroup>
      <Card title="Google Ads Search" icon="magnifying-glass-chart" href="/v1/reference/google-ads-search">
        Competitor search ads. 1 credit = 5 lookups.
      </Card>

      <Card title="Meta Ads Search" icon="rectangle-ad" href="/v1/reference/meta-ads-search">
        Facebook/Instagram ads. 1 credit = 5 lookups.
      </Card>

      <Card title="B2B Ads Search" icon="rectangle-ad" href="/v1/reference/b2b-ads-search">
        Professional network ads. 1 credit = 5 lookups.
      </Card>

      <Card title="B2B Ad Details" icon="chart-bar" href="/v1/reference/b2b-ad-details">
        Full ad creative and metrics. 2 credits.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Account" icon="gauge">
    <CardGroup>
      <Card title="Check Credits" icon="coins" href="/v1/reference/check-credits">
        Monitor your credit balance. Free.
      </Card>

      <Card title="Analytics" icon="chart-line" href="/v1/reference/analytics">
        Usage stats, daily metrics, product breakdown. Free.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# Job Change Detector
Source: https://leadmagic.io/docs/v1/reference/job-change-detector

post /v1/people/job-change-detector
Monitor employee transitions and detect when someone has changed jobs.

# Detect Job Changes

Detect job changes for a professional by monitoring their profile against a specific company. Know instantly when your contacts move companies.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                   |
    | -------- | ----------------------- |
    | **Cost** | **3 credits** per check |

    <Tip>
      Job changes are a prime trigger event. People who just started a new role have budget and authority to make purchasing decisions.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/job-change-detector' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "profile_url": "linkedin.com/in/alex-rivera",
      "company_domain": "leadmagic.io"
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/job-change-detector', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      profile_url: 'linkedin.com/in/alex-rivera',
      company_domain: 'leadmagic.io'
    })
  });
  const data = await response.json();
  if (data.job_changed) {
    console.log(`Job change detected! Now at: ${data.current_company}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/job-change-detector',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'profile_url': 'linkedin.com/in/alex-rivera',
          'company_domain': 'leadmagic.io'
      }
  )
  data = response.json()
  if data.get('job_changed'):
      print(f"Job change detected! Now at: {data['current_company']}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Professional profile URL or username to monitor
</ParamField>

<ParamField type="string">
  Expected company domain to check against (preferred)
</ParamField>

<ParamField type="string">
  Expected company name to check against
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` to compare against.
</Warning>

***

## Response

<ResponseField name="job_changed" type="boolean">
  Whether the person has changed jobs
</ResponseField>

<ResponseField name="still_employed" type="boolean">
  Whether still employed at the expected company
</ResponseField>

<ResponseField name="current_company" type="string">
  Current company name (if changed)
</ResponseField>

<ResponseField name="current_title" type="string">
  Current job title
</ResponseField>

<ResponseField name="expected_company" type="string">
  The company you were checking against
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (always 3)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response - No Change

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "job_changed": false,
  "still_employed": true,
  "current_company": "Old Example Robotics",
  "current_title": "VP of Sales",
  "expected_company": "Old Example Robotics",
  "credits_consumed": 3,
  "message": "No job change detected. Still employed at expected company."
}
```

### Example Response - Job Changed

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "job_changed": true,
  "still_employed": false,
  "current_company": "New Example Robotics",
  "current_title": "Chief Revenue Officer",
  "expected_company": "Old Example Robotics",
  "credits_consumed": 3,
  "message": "Job change detected. Person has moved to a new company."
}
```

***

## Success Messages

| Message                                                       | Meaning                    |
| ------------------------------------------------------------- | -------------------------- |
| `No job change detected. Still employed at expected company.` | Person still at company    |
| `Job change detected. Person has moved to a new company.`     | Person changed jobs        |
| `Never worked at the expected company.`                       | No employment record found |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor key contacts regularly" icon="clock">
    Run weekly checks on your top accounts to catch job changes early.
  </Accordion>

  <Accordion title="Act fast on changes" icon="bolt">
    Job changers in their first 90 days are 3x more likely to buy. Reach out quickly.
  </Accordion>

  <Accordion title="Follow the champion" icon="user">
    When your champion moves, reach out at their new company - they already know your value.
  </Accordion>

  <Accordion title="Batch your checks" icon="layer-group">
    Check multiple contacts in parallel to efficiently monitor your database.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Champion Tracking" icon="star">
    Follow your product champions when they move to new companies.
  </Card>

  <Card title="Churn Prevention" icon="shield">
    Know when key contacts leave accounts before renewal conversations.
  </Card>

  <Card title="Trigger Campaigns" icon="bolt">
    Automatically trigger outreach when contacts move to target accounts.
  </Card>

  <Card title="CRM Hygiene" icon="database">
    Keep contact records accurate by detecting role changes.
  </Card>
</CardGroup>


# Job Company Type
Source: https://leadmagic.io/docs/v1/reference/job-company-types

get /v1/jobs/company-types
Use this API to retrieve the Company Type ID, which can then be used in the Jobs Finder API to filter jobs by Company Type.

# Company Types

Get all supported company type codes for filtering job searches.

<Info>
  **Free Endpoint** — No credits charged. Cache results locally.
</Info>

## Common Types

| Type           | Description                |
| -------------- | -------------------------- |
| Startup        | Early-stage companies      |
| Small Business | SMBs (\<50 employees)      |
| Mid-Market     | Growing companies (50-500) |
| Enterprise     | Large corporations (500+)  |
| Public         | Publicly traded            |
| Private        | Private companies          |
| Non-Profit     | Non-profit organizations   |
| Government     | Government agencies        |

<Tip>
  Target startups for fast-moving buyers, or enterprise for larger deal sizes.
</Tip>

## Related

<CardGroup>
  <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
    Use `company_type_id` to filter results
  </Card>

  <Card title="Industries" icon="industry" href="/v1/reference/job-industry">
    Filter by industry sector
  </Card>
</CardGroup>


# Job Country
Source: https://leadmagic.io/docs/v1/reference/job-country

get /v1/jobs/countries
Use this API to retrieve the country ID, which can then be used in the Jobs Finder API to filter jobs by country.

# Countries

Get all supported country codes for filtering job searches.

<Info>
  **Free Endpoint** — No credits charged. Cache results locally.
</Info>

## Common Codes

| Country        | Code |
| -------------- | ---- |
| United States  | `US` |
| United Kingdom | `UK` |
| Canada         | `CA` |
| Germany        | `DE` |
| Australia      | `AU` |
| France         | `FR` |
| India          | `IN` |

## Related

<CardGroup>
  <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
    Use `country_id` to filter results
  </Card>

  <Card title="Regions" icon="map" href="/v1/reference/job-regions">
    States/provinces within countries
  </Card>
</CardGroup>


# Job Industry
Source: https://leadmagic.io/docs/v1/reference/job-industry

get /v1/jobs/industries
Use this API to retrieve the Industry ID, which can then be used in the Jobs Finder API to filter jobs by Industry.

# Industries

Get all supported industry codes for filtering job searches.

<Info>
  **Free Endpoint** — No credits charged. Cache results locally.
</Info>

## Common Industries

| Industry      | Examples                    |
| ------------- | --------------------------- |
| Technology    | Software, SaaS, IT services |
| Finance       | Banking, fintech, insurance |
| Healthcare    | Medical, biotech, pharma    |
| Manufacturing | Industrial, production      |
| Retail        | E-commerce, brick & mortar  |
| Marketing     | Agencies, adtech            |
| Education     | EdTech, schools, training   |
| Real Estate   | Property, construction      |

## Workflow: Target Your ICP

<Steps>
  <Step title="Get Industry ID">
    Find your target industry ID from this endpoint.
  </Step>

  <Step title="Find Hiring Companies">
    Use [Jobs Finder](/docs/v1/reference/jobs-finder) with `company_industry_id`.
  </Step>

  <Step title="Research Companies">
    Use [Company Search](/docs/v1/reference/company-search) for full details.
  </Step>

  <Step title="Find Contacts">
    Use [Role Finder](/docs/v1/reference/role-finder) for decision makers.
  </Step>
</Steps>

## Related

<CardGroup>
  <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
    Use `company_industry_id` to filter results
  </Card>

  <Card title="Company Types" icon="building" href="/v1/reference/job-company-types">
    Filter by company size
  </Card>
</CardGroup>


# Job Region
Source: https://leadmagic.io/docs/v1/reference/job-regions

get /v1/jobs/regions
Use this API to retrieve the region ID, which can then be used in the Jobs Finder API to filter jobs by region.

# Regions

Get all supported state/province/region codes for filtering job searches.

<Info>
  **Free Endpoint** — No credits charged. Cache results locally.
</Info>

## Response Fields

| Field        | Description         |
| ------------ | ------------------- |
| `id`         | Region identifier   |
| `name`       | Region/state name   |
| `country_id` | Parent country code |

<Tip>
  Combine `country_id` and `region_id` for precise geographic targeting (e.g., California only).
</Tip>

## Related

<CardGroup>
  <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
    Use `region_id` to filter results
  </Card>

  <Card title="Countries" icon="globe" href="/v1/reference/job-country">
    Parent country codes
  </Card>
</CardGroup>


# Job Search
Source: https://leadmagic.io/docs/v1/reference/job-search

post /v3/jobs/search
Search jobs with occupation taxonomy, company, location, salary, tag, and title filters.

# Job Search

Search jobs with frontend-friendly filters. The `/v3/jobs/search` route resolves company domains, country codes, tags, occupation taxonomy, and title terms into normalized filter IDs before running a bounded query.

<Info>
  `POST /v3/jobs-search` is an alias for this endpoint with a simplified request shape. Use `/v3/jobs/search` for new integrations.
</Info>

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                                                                                               |
    | -------------- | --------------------------------------------------------------------------------------------------- |
    | **Cost**       | **1 credit** per returned job/signal                                                                |
    | **No Results** | **FREE** when no jobs are returned                                                                  |
    | **Helpers**    | Companies, resolve, tags, titles, occupation taxonomy, locations, catalogs, and stats are **FREE**. |

    <Tip>
      Pre-resolve filters with [helpers](/docs/v1/reference/job-search-helpers) when your UI needs autocomplete. Free helpers + targeted search beat paying for resolve on every query.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

Start with `limit: 5` and `totalMode: "none"` while testing. Add facets, deep mode, salary, company, and taxonomy filters only after the base search works.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/jobs/search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "titles": { "include": ["Software Engineer"] },
      "location": { "regions": ["North America"] },
      "postedWithin": 30,
      "limit": 5,
      "totalMode": "none"
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/jobs/search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      titles: { include: ['Software Engineer'] },
      location: { regions: ['North America'] },
      postedWithin: 30,
      limit: 5,
      totalMode: 'none'
    })
  });
  const data = await response.json();
  console.log(`${data.signals.length} jobs`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v3/jobs/search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'titles': {'include': ['Software Engineer']},
          'location': {'regions': ['North America']},
          'postedWithin': 30,
          'limit': 5,
          'totalMode': 'none'
      }
  )
  data = response.json()
  print(f"{len(data['signals'])} jobs")
  ```
</CodeGroup>

Use this fuller body when you want to combine all supported filters:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "titles": {
    "include": ["Software Engineer", "DevOps Engineer"],
    "exclude": ["Intern"],
    "vector": false
  },
  "occupationTaxonomy": {
    "level1": ["Engineering"],
    "level2": ["DevOps"],
    "level3": []
  },
  "companies": {
    "include": ["leadmagic.io"],
    "exclude": ["meta.com"],
    "ids": []
  },
  "location": {
    "countries": ["US", "GB"],
    "regions": [],
    "states": [],
    "cities": []
  },
  "tags": {
    "include": ["kubernetes", "terraform"],
    "exclude": []
  },
  "salary": {
    "min_usd": 120000,
    "max_usd": 280000
  },
  "seniority": ["SE", "EX"],
  "languages": ["en"],
  "hasRemote": true,
  "jobTypeIds": [],
  "industryIds": [],
  "companyTypeIds": [],
  "companySizeCodes": [],
  "postedAfter": "2026-05-01",
  "postedWithin": 30,
  "workModes": [1, 2],
  "includeAgencies": false,
  "includeCompany": true,
  "includeDescription": false,
  "includeFacets": false,
  "includeOccupationTaxonomy": true,
  "dryRun": false,
  "limit": 25,
  "totalMode": "capped",
  "mode": "fast",
  "autoResolve": true,
  "_query_budget_ms": 8000
}
```

## Request Parameters

<ParamField type="string[]">
  Job title terms. Uses indexed title search.
</ParamField>

<ParamField type="string[]">
  Title terms to exclude.
</ParamField>

<ParamField type="boolean">
  Request semantic title matching where available.
</ParamField>

<ParamField type="string[] | integer[]">
  Broad occupation families. Results include `occupation_taxonomy.level1.id` and `occupation_taxonomy.level1.name`.
</ParamField>

<ParamField type="string[] | integer[]">
  Mid-level occupation categories. Results include `occupation_taxonomy.level2.id` and `occupation_taxonomy.level2.name`.
</ParamField>

<ParamField type="string[] | integer[]">
  Specific normalized job titles. Results include `occupation_taxonomy.level3.id` and `occupation_taxonomy.level3.name`.
</ParamField>

<ParamField type="string[]">
  Company domains or names. Domains are resolved exactly; names use fuzzy helper matching.
</ParamField>

<ParamField type="string[]">
  Company domains or names to exclude.
</ParamField>

<ParamField type="integer[]">
  Exact company IDs from helper responses.
</ParamField>

<ParamField type="string[] | integer[]">
  Country codes, names, or IDs.
</ParamField>

<ParamField type="string[] | integer[]">
  Region names or IDs.
</ParamField>

<ParamField type="string[] | integer[]">
  State or province names or IDs.
</ParamField>

<ParamField type="string[] | integer[]">
  City names or IDs.
</ParamField>

<ParamField type="string">
  Free-text location. Use `mode: "deep"` when you need text location matching.
</ParamField>

<ParamField type="string[] | integer[]">
  Tag names or IDs. Tags are resolved before search and can attach occupation taxonomy metadata.
</ParamField>

<ParamField type="string[] | integer[]">
  Tag names or IDs to exclude.
</ParamField>

<ParamField type="integer">
  Minimum normalized USD salary.
</ParamField>

<ParamField type="integer">
  Maximum normalized USD salary.
</ParamField>

<ParamField type="string[]">
  Experience levels. Use `EN`, `MI`, `SE`, or `EX`.
</ParamField>

<ParamField type="string[]">
  Two-letter language codes such as `en`, `de`, or `fr`.
</ParamField>

<ParamField type="boolean">
  Filter for jobs that support remote work.
</ParamField>

<ParamField type="integer[]">
  Work mode IDs. Allowed values are `1`, `2`, and `3`.
</ParamField>

<ParamField type="integer[]">
  Job type IDs from the job type catalog.
</ParamField>

<ParamField type="integer[]">
  Company industry IDs.
</ParamField>

<ParamField type="integer[]">
  Company type IDs.
</ParamField>

<ParamField type="integer[]">
  Company size bucket codes.
</ParamField>

<ParamField type="string">
  Include jobs posted on or after a date in `YYYY-MM-DD` format.
</ParamField>

<ParamField type="string">
  Include jobs posted before or on a date in `YYYY-MM-DD` format.
</ParamField>

<ParamField type="integer">
  Include jobs posted within the last N days.
</ParamField>

<ParamField type="boolean">
  Include staffing/recruiting agency jobs. Defaults to excluding agencies.
</ParamField>

<ParamField type="integer">
  Number of jobs to return. Maximum is 50.
</ParamField>

<ParamField type="object">
  Cursor from `pagination.next_cursor` for the next page.
</ParamField>

<ParamField type="boolean">
  Include a short description snippet. Use only when you need description text.
</ParamField>

<ParamField type="boolean">
  Include the company object in each returned job.
</ParamField>

<ParamField type="boolean">
  Request facet metadata where available.
</ParamField>

<ParamField type="boolean">
  Include normalized occupation taxonomy fields in each returned job.
</ParamField>

<ParamField type="string">
  Count mode. Use `none`, `capped`, or `exact`.
</ParamField>

<ParamField type="string">
  Query mode. Use `fast` by default. Use `deep` only for broader text matching.
</ParamField>

<ParamField type="boolean">
  Validate/resolve the request without charging credits.
</ParamField>

<ParamField type="boolean">
  Resolve friendly strings like company domains, countries, tags, and occupation taxonomy values before search.
</ParamField>

<ParamField type="integer">
  Optional internal query budget hint. Omit unless instructed by support.
</ParamField>

## Built-in Search Modes

Facets, semantic title matching, and deep matching are all part of `POST /v3/jobs/search`. You do not need separate endpoints.

| Capability              | Request field         | Use when                                                                                |
| ----------------------- | --------------------- | --------------------------------------------------------------------------------------- |
| Semantic title matching | `titles.vector: true` | Title intent is broader than exact keywords, such as `platform operations engineer`.    |
| Facets                  | `includeFacets: true` | Your UI needs filter counts or summary metadata alongside the returned jobs.            |
| Deep matching           | `mode: "deep"`        | Standard filters are too strict and you need broader matching across searchable fields. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "titles": {
    "include": ["AI infrastructure engineer"],
    "vector": true
  },
  "tags": { "include": ["kubernetes", "machine learning"] },
  "location": { "countries": ["US"] },
  "includeFacets": true,
  "mode": "deep",
  "includeDescription": true,
  "limit": 10,
  "totalMode": "capped"
}
```

## Response

<ResponseField name="signals" type="object[]">
  Returned jobs/signals.
</ResponseField>

<ResponseField name="signals[].title" type="string">
  Job title.
</ResponseField>

<ResponseField name="signals[].company" type="object">
  Company object with `id`, `name`, `website_url`, and (when available) `linkedin_url`.
</ResponseField>

<ResponseField name="signals[].location" type="string | null">
  Display location string.
</ResponseField>

<ResponseField name="signals[].salary" type="object">
  Salary fields, including normalized USD ranges where available.
</ResponseField>

<ResponseField name="signals[].posted_at" type="string | null">
  Published timestamp/date for the job.
</ResponseField>

<ResponseField name="signals[].has_remote" type="boolean">
  Whether the job supports remote work.
</ResponseField>

<ResponseField name="signals[].application_url" type="string">
  Application URL for the job posting.
</ResponseField>

<ResponseField name="signals[].job_types" type="object[]">
  Job type metadata.
</ResponseField>

<ResponseField name="signals[].tags" type="object[]">
  Full tag metadata.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level1" type="object">
  Broad occupation taxonomy level with `id` and `name`.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level2" type="object">
  Mid-level occupation taxonomy level with `id` and `name`.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level3" type="object">
  Specific normalized title level with `id` and `name`.
</ResponseField>

<ResponseField name="total" type="integer">
  Total matching jobs (bounded by `totalMode`).
</ResponseField>

<ResponseField name="totalMode" type="string">
  Echoes the count mode used (`none`, `capped`, or `exact`).
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination wrapper with `next_cursor` for cursor-based pagination.
</ResponseField>

<ResponseField name="resolved" type="object">
  How input filters were resolved (only present when `autoResolve: true`).
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Non-fatal notes about fallback behavior, unsupported combinations, or broad matching.
</ResponseField>

<ResponseField name="metadata.query_path" type="string">
  Query path describing how the search was executed, such as `title+geo_bridge+vector_requested`.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Finalized credits charged for this request.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "signals": [
    {
      "title": "Full-Stack Software Engineer",
      "company": {
        "id": 102413,
        "name": "Example Company",
        "website_url": "https://example.com"
      },
      "occupation_taxonomy": {
        "level1": { "id": 1, "name": "Developer" },
        "level2": { "id": 20, "name": "Full-Stack Development" },
        "level3": { "id": 774, "name": "Full-stack software engineer" }
      }
    }
  ],
  "total": 3,
  "totalMode": "capped",
  "credits_consumed": 1
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Resolve companies, tags, occupation taxonomy values, titles, locations, and catalogs.
  </Card>

  <Card title="Search Stats" icon="chart-simple" href="/v1/reference/search-stats">
    See coverage, capabilities, and top dimensions across Jobs, Company, and People Search.
  </Card>

  <Card title="Job Search v2" icon="briefcase" href="/v1/reference/jobs-finder">
    Previous jobs finder shape.
  </Card>
</CardGroup>


# Job Search Catalogs
Source: https://leadmagic.io/docs/v1/reference/job-search-catalogs

get /v3/jobs/search/catalogs
Fetch filter catalogs and dimension summaries for Job Search.

# Job Search Catalogs

Fetch the full set of filter catalogs for [Job Search](/docs/v1/reference/job-search) — countries, regions, job types, industries, company types, seniority values, and dataset stats — in one call. Use this to populate static filter dropdowns in your UI.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                            |
    | -------- | -------------------------------- |
    | **Cost** | **FREE** — 0 credits per request |

    <Tip>
      Cache the catalog response on your side — these dimensions change infrequently. Refresh on a daily or weekly schedule.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/catalogs' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/jobs/search/catalogs', {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const catalogs = await response.json();
  console.log(Object.keys(catalogs));
  // ['countries', 'regions', 'job_types', 'industries', 'company_types', 'seniority', 'stats']
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/catalogs',
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  catalogs = response.json()
  print(list(catalogs.keys()))
  ```
</CodeGroup>

***

## Request Parameters

This endpoint takes no parameters.

***

## Response

<ResponseField name="countries" type="object[]">
  Country catalog with `id` and `name`.
</ResponseField>

<ResponseField name="regions" type="object[]">
  Region catalog with `id` and `name`.
</ResponseField>

<ResponseField name="job_types" type="object[]">
  Job-type catalog (full-time, part-time, contract, etc.).
</ResponseField>

<ResponseField name="industries" type="object[]">
  Industry catalog.
</ResponseField>

<ResponseField name="company_types" type="object[]">
  Company-type catalog (private, public, non-profit, etc.).
</ResponseField>

<ResponseField name="seniority" type="object[]">
  Seniority catalog.
</ResponseField>

<ResponseField name="stats" type="object">
  Public-safe Jobs Search coverage stats included with the catalog response.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "countries": [
    { "id": 840, "name": "United States" },
    { "id": 826, "name": "United Kingdom" }
  ],
  "job_types": [
    { "id": 1, "name": "Full-time" },
    { "id": 2, "name": "Part-time" },
    { "id": 3, "name": "Contract" }
  ],
  "industries": [
    { "id": 96, "name": "Software" }
  ],
  "company_types": [
    { "id": 1, "name": "Private" },
    { "id": 2, "name": "Public" }
  ],
  "seniority": [
    { "id": 1, "name": "Entry" },
    { "id": 5, "name": "VP" }
  ],
  "stats": {
    "total_jobs_indexed": 12500000,
    "freshness_days": 1
  }
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search Locations" icon="location-dot" href="/v1/reference/job-search-locations">
    Search location filters (states, cities) not in the static catalog.
  </Card>

  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Use catalog IDs in `jobTypeIds`, `industryIds`, `companyTypeIds`, etc.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all filter helpers.
  </Card>
</CardGroup>


# Job Search Companies
Source: https://leadmagic.io/docs/v1/reference/job-search-companies

get /v3/jobs/search/companies
Autocomplete and resolve companies for Job Search filters.

# Job Search Companies

Company autocomplete and card data for [Job Search](/docs/v1/reference/job-search) filter builders. Use this helper to resolve a free-text company name or domain into a canonical company ID before running search.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                        |
    | -------------- | ---------------------------- |
    | **Cost**       | FREE — 0 credits per request |
    | **No Results** | FREE                         |

    <Tip>
      The main [Job Search](/docs/v1/reference/job-search) route can auto-resolve companies when `autoResolve` is `true`. Use this helper directly when you're building autocomplete or filter-builder UIs.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/companies?q=leadmagic&limit=10' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const url = new URL('https://api.leadmagic.io/v3/jobs/search/companies');
  url.searchParams.set('q', 'leadmagic');
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(data.companies);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/companies',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      params={'q': 'leadmagic', 'limit': 10}
  )
  data = response.json()
  print(data['companies'])
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Free-text company name or domain to search for.
</ParamField>

<ParamField type="string">
  Exact company domain to look up (e.g. `leadmagic.io`).
</ParamField>

<ParamField type="integer">
  Number of company candidates to return.
</ParamField>

***

## Response

<ResponseField name="companies" type="object[]">
  Matching company candidates with `id`, `name`, `domain`, and any available card data.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "companies": [
    {
      "id": 102413,
      "name": "LeadMagic",
      "domain": "leadmagic.io",
      "logo_domain": "leadmagic.io"
    }
  ]
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Run search using the resolved company IDs from this helper.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all Job Search filter helpers.
  </Card>

  <Card title="Job Search Resolve" icon="arrows-turn-to-dots" href="/v1/reference/job-search-helpers#resolve-a-search">
    Resolve a full draft search request in one call.
  </Card>
</CardGroup>


# Job Search Helpers
Source: https://leadmagic.io/docs/v1/reference/job-search-helpers

post /v3/jobs/search/resolve
Resolve companies, tags, occupation taxonomy values, titles, locations, and catalogs for Job Search.

# Job Search Helpers

Helpers let your frontend send friendly values (a company name, a tag, a country code) and get back canonical filter IDs before running [Job Search](/docs/v1/reference/job-search). Use them for autocomplete, filter builders, and preflight validation screens.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Helper                                                                     | Credits  |
    | -------------------------------------------------------------------------- | -------- |
    | **Resolve** (this page)                                                    | **FREE** |
    | **Companies**                                                              | **FREE** |
    | **Tags**, **Titles**, **Occupation Taxonomy**, **Locations**, **Catalogs** | **FREE** |

    <Tip>
      The main [Job Search](/docs/v1/reference/job-search) route auto-resolves friendly values when `autoResolve: true`. Use these helpers directly when you want to show choices before search, or to avoid ambiguous fuzzy matches in production.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

Resolve a draft search request into canonical filter IDs and labels:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/jobs/search/resolve' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "companies": { "include": ["leadmagic.io"] },
      "tags": { "include": ["kubernetes"] },
      "occupationTaxonomy": { "level2": ["DevOps"] },
      "location": { "countries": ["US"] },
      "titles": { "include": ["Site Reliability Engineer"] }
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/jobs/search/resolve', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies: { include: ['leadmagic.io'] },
      tags: { include: ['kubernetes'] },
      occupationTaxonomy: { level2: ['DevOps'] },
      location: { countries: ['US'] },
      titles: { include: ['Site Reliability Engineer'] }
    })
  });
  const data = await response.json();
  console.log(data.resolved);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v3/jobs/search/resolve',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'companies': {'include': ['leadmagic.io']},
          'tags': {'include': ['kubernetes']},
          'occupationTaxonomy': {'level2': ['DevOps']},
          'location': {'countries': ['US']},
          'titles': {'include': ['Site Reliability Engineer']}
      }
  )
  data = response.json()
  print(data['resolved'])
  ```
</CodeGroup>

***

## Autocomplete endpoints

Each autocomplete helper has its own page with full request/response docs and an interactive playground:

<CardGroup>
  <Card title="Companies" icon="building" href="/v1/reference/job-search-companies">
    `GET /v3/jobs/search/companies?q=leadmagic` — FREE
  </Card>

  <Card title="Tags" icon="tag" href="/v1/reference/job-search-tags">
    `GET /v3/jobs/search/tags?q=kuber` — FREE
  </Card>

  <Card title="Titles" icon="briefcase" href="/v1/reference/job-search-titles">
    `GET /v3/jobs/search/titles?q=devops engineer` — FREE
  </Card>

  <Card title="Occupation Taxonomy" icon="diagram-project" href="/v1/reference/job-search-occupation-taxonomy">
    `GET /v3/jobs/search/occupation-taxonomy?q=DevOps&level=level2` — FREE
  </Card>

  <Card title="Locations" icon="location-dot" href="/v1/reference/job-search-locations">
    `GET /v3/jobs/search/locations?type=country&q=United` — FREE
  </Card>

  <Card title="Catalogs" icon="list" href="/v1/reference/job-search-catalogs">
    `GET /v3/jobs/search/catalogs` — FREE
  </Card>
</CardGroup>

***

## Resolve request parameters

The resolve endpoint accepts the same filter blocks as [Job Search](/docs/v1/reference/job-search), but instead of running a search it returns canonical IDs and labels for whatever you passed in.

<ParamField type="object">
  Company filters: `include`, `exclude`, and `ids` arrays.
</ParamField>

<ParamField type="object">
  Tag filters: `include` and `exclude` arrays of names or IDs.
</ParamField>

<ParamField type="object">
  Taxonomy filters: `level1`, `level2`, `level3` arrays of names or IDs.
</ParamField>

<ParamField type="object">
  Location filters: `countries`, `regions`, `states`, `cities`.
</ParamField>

<ParamField type="object">
  Title filters: `include` and `exclude` arrays.
</ParamField>

***

## Response

<ResponseField name="resolved" type="object">
  Mirrors the request shape, with each input value replaced by `{ id, name, ... }` objects for canonical filter IDs.
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Any inputs that could not be resolved (typos, ambiguous matches, unsupported values).
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Always `1` for this helper.
</ResponseField>

<Tip>
  Cache resolve responses for the lifetime of a user session. The same friendly inputs will resolve to the same canonical IDs.
</Tip>

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Run search with the resolved filter IDs.
  </Card>

  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Discover which filter dimensions are searchable.
  </Card>

  <Card title="Job Search Catalogs" icon="list" href="/v1/reference/job-search-catalogs">
    Full static filter catalogs (countries, job types, etc.).
  </Card>

  <Card title="Facets in Job Search" icon="filter" href="/v1/reference/job-search">
    Get filter counts alongside search results.
  </Card>
</CardGroup>


# Job Search Locations
Source: https://leadmagic.io/docs/v1/reference/job-search-locations

get /v3/jobs/search/locations
Autocomplete countries, regions, states, and cities for Job Search.

# Job Search Locations

Location autocomplete for [Job Search](/docs/v1/reference/job-search). Resolve country, region, state, and city candidates into canonical IDs for exact geo filtering.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                            |
    | -------- | -------------------------------- |
    | **Cost** | **FREE** — 0 credits per request |

    <Tip>
      Location autocomplete is free across all four location types (country, region, state, city).
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/locations?type=country&q=United&limit=10' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const url = new URL('https://api.leadmagic.io/v3/jobs/search/locations');
  url.searchParams.set('type', 'country');
  url.searchParams.set('q', 'United');
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(data.locations);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/locations',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      params={'type': 'country', 'q': 'United', 'limit': 10}
  )
  data = response.json()
  print(data['locations'])
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Free-text location query (e.g. `United`, `Berlin`, `California`).
</ParamField>

<ParamField type="string">
  Location type to search. One of `country`, `region`, `state`, or `city`.
</ParamField>

<ParamField type="integer">
  Number of location candidates to return.
</ParamField>

***

## Response

<ResponseField name="locations" type="object[]">
  Matching locations with `id`, `name`, and `type`.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "locations": [
    { "id": 840, "name": "United States", "type": "country" },
    { "id": 826, "name": "United Kingdom", "type": "country" }
  ]
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Pass resolved `location.countries / regions / states / cities` into search.
  </Card>

  <Card title="Job Country (Legacy)" icon="globe" href="/v1/reference/job-country">
    Legacy v1 country list — prefer this v3 helper for new integrations.
  </Card>

  <Card title="Job Regions (Legacy)" icon="map" href="/v1/reference/job-regions">
    Legacy v1 region list.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all filter helpers.
  </Card>
</CardGroup>


# Job Search Occupation Taxonomy
Source: https://leadmagic.io/docs/v1/reference/job-search-occupation-taxonomy

get /v3/jobs/search/occupation-taxonomy
Autocomplete occupation taxonomy values for Job Search.

# Job Search Occupation Taxonomy

Occupation taxonomy autocomplete for [Job Search](/docs/v1/reference/job-search). The taxonomy is a broad-to-specific hierarchy that maps free-text occupation queries to canonical IDs and labels.

| Level    | Meaning                 | Example           |
| -------- | ----------------------- | ----------------- |
| `level1` | Broad occupation family | "Engineer"        |
| `level2` | Occupation category     | "DevOps"          |
| `level3` | Normalized job title    | "DevOps Engineer" |

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                            |
    | -------- | -------------------------------- |
    | **Cost** | **FREE** — 0 credits per request |

    <Tip>
      Occupation taxonomy autocomplete is free. Use this for filter-builder UIs that need a structured taxonomy picker.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/occupation-taxonomy?q=DevOps&level=level2&limit=10' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const url = new URL('https://api.leadmagic.io/v3/jobs/search/occupation-taxonomy');
  url.searchParams.set('q', 'DevOps');
  url.searchParams.set('level', 'level2');
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(data.occupation_taxonomy);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/occupation-taxonomy',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      params={'q': 'DevOps', 'level': 'level2', 'limit': 10}
  )
  data = response.json()
  print(data['occupation_taxonomy'])
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Free-text occupation query.
</ParamField>

<ParamField type="string">
  Restrict results to a single level. One of `level1`, `level2`, or `level3`. Omit to return matches across all levels.
</ParamField>

<ParamField type="integer">
  Number of taxonomy entries to return.
</ParamField>

***

## Response

<ResponseField name="occupation_taxonomy" type="object[]">
  Matching taxonomy entries with `id`, `name`, level metadata, and a human-readable `path`.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Always `0` for this helper.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "occupation_taxonomy": [
    {
      "id": 1700834,
      "name": ".NET & DevOps",
      "type": 2,
      "level1": { "id": 7, "name": "Engineer" },
      "level2": { "id": 1700834, "name": ".NET & DevOps" },
      "level3": null,
      "path": "Engineer > .NET & DevOps"
    }
  ],
  "credits_consumed": 0
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Pass `occupationTaxonomy.level1/2/3` arrays into search.
  </Card>

  <Card title="Job Search Titles" icon="briefcase" href="/v1/reference/job-search-titles">
    Find specific job titles within a taxonomy branch.
  </Card>

  <Card title="Job Search Tags" icon="tag" href="/v1/reference/job-search-tags">
    Tags often map to taxonomy nodes — pair them in filter builders.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all filter helpers.
  </Card>
</CardGroup>


# Job Search Tags
Source: https://leadmagic.io/docs/v1/reference/job-search-tags

get /v3/jobs/search/tags
Autocomplete tags with occupation taxonomy metadata for Job Search.

# Job Search Tags

Tag autocomplete for [Job Search](/docs/v1/reference/job-search) filter builders. Tags include tools, platforms, skills, and other normalized hiring-signal dimensions (e.g. `kubernetes`, `terraform`, `react`).

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                            |
    | -------- | -------------------------------- |
    | **Cost** | **FREE** — 0 credits per request |

    <Tip>
      Tag, title, occupation taxonomy, location, and catalog helpers are all zero-credit. The companies helper and resolve endpoint are the only paid Job Search helpers.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/tags?q=kuber&limit=10' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const url = new URL('https://api.leadmagic.io/v3/jobs/search/tags');
  url.searchParams.set('q', 'kuber');
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(data.tags);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/tags',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      params={'q': 'kuber', 'limit': 10}
  )
  data = response.json()
  print(data['tags'])
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Free-text tag query (e.g. `kuber` matches `kubernetes`, `kubectl`, etc.).
</ParamField>

<ParamField type="integer">
  Optional tag-type ID to scope the search. Use [Job Search Catalogs](/docs/v1/reference/job-search-catalogs) to discover tag-type IDs.
</ParamField>

<ParamField type="integer">
  Number of tag candidates to return.
</ParamField>

***

## Response

<ResponseField name="tags" type="object[]">
  Matching tags with `id`, `name`, and any associated occupation taxonomy metadata.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tags": [
    {
      "id": 482,
      "name": "kubernetes",
      "tag_type": 2,
      "occupation_taxonomy": {
        "level1": { "id": 1, "name": "Developer" },
        "level2": { "id": 20, "name": "DevOps" }
      }
    }
  ]
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Run search with the resolved tag IDs.
  </Card>

  <Card title="Job Search Catalogs" icon="list" href="/v1/reference/job-search-catalogs">
    Discover tag-type IDs and other filter dimensions.
  </Card>

  <Card title="Occupation Taxonomy" icon="diagram-project" href="/v1/reference/job-search-occupation-taxonomy">
    Explore the taxonomy levels associated with tags.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all filter helpers.
  </Card>
</CardGroup>


# Job Search Titles
Source: https://leadmagic.io/docs/v1/reference/job-search-titles

get /v3/jobs/search/titles
Autocomplete job titles for Job Search title filters.

# Job Search Titles

Title autocomplete for [Job Search](/docs/v1/reference/job-search) filter builders. Discover searchable title phrases with occupation taxonomy metadata before running search.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric   | Value                            |
    | -------- | -------------------------------- |
    | **Cost** | **FREE** — 0 credits per request |

    <Tip>
      Title autocomplete is free. In [Job Search](/docs/v1/reference/job-search), set `titles.vector: true` when exact title keywords are too narrow for your users.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Contact us for enterprise plans — [support@leadmagic.io](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.leadmagic.io/v3/jobs/search/titles?q=devops%20engineer&limit=10' \
    -H 'X-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const url = new URL('https://api.leadmagic.io/v3/jobs/search/titles');
  url.searchParams.set('q', 'devops engineer');
  url.searchParams.set('limit', '10');

  const response = await fetch(url, {
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  });
  const data = await response.json();
  console.log(data.titles);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      'https://api.leadmagic.io/v3/jobs/search/titles',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      params={'q': 'devops engineer', 'limit': 10}
  )
  data = response.json()
  print(data['titles'])
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Free-text title query.
</ParamField>

<ParamField type="integer">
  Number of title candidates to return.
</ParamField>

***

## Response

<ResponseField name="titles" type="object[]">
  Matching titles with `id`, `name`, and any associated occupation taxonomy metadata.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "titles": [
    {
      "id": 774,
      "name": "DevOps Engineer",
      "occupation_taxonomy": {
        "level1": { "id": 1, "name": "Developer" },
        "level2": { "id": 20, "name": "DevOps" },
        "level3": { "id": 774, "name": "DevOps Engineer" }
      }
    }
  ]
}
```

***

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Run search using the resolved title phrases.
  </Card>

  <Card title="Semantic Title Matching" icon="wand-sparkles" href="/v1/reference/job-search">
    Use `titles.vector: true` when exact keywords are too narrow.
  </Card>

  <Card title="Occupation Taxonomy" icon="diagram-project" href="/v1/reference/job-search-occupation-taxonomy">
    Browse the canonical taxonomy levels.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Index of all filter helpers.
  </Card>
</CardGroup>


# Job Type
Source: https://leadmagic.io/docs/v1/reference/job-types

get /v1/jobs/job-types
Use this API to retrieve the Job Type ID, which can then be used in the Jobs Finder API to filter jobs by Job Type.

# Employment Types

Get all supported employment type codes for filtering job searches.

<Info>
  **Free Endpoint** — No credits charged. Cache results locally.
</Info>

## Common Types

| Type       | Description                   |
| ---------- | ----------------------------- |
| Full-time  | Standard full-time employment |
| Part-time  | Part-time positions           |
| Contract   | Temporary/contract work       |
| Internship | Internship programs           |
| Temporary  | Short-term positions          |

<Tip>
  Combine with `experience_level` for precise targeting (e.g., "Full-time Senior" roles).
</Tip>

## Related

<CardGroup>
  <Card title="Jobs Finder" icon="briefcase" href="/v1/reference/jobs-finder">
    Use `job_type_id` to filter results
  </Card>

  <Card title="Company Types" icon="building" href="/v1/reference/job-company-types">
    Filter by company size
  </Card>
</CardGroup>


# Job Search
Source: https://leadmagic.io/docs/v1/reference/jobs-finder

post /v1/jobs/jobs-finder
LeadMagic's Jobs Finder

# Job Search

<Warning>
  This is the legacy v1 jobs endpoint (`POST /v1/jobs/jobs-finder`). For new integrations, use the [Job Search](/docs/v1/reference/job-search) endpoint backed by `/v3/jobs/search`, which supports occupation taxonomy, helper resolution, vector search, and richer filters. This page remains available for existing integrations.
</Warning>

Search and filter job listings across companies with a straightforward page-based jobs search.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                         |
    | -------------- | ----------------------------- |
    | **Cost**       | **1 credit** per job returned |
    | **No Results** | **FREE** if no jobs found     |

    <Tip>
      **Hiring Signals:** Companies with open positions are actively investing and growing - perfect timing for sales outreach.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 100                 |
    | **Burst Capacity**  | \~2 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/jobs/jobs-finder' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "job_title": "Sales Director",
      "country_id": "US",
      "experience_level": "senior",
      "has_remote": true,
      "posted_within": 14,
      "page": 1,
      "per_page": 20
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/jobs/jobs-finder', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      job_title: 'Sales Director',
      country_id: 'US',
      experience_level: 'senior',
      has_remote: true,
      posted_within: 14,
      page: 1,
      per_page: 20
    })
  });
  const { results, total_count } = await response.json();
  console.log(`Found ${total_count} jobs`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/jobs/jobs-finder',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'job_title': 'Sales Director',
          'country_id': 'US',
          'experience_level': 'senior',
          'has_remote': True,
          'posted_within': 14,
          'page': 1,
          'per_page': 20
      }
  )
  data = response.json()
  print(f"Found {data['total_count']} jobs")
  ```
</CodeGroup>

***

## Request Parameters

All fields are optional - combine them to filter results:

<Tabs>
  <Tab title="Company Filters" icon="building">
    <ParamField type="string">
      Company name to search
    </ParamField>

    <ParamField type="string">
      Company domain
    </ParamField>

    <ParamField type="integer">
      Company type ID (see [Company Types](/docs/v1/reference/job-company-types))
    </ParamField>

    <ParamField type="integer">
      Industry ID (see [Industries](/docs/v1/reference/job-industry))
    </ParamField>

    <ParamField type="integer">
      Minimum company size
    </ParamField>

    <ParamField type="integer">
      Maximum company size
    </ParamField>
  </Tab>

  <Tab title="Job Filters" icon="briefcase">
    <ParamField type="string">
      Title keyword search
    </ParamField>

    <ParamField type="string">
      Description keyword search
    </ParamField>

    <ParamField type="string">
      Level: `entry`, `mid`, `senior`, `executive`
    </ParamField>

    <ParamField type="integer">
      Job type ID (see [Job Types](/docs/v1/reference/job-types))
    </ParamField>

    <ParamField type="boolean">
      Filter for remote work options
    </ParamField>
  </Tab>

  <Tab title="Location Filters" icon="location-dot">
    <ParamField type="string">
      City or region name
    </ParamField>

    <ParamField type="string">
      Specific city
    </ParamField>

    <ParamField type="string">
      Country code (US, UK, etc.) - see [Countries](/docs/v1/reference/job-country)
    </ParamField>

    <ParamField type="integer">
      State/region ID (see [Regions](/docs/v1/reference/job-regions))
    </ParamField>
  </Tab>

  <Tab title="Date Filters" icon="calendar">
    <ParamField type="integer">
      Days since posting (e.g., 14 for last 2 weeks)
    </ParamField>

    <ParamField type="string">
      Posted on or after (YYYY-MM-DD)
    </ParamField>

    <ParamField type="string">
      Posted on or before (YYYY-MM-DD)
    </ParamField>
  </Tab>

  <Tab title="Pagination" icon="list-ol">
    <ParamField type="integer">
      Page number
    </ParamField>

    <ParamField type="integer">
      Results per page (max: 50)
    </ParamField>
  </Tab>
</Tabs>

***

## Response

<ResponseField name="total_count" type="integer">
  Total jobs matching filters
</ResponseField>

<ResponseField name="page" type="integer">
  Current page
</ResponseField>

<ResponseField name="per_page" type="integer">
  Results per page
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Total pages available
</ResponseField>

<ResponseField name="credits_consumed" type="integer">
  Credits used (1 per job returned)
</ResponseField>

<ResponseField name="results" type="array">
  Array of job listings
</ResponseField>

### Job Object

| Field                     | Type    | Description                   |
| ------------------------- | ------- | ----------------------------- |
| `title`                   | string  | Job title                     |
| `company.name`            | string  | Company name                  |
| `company.website_url`     | string  | Company website               |
| `company.b2b_profile_url` | string  | Company profile URL           |
| `location`                | string  | Job location                  |
| `types`                   | array   | Job types (Full-time, etc.)   |
| `experience_level`        | string  | Entry, Mid, Senior, Executive |
| `has_remote`              | boolean | Remote work available         |
| `published`               | string  | Posted date                   |
| `description`             | string  | Full job description          |
| `application_url`         | string  | Apply link                    |

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_count": 142,
  "page": 1,
  "per_page": 20,
  "total_pages": 8,
  "credits_consumed": 20,
  "results": [
    {
      "title": "VP of Sales",
      "company": {
        "name": "LeadMagic",
        "website_url": "https://leadmagic.io",
        "b2b_profile_url": "https://linkedin.com/company/leadmagichq"
      },
      "location": "San Francisco, CA",
      "types": ["Full-time"],
      "experience_level": "Executive",
      "has_remote": true,
      "published": "2026-01-28",
      "description": "Leading enterprise sales team...",
      "application_url": "https://leadmagic.io/careers/vp-sales"
    }
  ]
}
```

***

## Reference Endpoints

Get valid filter IDs from these endpoints (all free, no credits):

<CardGroup>
  <Card title="Countries" icon="globe" href="/v1/reference/job-country">
    Get country IDs
  </Card>

  <Card title="Regions" icon="map" href="/v1/reference/job-regions">
    Get region/state IDs
  </Card>

  <Card title="Job Types" icon="list" href="/v1/reference/job-types">
    Get job type IDs
  </Card>

  <Card title="Company Types" icon="building" href="/v1/reference/job-company-types">
    Get company type IDs
  </Card>

  <Card title="Industries" icon="industry" href="/v1/reference/job-industry">
    Get industry IDs
  </Card>
</CardGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Filter by posted_within" icon="calendar">
    Use `posted_within: 14` to focus on companies actively hiring right now.
  </Accordion>

  <Accordion title="Target your buyer's role" icon="user-tie">
    Companies hiring for your buyer's role have active budget and immediate need.
  </Accordion>

  <Accordion title="Chain with Role Finder" icon="link">
    After finding hiring companies, use [Role Finder](/docs/v1/reference/role-finder) to find decision makers.
  </Accordion>

  <Accordion title="Use pagination wisely" icon="list-ol">
    Start with `per_page: 20` and paginate. Don't request large pages you won't use.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Intelligence" icon="lightbulb">
    Companies hiring for your buyer persona have active budget.
  </Card>

  <Card title="ABM Targeting" icon="bullseye">
    Find companies hiring roles that need your product.
  </Card>

  <Card title="Market Research" icon="chart-line">
    Analyze hiring trends across industries.
  </Card>

  <Card title="Recruiting" icon="user-plus">
    Discover open positions matching candidate profiles.
  </Card>
</CardGroup>


# Meta Ads Search
Source: https://leadmagic.io/docs/v1/reference/meta-ads-search

post /v1/ads/meta-ads-search
Search for Meta Ads by company domain or name.

# Meta Ads

Search for Meta (Facebook/Instagram) ads run by a company. Analyze social media advertising strategies and creative approaches.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric          | Value                      |
    | --------------- | -------------------------- |
    | **Cost**        | **0.2 credits** per search |
    | **Calculation** | 5 searches = 1 credit      |
    | **No Results**  | **FREE** if no ads found   |

    <Tip>
      Very cost-effective for social ad intelligence at just 0.2 credits per search.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/ads/meta-ads-search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"company_domain": "leadmagic.io"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/ads/meta-ads-search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_domain: 'leadmagic.io' })
  });
  const data = await response.json();
  console.log(`Found ${data.ads?.length || 0} Meta ads`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/ads/meta-ads-search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'company_domain': 'leadmagic.io'}
  )
  data = response.json()
  print(f"Found {len(data.get('ads', []))} Meta ads")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Company website domain (preferred).
</ParamField>

<ParamField type="string">
  Company name.
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` (or both).
</Warning>

***

## Response

<ResponseField name="company_name" type="string">
  Company searched
</ResponseField>

<ResponseField name="ads" type="array">
  Array of ad creatives
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (0.2 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Ad Object

| Field             | Type   | Description                  |
| ----------------- | ------ | ---------------------------- |
| `ad_id`           | string | Meta Ad Library ID           |
| `content`         | string | Ad copy/text                 |
| `image_url`       | string | Ad image URL                 |
| `video_url`       | string | Ad video URL (if video ad)   |
| `platform`        | string | Facebook, Instagram, or both |
| `started_running` | string | When ad started              |

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "company_name": "Airbnb",
  "ads": [
    {
      "ad_id": "123456789",
      "content": "Book unique homes and experiences all over the world.",
      "image_url": "https://...",
      "platform": "Facebook, Instagram",
      "started_running": "2026-01-15"
    }
  ],
  "credits_consumed": 0.2,
  "message": "Ads found."
}
```

***

## Success Messages

| Message                          | Meaning                | Cost        |
| -------------------------------- | ---------------------- | ----------- |
| `Ads found.`                     | Meta Ads data returned | 0.2 credits |
| `No ads found for this company.` | No Meta Ads found      | FREE        |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Analyze visual creative" icon="image">
    Meta ads are highly visual. Study image styles and video formats.
  </Accordion>

  <Accordion title="Note platform targeting" icon="bullseye">
    See which platforms (Facebook vs Instagram) competitors prioritize.
  </Accordion>

  <Accordion title="Track seasonal campaigns" icon="calendar">
    Monitor how competitors adjust messaging for seasons and events.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Creative Inspiration" icon="palette">
    Study competitor visual styles and messaging.
  </Card>

  <Card title="Competitive Intelligence" icon="binoculars">
    Monitor competitor social ad strategies.
  </Card>

  <Card title="Market Research" icon="chart-pie">
    Analyze social advertising trends in your industry.
  </Card>

  <Card title="Campaign Planning" icon="calendar">
    Inform your own social ad strategy with competitor insights.
  </Card>
</CardGroup>


# Mobile Finder
Source: https://leadmagic.io/docs/v1/reference/mobile-finder

post /v1/people/mobile-finder
Find a person's mobile phone number using their profile URL or email address.

# Find Mobile

Find mobile phone numbers for direct outreach campaigns. Perfect for sales teams who need direct contact with decision-makers.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                          |
    | -------------- | ------------------------------ |
    | **Cost**       | **5 credits** per mobile found |
    | **No Results** | **FREE** if no mobile found    |

    <Tip>
      You only pay when we successfully find a mobile number. No-result lookups are always free.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/mobile-finder' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"profile_url": "linkedin.com/in/alex-rivera"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/mobile-finder', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      profile_url: 'linkedin.com/in/alex-rivera',
      work_email: 'alex.rivera@example.com'  // Optional: improves match rate
    })
  });
  const data = await response.json();
  if (data.mobile_number) {
    console.log(`Found: ${data.mobile_number}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/mobile-finder',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'profile_url': 'linkedin.com/in/alex-rivera',
          'work_email': 'alex.rivera@example.com'
      }
  )
  data = response.json()
  print(f"Mobile: {data.get('mobile_number', 'Not found')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Professional profile URL or username. Most accurate identifier.
</ParamField>

<ParamField type="string">
  Professional email address. Improves match rate when combined with profile\_url.
</ParamField>

<ParamField type="string">
  Personal email address. Alternative identifier.
</ParamField>

<Warning>
  You must provide at least one identifier: `profile_url`, `work_email`, or `personal_email`.
</Warning>

<Tip>
  Profile URL provides the highest match rate. Combine with email for best results.
</Tip>

***

## Response

<ResponseField name="profile_url" type="string">
  The profile URL used for lookup
</ResponseField>

<ResponseField name="email" type="string">
  The email used for lookup (if provided)
</ResponseField>

<ResponseField name="mobile_number" type="string">
  Mobile phone number found (null if not found)
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (5 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "profile_url": "linkedin.com/in/alex-rivera",
  "mobile_number": "+1-555-123-4567",
  "credits_consumed": 5,
  "message": "Mobile number found."
}
```

***

## Success Messages

| Message                                    | Meaning                             | Cost      |
| ------------------------------------------ | ----------------------------------- | --------- |
| `Mobile number found.`                     | Phone number successfully retrieved | 5 credits |
| `No mobile number found for this contact.` | No phone data available             | FREE      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Combine multiple identifiers" icon="layer-group">
    Provide both profile URL and email when available for the highest match rate.
  </Accordion>

  <Accordion title="Respect contact preferences" icon="shield">
    Mobile numbers are personal data. Use responsibly and respect opt-out requests.
  </Accordion>

  <Accordion title="Verify before large campaigns" icon="badge-check">
    Test a sample before running large batches to ensure quality for your use case.
  </Accordion>

  <Accordion title="Use for high-value outreach" icon="phone">
    Mobile outreach has higher response rates but use sparingly for important contacts.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Outreach" icon="phone-volume">
    Reach decision-makers directly with SMS or calls.
  </Card>

  <Card title="Account-Based Marketing" icon="bullseye">
    Build complete contact profiles for target accounts.
  </Card>

  <Card title="Recruiter Outreach" icon="user-plus">
    Contact candidates directly for high-priority roles.
  </Card>

  <Card title="Customer Success" icon="headset">
    Reach customers quickly for urgent support issues.
  </Card>
</CardGroup>


# People Search
Source: https://leadmagic.io/docs/v1/reference/people-search

post /v3/people/search
Canonical V3 people lookup with all company, title, role, people, channel, and contact-detail filters.

# People Search

`POST /v3/people/search` is the single V3 people lookup endpoint. It replaces the older V3 people variants such as mixed search, ICP search, employees, by-title, and people lookalike.

Use it when you want to search people from either:

* one company, using `company_domain`, `company_name`, or `linkedin_url`
* a criteria-based account set, using `company_filters`

You can combine company filters, people filters, title/role/query intent, contactability requirements, and optional paid contact-detail unlocks in one request.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric            | Value                                                                                               |
    | ----------------- | --------------------------------------------------------------------------------------------------- |
    | **Base cost**     | **1 credit** per returned person                                                                    |
    | **No results**    | **FREE**                                                                                            |
    | **Raw email**     | + **1 credit** per returned email when `include_contact_details: true`                              |
    | **Raw mobile**    | + **5 credits** per returned mobile when `include_contact_details: true`                            |
    | **Authorization** | Reserves up to the requested `limit` and finalizes to returned people plus selected contact details |

    <Tip>
      Raw outreach fields require `include_contact_details: true` and `confirm_credit_charge: true`. Otherwise the API returns masked/locked values and availability flags.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/people/search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "company_domain": "leadmagic.io",
      "titles": ["VP Sales", "Head of Revenue"],
      "required_email": true,
      "limit": 10
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/people/search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company_domain: 'leadmagic.io',
      titles: ['VP Sales', 'Head of Revenue'],
      required_email: true,
      limit: 10
    })
  });

  const data = await response.json();
  console.log(`${data.count} people found`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v3/people/search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'company_domain': 'leadmagic.io',
          'titles': ['VP Sales', 'Head of Revenue'],
          'required_email': True,
          'limit': 10
      }
  )

  data = response.json()
  print(f"{data['count']} people found")
  ```
</CodeGroup>

## Search Across Company Filters

Use `company_filters` when you want to find people across an account list instead of one known company.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "limit": 10,
  "company_filters": {
    "country_codes": ["US"],
    "employee_ranges": ["51 to 200", "201 to 500"],
    "crm_tech": ["Salesforce"],
    "min_valid_email_count": 10
  },
  "people_filters": {
    "contact_job_level": ["VP", "Director"],
    "contact_job_function": ["Sales"]
  },
  "titles": ["VP Sales", "Head of Revenue"],
  "required_email": true
}
```

## Request Body

At least one company identifier or usable `company_filters` object is required.

### Company Targeting

| Field                                | Type     | Description                                                                                                         |
| ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `company_domain`                     | `string` | Single company domain. Preferred for one-company searches.                                                          |
| `company_name`                       | `string` | Single company name.                                                                                                |
| `linkedin_url`                       | `string` | B2B company profile URL or slug.                                                                                    |
| `company_filters` / `companyFilters` | `object` | Criteria-based company set. Supports the same full filter family as [Company Search](/docs/v1/reference/company-search). |

### People Intent

| Field                 | Type       | Description                           |
| --------------------- | ---------- | ------------------------------------- |
| `title` / `job_title` | `string`   | Single title query.                   |
| `titles`              | `string[]` | Up to 12 title terms.                 |
| `roles`               | `string[]` | Role terms combined with title terms. |
| `query`               | `string`   | Free-text people/title query.         |

### People Filters

Pass these inside `people_filters` or `peopleFilters`.

| Field                       | Type       | Description                                                            |
| --------------------------- | ---------- | ---------------------------------------------------------------------- |
| `contact_full_name`         | `string[]` | Full-name text filter. Aliases include `full_name`, `name`.            |
| `contact_first_name`        | `string[]` | First-name text filter.                                                |
| `contact_last_name`         | `string[]` | Last-name text filter.                                                 |
| `contact_email_domain`      | `string[]` | Email-domain filter.                                                   |
| `contact_linkedin_url`      | `string[]` | B2B person profile URL. Aliases include `linkedin_url`, `profile_url`. |
| `contact_linkedin_username` | `string[]` | B2B person profile slug.                                               |
| `contact_job_title`         | `string[]` | Fuzzy title text.                                                      |
| `contact_job_function`      | `string[]` | Normalized function, such as `Sales` or `Engineering`.                 |
| `contact_job_level`         | `string[]` | Normalized seniority, such as `VP`, `Director`, or `C-Team`.           |
| `contact_country_code`      | `string[]` | Country code.                                                          |
| `contact_country`           | `string[]` | Country name text.                                                     |
| `contact_region`            | `string[]` | Region label.                                                          |
| `contact_continent`         | `string[]` | Continent label.                                                       |
| `contact_city`              | `string[]` | City text.                                                             |
| `contact_state`             | `string[]` | State text.                                                            |
| `contact_state_code`        | `string[]` | State/province code.                                                   |
| `contact_linkedin_headline` | `string[]` | Professional headline text.                                            |
| `contact_linkedin_about_me` | `string[]` | Professional about/summary text.                                       |
| `contact_linkedin_industry` | `string[]` | Industry text.                                                         |
| `contact_job_description`   | `string[]` | Job description text.                                                  |
| `contact_languages`         | `string[]` | Language text.                                                         |
| `min_followers`             | `integer`  | Minimum follower count on the person’s public profile.                 |
| `max_followers`             | `integer`  | Maximum follower count on the person’s public profile.                 |
| `min_seniority`             | `integer`  | Minimum computed seniority score.                                      |
| `has_email`                 | `boolean`  | Require email availability.                                            |
| `has_mobile_phone`          | `boolean`  | Require mobile availability.                                           |

### Contactability And Unlocks

| Field                                               | Type                     | Description                                                                                  |
| --------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `required_email` / `requiredEmail`                  | `boolean`                | Only return people with email availability.                                                  |
| `required_mobile` / `requiredMobile`                | `boolean`                | Only return people with mobile availability.                                                 |
| `channels`                                          | `("email" \| "phone")[]` | Legacy alias for contactability requirements.                                                |
| `channel_match` / `channelMatch`                    | `"any" \| "all"`         | Whether a person must match any or all requested channels.                                   |
| `include_contact_details` / `includeContactDetails` | `boolean`                | Return raw paid email/mobile fields. Requires `confirm_credit_charge: true`.                 |
| `include_email` / `includeEmail`                    | `boolean`                | When unlocking details, include and bill raw email values. Defaults to `true`.               |
| `include_mobile` / `includeMobile`                  | `boolean`                | When unlocking details, include and bill raw mobile/direct phone values. Defaults to `true`. |
| `confirm_credit_charge` / `confirmCreditCharge`     | `boolean`                | Required for raw contact-detail unlocks.                                                     |

### Output Controls

| Field                                         | Type                  | Description                                        |
| --------------------------------------------- | --------------------- | -------------------------------------------------- |
| `include_company` / `includeCompany`          | `boolean`             | Include company rows for returned people.          |
| `include_domain_intel` / `includeDomainIntel` | `boolean`             | Include email/domain intelligence where available. |
| `person_fields`                               | `"summary" \| "full"` | Requested person detail level.                     |
| `company_fields`                              | `"summary" \| "full"` | Requested company detail level.                    |
| `limit`                                       | `integer`             | Page size. Maximum is `100`. Defaults to `25`.     |
| `offset`                                      | `integer`             | Offset for pagination.                             |

## Response

<ResponseField name="message" type="string">
  Human-readable result summary.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Finalized credits charged for this request (base people rows plus any unlocked contact details).
</ResponseField>

<ResponseField name="people" type="object[]">
  Returned people. Each row contains `person`, optional `company`, optional `domain_intel`, and an `unlock` object when outreach fields are locked.
</ResponseField>

<ResponseField name="companies" type="object[]">
  Company rows matched or hydrated for the search.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of returned people.
</ResponseField>

<ResponseField name="limit_applied" type="integer">
  Applied page size.
</ResponseField>

<ResponseField name="offset" type="integer">
  Applied offset.
</ResponseField>

<Info>
  Unless you set `include_contact_details: true` and `confirm_credit_charge: true`, raw outreach fields stay hidden and the API returns masked values such as `contact_email_masked` plus an `unlock` cost summary.
</Info>

## Related endpoints

<CardGroup>
  <Card title="Company Search" icon="building-magnifying-glass" href="/v1/reference/company-search">
    Build the account set that People Search can target with `company_filters`.
  </Card>

  <Card title="Company Lookalike" icon="sparkles" href="/v1/reference/company-lookalike">
    Find similar accounts from a seed company.
  </Card>

  <Card title="Email Finder" icon="envelope" href="/v1/reference/email-finder">
    Find a work email for one known person.
  </Card>

  <Card title="Mobile Finder" icon="phone" href="/v1/reference/mobile-finder">
    Find a direct mobile number for one known person.
  </Card>
</CardGroup>


# Personal Email Finder
Source: https://leadmagic.io/docs/v1/reference/personal-email-finder

post /v1/people/personal-email-finder
Provide a B2B Profile URL and get back the personal emails of the person.

# Find Personal Email

Find personal email addresses for professionals using their profile URL. Ideal for reaching people outside of work contexts.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                         |
    | -------------- | ----------------------------- |
    | **Cost**       | **2 credits** per email found |
    | **No Results** | **FREE** if no email found    |

    <Tip>
      Personal emails are harder to find than work emails, hence the higher cost when found.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/personal-email-finder' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"profile_url": "linkedin.com/in/alex-rivera"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/personal-email-finder', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ profile_url: 'linkedin.com/in/alex-rivera' })
  });
  const data = await response.json();
  if (data.personal_email) {
    console.log(`Found: ${data.personal_email}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/personal-email-finder',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'profile_url': 'linkedin.com/in/alex-rivera'}
  )
  data = response.json()
  print(f"Personal Email: {data.get('personal_email', 'Not found')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Professional profile URL or username.
</ParamField>

***

## Response

<ResponseField name="profile_url" type="string">
  The profile URL used for lookup
</ResponseField>

<ResponseField name="personal_email" type="string">
  Personal email address found (null if not found)
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (2 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "profile_url": "linkedin.com/in/alex-rivera",
  "personal_email": "alex.rivera@example.net",
  "credits_consumed": 2,
  "message": "Personal email found."
}
```

***

## Success Messages

| Message                                     | Meaning                      | Cost      |
| ------------------------------------------- | ---------------------------- | --------- |
| `Personal email found.`                     | Email successfully retrieved | 2 credits |
| `No personal email found for this contact.` | No personal email available  | FREE      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use for recruiting outreach" icon="user-plus">
    Personal emails are better for recruiting since candidates may not check work email.
  </Accordion>

  <Accordion title="Respect privacy preferences" icon="shield">
    Personal emails should be used thoughtfully. Ensure compliance with privacy regulations.
  </Accordion>

  <Accordion title="Combine with work email" icon="envelope">
    Use both work and personal email channels for important outreach campaigns.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Recruiting" icon="user-plus">
    Reach candidates on personal email where they're more likely to respond.
  </Card>

  <Card title="Former Employees" icon="building">
    Contact people who've left a company and no longer have work email.
  </Card>

  <Card title="Multi-Channel Outreach" icon="share-nodes">
    Build complete contact profiles with both work and personal channels.
  </Card>

  <Card title="Event Follow-up" icon="calendar">
    Follow up with conference contacts using personal email.
  </Card>
</CardGroup>


# B2B Person Profile
Source: https://leadmagic.io/docs/v1/reference/profile-search

post /v1/people/profile-search
Retrieve comprehensive B2B person profile information including work history, education, certifications, and more.

# B2B Person Profile

Retrieve comprehensive B2B person profile data including work experience, education, certifications, and professional metrics.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                         |
    | -------------- | ----------------------------- |
    | **Cost**       | **1 credit** per profile      |
    | **No Results** | **FREE** if profile not found |

    <Tip>
      B2B person profile data includes work history, education, certifications, and company enrichment - all for 1 credit.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 100                 |
    | **Burst Capacity**  | \~2 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/profile-search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"profile_url": "linkedin.com/in/alex-rivera"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/profile-search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      profile_url: 'linkedin.com/in/alex-rivera'
    })
  });
  const profile = await response.json();
  console.log(`${profile.full_name} - ${profile.professional_title}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/profile-search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'profile_url': 'linkedin.com/in/alex-rivera'
      }
  )
  profile = response.json()
  print(f"{profile['full_name']} - {profile['professional_title']}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  B2B person profile URL or slug. Accepts full profile URLs or just the profile slug.
</ParamField>

***

## Response

<ResponseField name="profile_url" type="string">
  B2B person profile URL or slug
</ResponseField>

<ResponseField name="first_name" type="string">
  First name
</ResponseField>

<ResponseField name="last_name" type="string">
  Last name
</ResponseField>

<ResponseField name="full_name" type="string">
  Full name
</ResponseField>

<ResponseField name="professional_title" type="string">
  Current job title/headline
</ResponseField>

<ResponseField name="bio" type="string">
  Profile summary
</ResponseField>

<ResponseField name="location" type="string">
  Geographic location
</ResponseField>

<ResponseField name="country" type="string">
  Country
</ResponseField>

<ResponseField name="followers_range" type="string">
  Social follower range (e.g., "45K-50K")
</ResponseField>

<Expandable title="Current Employment">
  <ResponseField name="company_name" type="string">
    Current company name
  </ResponseField>

  <ResponseField name="company_industry" type="string">
    Current company industry
  </ResponseField>

  <ResponseField name="company_website" type="string">
    Current company website
  </ResponseField>
</Expandable>

<Expandable title="Tenure Statistics">
  <ResponseField name="total_tenure_years" type="string">
    Total career tenure in years
  </ResponseField>

  <ResponseField name="total_tenure_months" type="string">
    Total career tenure in months
  </ResponseField>
</Expandable>

<Expandable title="Work Experience">
  <ResponseField name="work_experience" type="array">
    Array of work history entries with position\_title, company\_name, employment\_period, company\_website, company\_logo\_url
  </ResponseField>
</Expandable>

<Expandable title="Education & Certifications">
  <ResponseField name="education" type="array">
    Array of education entries with institution\_name, degree, attendance\_period
  </ResponseField>

  <ResponseField name="certifications" type="array">
    Array of certifications with certification\_name, issuing\_organization, issue\_date
  </ResponseField>
</Expandable>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "profile_url": "linkedin.com/in/alex-rivera",
  "first_name": "Alex",
  "last_name": "Rivera",
  "full_name": "Alex Rivera",
  "professional_title": "VP of Sales at LeadMagic",
  "company_name": "LeadMagic",
  "company_industry": "Technology",
  "location": "San Francisco, CA",
  "country": "United States",
  "followers_range": "10K-15K",
  "total_tenure_years": "12",
  "bio": "Sales leader with 12+ years experience...",
  "work_experience": [
    {
      "position_title": "VP of Sales",
      "company_name": "LeadMagic",
      "employment_period": "Jan 2022 - Present"
    }
  ],
  "education": [
    {
      "institution_name": "Stanford University",
      "degree": "MBA",
      "attendance_period": "2010 - 2012"
    }
  ],
  "credits_consumed": 1,
  "message": "Profile found."
}
```

***

## Success Messages

| Message                                | Meaning                               | Cost     |
| -------------------------------------- | ------------------------------------- | -------- |
| `Profile found.`                       | Full B2B person profile data returned | 1 credit |
| `Profile not found or not accessible.` | Profile doesn't exist or is private   | FREE     |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Handle private profiles" icon="lock">
    Some profiles are private and will return limited data. Check for null fields and handle gracefully.
  </Accordion>

  <Accordion title="Chain with other endpoints" icon="link">
    Use B2B Person Profile to verify a person, then Email Finder or Mobile Finder for contact info.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Research" icon="handshake">
    Research prospects before outreach. Identify decision-makers and personalize your pitch.
  </Card>

  <Card title="Recruiting" icon="users">
    Enrich candidate profiles. Verify work history and identify qualified candidates.
  </Card>

  <Card title="Marketing Personas" icon="bullhorn">
    Build detailed buyer personas. Segment audiences by role and seniority.
  </Card>
</CardGroup>


# B2B Person Profile to Email
Source: https://leadmagic.io/docs/v1/reference/profile-to-email

post /v1/people/b2b-profile-email
Provide a B2B person profile and get back the work email of the person.

# B2B Person Profile to Email

Convert a B2B person profile into a verified work email address. The reverse of Email to B2B Person Profile.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                         |
    | -------------- | ----------------------------- |
    | **Cost**       | **5 credits** per email found |
    | **No Results** | **FREE** if no email found    |

    <Tip>
      Every email found is automatically validated for deliverability.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/b2b-profile-email' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"profile_url": "linkedin.com/in/alex-rivera"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/b2b-profile-email', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ profile_url: 'linkedin.com/in/alex-rivera' })
  });
  const data = await response.json();
  if (data.email) {
    console.log(`Email: ${data.email}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/b2b-profile-email',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'profile_url': 'linkedin.com/in/alex-rivera'}
  )
  data = response.json()
  print(f"Email: {data.get('email', 'Not found')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  B2B person profile URL or slug.
</ParamField>

***

## Response

<ResponseField name="email" type="string">
  Work email address found (null if not found)
</ResponseField>

<ResponseField name="profile_url" type="string">
  The B2B person profile used for lookup
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (5 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "email": "alex.rivera@example.com",
  "profile_url": "linkedin.com/in/alex-rivera",
  "credits_consumed": 5,
  "message": "Email found."
}
```

***

## Success Messages

| Message                            | Meaning                           | Cost      |
| ---------------------------------- | --------------------------------- | --------- |
| `Email found.`                     | Work email successfully retrieved | 5 credits |
| `No email found for this profile.` | No work email available           | FREE      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Clean profile URLs" icon="broom">
    Remove tracking parameters from profile URLs for best results. Just the base URL works.
  </Accordion>

  <Accordion title="Just the username works" icon="at">
    You can pass just `alex-rivera` and we'll resolve it to the full profile.
  </Accordion>

  <Accordion title="Compare with Email Finder" icon="scale-balanced">
    If you have the person's name and company, Email Finder (1 credit) may be more cost-effective than this endpoint (5 credits).
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Profile Prospecting" icon="user-magnifying-glass">
    Found someone's B2B person profile? Get their work email instantly.
  </Card>

  <Card title="B2B Profile Export" icon="download">
    Convert exported B2B profile lists into actionable email lists.
  </Card>

  <Card title="Event Follow-up" icon="calendar-check">
    Got connections at an event? Get their emails.
  </Card>

  <Card title="Inbound Lead Enrichment" icon="arrow-right-to-bracket">
    Visitor shared their profile? Get their work contact.
  </Card>
</CardGroup>


# Role Finder
Source: https://leadmagic.io/docs/v1/reference/role-finder

post /v1/people/role-finder
Provide the company name or domain and the required job title, and retrieve the corresponding person.

# Find by Role

Find a person at a company by their job title. Perfect for ABM campaigns targeting specific roles like "VP of Sales" or "Head of Marketing".

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                          |
    | -------------- | ------------------------------ |
    | **Cost**       | **2 credits** per person found |
    | **No Results** | **FREE** if no match found     |

    <Tip>
      Returns the first matching person. For multiple results, use People Search with title and company filters.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/role-finder' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "job_title": "VP of Sales",
      "company_domain": "leadmagic.io"
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/people/role-finder', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      job_title: 'VP of Sales',
      company_domain: 'leadmagic.io'
    })
  });
  const data = await response.json();
  if (data.profile_url) {
    console.log(`Found: ${data.first_name} ${data.last_name}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/role-finder',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'job_title': 'VP of Sales',
          'company_domain': 'leadmagic.io'
      }
  )
  data = response.json()
  print(f"Found: {data.get('full_name', 'Not found')}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  The job title to search for. Matches partial titles (e.g., "Sales" matches "VP of Sales").
</ParamField>

<ParamField type="string">
  Company website domain (preferred). More accurate than company\_name.
</ParamField>

<ParamField type="string">
  Company name. Use if domain is not available.
</ParamField>

<Warning>
  You must provide either `company_domain` or `company_name` (or both).
</Warning>

***

## Response

<ResponseField name="first_name" type="string">
  First name of the person found
</ResponseField>

<ResponseField name="last_name" type="string">
  Last name of the person found
</ResponseField>

<ResponseField name="full_name" type="string">
  Full name of the person found
</ResponseField>

<ResponseField name="profile_url" type="string">
  Professional profile URL
</ResponseField>

<ResponseField name="company_name" type="string">
  Company name
</ResponseField>

<ResponseField name="company_website" type="string">
  Company website domain
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (2 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "first_name": "Alex",
  "last_name": "Rivera",
  "full_name": "Alex Rivera",
  "profile_url": "linkedin.com/in/alex-rivera",
  "job_title": "VP of Sales",
  "company_name": "Example Robotics",
  "company_website": "leadmagic.io",
  "credits_consumed": 2,
  "message": "Role found."
}
```

***

## Success Messages

| Message                                   | Meaning                         | Cost      |
| ----------------------------------------- | ------------------------------- | --------- |
| `Role Found`                              | Person with matching role found | 2 credits |
| `No matching role found at this company.` | No matching role exists         | FREE      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use domain over company name" icon="globe">
    Domain lookups are more accurate. `leadmagic.io` resolves directly to LeadMagic, while a company name can match multiple entities.
  </Accordion>

  <Accordion title="Be flexible with titles" icon="edit">
    Try variations: "VP Sales", "VP of Sales", "Head of Sales" may all work depending on how the person lists their title.
  </Accordion>

  <Accordion title="Chain with Email Finder" icon="link">
    After finding a person, use Email Finder with their name and company to get their email.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="ABM Campaigns" icon="bullseye">
    Target specific roles at key accounts for personalized outreach.
  </Card>

  <Card title="Competitive Intelligence" icon="chart-line">
    Find your counterpart at competitor companies.
  </Card>

  <Card title="Partner Outreach" icon="handshake">
    Find the right person to discuss partnerships.
  </Card>

  <Card title="Recruiting" icon="user-tie">
    Identify potential candidates by role at target companies.
  </Card>
</CardGroup>


# Search Stats
Source: https://leadmagic.io/docs/v1/reference/search-stats

post /v3/search/stats
Free helper endpoint for Jobs, Company, and People Search coverage and top dimensions.

# Search Stats

`POST /v3/search/stats` is a free helper endpoint that summarizes what is available across Jobs, Company, and People Search. Use it to power filter builders, capability cards, onboarding screens, or "what can I target?" UI.

The endpoint returns cached, high-level metrics only. It does not return records, contacts, or jobs.

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/search/stats' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "products": ["jobs", "company", "people"],
      "sections": ["coverage", "top"],
      "limit": 3
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/search/stats', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      products: ['jobs', 'company', 'people'],
      sections: ['coverage', 'top'],
      limit: 3
    })
  });

  const data = await response.json();
  console.log(data.company?.coverage, data.jobs?.top);
  ```
</CodeGroup>

## Request Body

<ParamField type="string[]">
  Product families to include. Allowed values: `jobs`, `company`, `people`.
</ParamField>

<ParamField type="string[]">
  Sections to include. Allowed values: `coverage`, `top`, `capabilities`.
</ParamField>

<ParamField type="integer">
  Number of top values to return for each dimension. Defaults to `3`; maximum is `25`.
</ParamField>

## Request Examples

Coverage only:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "products": ["jobs", "company", "people"],
  "sections": ["coverage"]
}
```

Top company and people dimensions:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "products": ["company", "people"],
  "sections": ["top"],
  "limit": 3
}
```

Jobs capabilities and filter counts:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "products": ["jobs"],
  "sections": ["coverage", "capabilities", "top"]
}
```

## Response

<ResponseField name="credits_consumed" type="number">
  Always `0`.
</ResponseField>

<ResponseField name="jobs.coverage" type="object">
  Jobs coverage metrics such as open jobs, total indexed jobs, companies, and title embeddings.
</ResponseField>

<ResponseField name="jobs.capabilities" type="object">
  Supported Jobs Search capabilities and filter families.
</ResponseField>

<ResponseField name="jobs.top" type="object">
  Top jobs dimensions such as common titles, specialties, role families, industries, company types, and countries.
</ResponseField>

<ResponseField name="company.coverage" type="object">
  Company coverage metrics such as estimated companies, company records with technology data, and contact coverage rollups.
</ResponseField>

<ResponseField name="company.top" type="object">
  Top company dimensions such as industries, countries, regions, size ranges, revenue ranges, funding types, SIC/NAICS, and each technology category.
</ResponseField>

<ResponseField name="people.coverage" type="object">
  People/contact coverage metrics, including estimated contacts and email/phone availability rollups.
</ResponseField>

<ResponseField name="people.top" type="object">
  Top people/contact coverage dimensions by company.
</ResponseField>

<ResponseField name="cache" type="object">
  Cache status for each backend stats source.
</ResponseField>

## Related endpoints

<CardGroup>
  <Card title="Job Search" icon="briefcase" href="/v1/reference/job-search">
    Search jobs using the capabilities shown here.
  </Card>

  <Card title="Company Search" icon="building-magnifying-glass" href="/v1/reference/company-search">
    Search companies using the company dimensions shown here.
  </Card>

  <Card title="People Search" icon="users" href="/v1/reference/people-search">
    Search contacts using the people coverage shown here.
  </Card>

  <Card title="Job Search Helpers" icon="wand-magic-sparkles" href="/v1/reference/job-search-helpers">
    Resolve concrete filter values for Jobs Search.
  </Card>
</CardGroup>


# Company Technographics
Source: https://leadmagic.io/docs/v1/reference/technographics

post /v1/companies/technographics
Get detailed technology stack information for any company by providing their domain.

# Tech Stack

Discover the technology stack and tools used by a company. Essential for technology-focused sales and competitive analysis.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                          |
    | -------------- | ------------------------------ |
    | **Cost**       | **1 credit** per company       |
    | **No Results** | **FREE** if no tech data found |

    <Tip>
      Identifies marketing tools, analytics, hosting, CRM, and more from website analysis.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    ### Per-Endpoint Limit

    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/companies/technographics' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"company_domain": "leadmagic.io"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v1/companies/technographics', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_domain: 'leadmagic.io' })
  });
  const data = await response.json();
  console.log(`Found ${data.technologies?.length || 0} technologies`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/companies/technographics',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={'company_domain': 'leadmagic.io'}
  )
  data = response.json()
  print(f"Technologies: {data.get('technologies', [])}")
  ```
</CodeGroup>

***

## Request Parameters

<ParamField type="string">
  Company website domain to analyze.
</ParamField>

***

## Response

<ResponseField name="company_domain" type="string">
  The domain analyzed
</ResponseField>

<ResponseField name="technologies" type="array">
  Array of detected technologies
</ResponseField>

<ResponseField name="categories" type="object">
  Technologies grouped by category
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Credits used (1 if found, 0 if not)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

### Technology Object

| Field      | Type   | Description                              |
| ---------- | ------ | ---------------------------------------- |
| `name`     | string | Technology name                          |
| `category` | string | Category (Analytics, CRM, Hosting, etc.) |
| `website`  | string | Technology vendor website                |
| `icon`     | string | Technology logo URL                      |

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "company_domain": "leadmagic.io",
  "technologies": [
    {
      "name": "Google Analytics",
      "category": "Analytics",
      "website": "google.com/analytics"
    },
    {
      "name": "Cloudflare",
      "category": "CDN",
      "website": "cloudflare.com"
    },
    {
      "name": "React",
      "category": "JavaScript Framework",
      "website": "react.dev"
    }
  ],
  "categories": {
    "Analytics": ["Google Analytics", "Segment"],
    "CDN": ["Cloudflare"],
    "JavaScript Framework": ["React"]
  },
  "credits_consumed": 1,
  "message": "Technologies found."
}
```

***

## Success Messages

| Message                                  | Meaning                  | Cost     |
| ---------------------------------------- | ------------------------ | -------- |
| `Technologies found.`                    | Tech stack data returned | 1 credit |
| `No technologies found for this domain.` | No tech data available   | FREE     |

***

## Common Categories

| Category                 | Examples                                 |
| ------------------------ | ---------------------------------------- |
| **Analytics**            | Google Analytics, Mixpanel, Amplitude    |
| **CRM**                  | Example CRM, Example Robotics, Pipedrive |
| **Marketing Automation** | Marketo, Pardot, Mailchimp               |
| **CDN**                  | Cloudflare, Fastly, Akamai               |
| **Hosting**              | AWS, Google Cloud, Azure                 |
| **E-commerce**           | Shopify, Magento, WooCommerce            |
| **Chat/Support**         | Intercom, Drift, Zendesk                 |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Target complementary tech" icon="puzzle-piece">
    If they use Example CRM CRM, they might need your Example CRM integration.
  </Accordion>

  <Accordion title="Identify displacement opportunities" icon="right-left">
    Find companies using competitor products for targeted messaging.
  </Accordion>

  <Accordion title="Validate tech fit" icon="check">
    Ensure prospects have compatible tech before outreach.
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup>
  <Card title="Sales Targeting" icon="bullseye">
    Find companies using complementary or competitive technologies.
  </Card>

  <Card title="Integration Sales" icon="plug">
    Target companies with tech your product integrates with.
  </Card>

  <Card title="Market Research" icon="chart-pie">
    Analyze technology adoption trends in your market.
  </Card>

  <Card title="Lead Qualification" icon="filter">
    Score leads based on tech stack compatibility.
  </Card>
</CardGroup>


# Support & Policies
Source: https://leadmagic.io/docs/v1/support

Get help, understand our policies, and contact the LeadMagic team

At LeadMagic, we're committed to helping you succeed with our API. Whether you have a question, encounter an issue, or need guidance, our support team is here to help.

## Contact Options

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:support@leadmagic.io">
    **[support@leadmagic.io](mailto:support@leadmagic.io)**

    Available 9 AM - 5 PM EST. Response within 24 hours.
  </Card>

  <Card title="Live Chat" icon="comments">
    **In-App Chat**

    Click the chat icon in the bottom right of your dashboard for immediate assistance.
  </Card>

  <Card title="Help Center" icon="circle-question" href="https://help.leadmagic.io/en">
    **Self-Service Help**

    Browse articles, tutorials, and FAQs.
  </Card>

  <Card title="Sales Inquiries" icon="handshake" href="mailto:support@leadmagic.io">
    **Enterprise & Custom Plans**

    Contact our team for custom solutions.
  </Card>
</CardGroup>

## Help Center Resources

<AccordionGroup>
  <Accordion title="Getting Started" icon="rocket">
    * [Welcome to LeadMagic](https://help.leadmagic.io/en) - Platform overview
    * [Creating Your Account](https://help.leadmagic.io/en) - Account setup guide
    * [The LeadMagic Credit System](/docs/v1/credits) - Understanding credits
    * [Subscription Plans](/docs/v1/credits#subscription-plans) - Plan comparison
  </Accordion>

  <Accordion title="List Data Enrichment" icon="list">
    * [Uploading a List for Enrichment](https://help.leadmagic.io/en) - Bulk processing
    * [Email Validation](/docs/v1/reference/email-validation) - Verify email addresses
    * [Email Finder](/docs/v1/reference/email-finder) - Find work emails
    * [Mobile Finder](/docs/v1/reference/mobile-finder) - Find mobile numbers
    * [Profile Search](/docs/v1/reference/profile-search) - Enrich LinkedIn profiles
    * [Company Search](/docs/v1/reference/company-search) - Company data enrichment
  </Accordion>

  <Accordion title="API Usage" icon="code">
    * [Authentication](/docs/v1/authentication) - API key setup
    * [Making API Calls](/docs/v1/making-api-calls) - Request & response formats
    * [Check Credits](/docs/v1/reference/check-credits) - Monitor your balance
    * [Integrations](/docs/v1/integrations) - Third-party platform guides
  </Accordion>

  <Accordion title="Account Management" icon="user-gear">
    * [Team Management](/docs/v1/credits#team-credit-management) - Share credits with team
    * [Billing & Invoices](/docs/v1/credits#billing--payments) - Payment management
    * [API Keys](https://app.leadmagic.io/settings/api) - Key management
  </Accordion>
</AccordionGroup>

## Before Contacting Support

<Info>
  Check these resources first - your answer might already be available!
</Info>

<AccordionGroup>
  <Accordion title="Search the Documentation" icon="book">
    Use the search bar at the top of this page to find answers to common questions.
  </Accordion>

  <Accordion title="Check Your API Response" icon="code">
    Error messages often contain helpful information about what went wrong.
    Check the `errors` array and `meta.request_id` in your API response.
  </Accordion>

  <Accordion title="Verify Your API Key" icon="key">
    Ensure your API key is correct and hasn't expired. You can regenerate it in
    your [account settings](https://app.leadmagic.io/settings/api).
  </Accordion>

  <Accordion title="Check Your Credit Balance" icon="wallet">
    Use the [Check Credits endpoint](/docs/v1/reference/check-credits) to verify you
    have sufficient credits.
  </Accordion>
</AccordionGroup>

## How to Report an Issue

When contacting support, please include:

<Steps>
  <Step title="Describe the issue">
    Explain what you're trying to do and what's not working as expected.
  </Step>

  <Step title="Include your API key prefix">
    Share the **first 8 characters** of your API key for identification.

    <Warning>
      Never share your full API key. Only the first 8 characters.
    </Warning>
  </Step>

  <Step title="Provide the request details">
    Include the endpoint URL, request body (with sensitive data redacted), and
    any error messages.
  </Step>

  <Step title="Share the response">
    Include the full API response, including status code and error details.
  </Step>
</Steps>

### Example Support Request

<Accordion title="Good support request example">
  ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
  **Issue:** Email validation returning "unknown" for valid emails

  **API Key Prefix:** abc12345...

  **Endpoint:** POST /v1/people/email-validation

  **Request Body:**
  {
    "email": "alex.rivera@example.com"
  }

  **Response:**
  {
    "status": "unknown",
    "email": "alex.rivera@example.com"
  }

  **Expected:** Status should be "valid" as the email exists.

  **Environment:** Node.js 20, using fetch API
  ```
</Accordion>

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    **Cause:** Invalid or missing API key.

    **Solution:**

    * Verify your API key in the dashboard
    * Check the header name is exactly `X-API-Key`
    * Ensure there are no extra spaces in the key
  </Accordion>

  <Accordion title="402 Payment Required" icon="credit-card">
    **Cause:** Insufficient credits in your account.

    **Solution:**

    * Check your balance in the dashboard
    * Purchase additional credits
    * Use the [Check Credits endpoint](/docs/v1/reference/check-credits)
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="gauge-high">
    **Cause:** Rate limit exceeded.

    **Solution:**

    * Reduce your request frequency
    * Implement exponential backoff
    * Contact us for higher limits
  </Accordion>

  <Accordion title="Unknown email results" icon="envelope-open-text">
    **Cause:** The mail server didn't respond or the domain is unverifiable.

    **Solution:**

    * `unknown` results are free — you are not charged
    * Retry validation later, or use Email Finder to verify the address
    * See [Email Validation docs](/docs/v1/reference/email-validation) for details
  </Accordion>
</AccordionGroup>

## Policies

* **Cancellation:** Cancel anytime under Settings > Billing. Access continues until end of billing cycle.
* **Refunds:** LeadMagic does not provide refunds. Contact [support@leadmagic.io](mailto:support@leadmagic.io) with billing concerns.
* **Data:** We don't store enriched data. All API traffic is encrypted via TLS 1.3.

<Tip>
  See our [Privacy Policy](https://leadmagic.io/legal/privacy) and [Terms of Service](https://leadmagic.io/legal/terms) for full details.
</Tip>

## Enterprise Support

<Note>
  Enterprise customers receive priority support with dedicated account management.
</Note>

<CardGroup>
  <Card title="Priority Response" icon="bolt">
    Get responses within 2 hours during business hours.
  </Card>

  <Card title="Dedicated Slack Channel" icon="slack">
    Direct communication with our engineering team.
  </Card>

  <Card title="Custom Rate Limits" icon="gauge">
    Higher rate limits tailored to your needs.
  </Card>

  <Card title="Onboarding Support" icon="handshake">
    Personalized setup and integration assistance.
  </Card>
</CardGroup>

<Tip>
  Interested in enterprise support? [Contact us](mailto:support@leadmagic.io) to learn more.
</Tip>

## Feedback

We continuously improve our API and documentation based on your feedback.

<CardGroup>
  <Card title="Feature Requests" icon="lightbulb" href="mailto:feedback@leadmagic.io">
    Have an idea for a new feature? We'd love to hear it.
  </Card>

  <Card title="Report a Bug" icon="bug" href="mailto:support@leadmagic.io">
    Found an issue? Let us know and we'll fix it ASAP.
  </Card>
</CardGroup>


# Use Cases
Source: https://leadmagic.io/docs/v1/use-cases

Common workflows you can build with LeadMagic across email, people, company, jobs, ads, MCP, and bulk enrichment.

# Use Cases

LeadMagic gives you one API key for the core B2B data workflows sales, marketing, RevOps, and product teams build every day.

## High-impact Workflows

<CardGroup>
  <Card title="Clean and Verify Lists" icon="broom" href="/v1/reference/email-validation">
    Validate emails before campaign launch, remove invalid addresses, and protect sender reputation.
  </Card>

  <Card title="Find Missing Work Emails" icon="envelope" href="/v1/reference/email-finder">
    Turn a name plus company into a verified professional email when available.
  </Card>

  <Card title="Turn Emails into Profiles" icon="id-card" href="/v1/reference/email-to-profile">
    Enrich inbound leads, signups, and CRM records with professional profile data.
  </Card>

  <Card title="Find Emails from Profiles" icon="at" href="/v1/reference/profile-to-email">
    Convert LinkedIn or professional profile URLs into reachable work emails.
  </Card>

  <Card title="Build Target Account Contact Lists" icon="users" href="/v1/reference/role-finder">
    Find the right decision-makers at target companies by role, title, and company.
  </Card>

  <Card title="Find People by Persona" icon="user-magnifying-glass" href="/v1/reference/people-search">
    Search people at a company by titles, roles, ICP terms, or lookalike title intent.
  </Card>

  <Card title="Search Companies" icon="building" href="/v1/reference/company-search">
    Enrich companies by domain, name, or profile URL with firmographic and funding context.
  </Card>

  <Card title="Research Hiring Signals" icon="briefcase" href="/v1/reference/job-search">
    Search jobs by occupation taxonomy, titles, companies, tags, salary, location, and recency.
  </Card>

  <Card title="Track Job Changes" icon="arrow-right-arrow-left" href="/v1/reference/job-change-detector">
    Detect when contacts move companies so your CRM and outreach stay current.
  </Card>

  <Card title="Analyze Competitor Ads" icon="rectangle-ad" href="/v1/reference/b2b-ads-search">
    Research Google, Meta, and B2B ads to understand competitor messaging and offers.
  </Card>
</CardGroup>

## Common Playbooks

<AccordionGroup>
  <Accordion title="Outbound prospecting" icon="bullseye">
    Start with target accounts, use [Company Search](/docs/v1/reference/company-search) to normalize domains, find employees with [People Search](/docs/v1/reference/people-search), then use [Email Finder](/docs/v1/reference/email-finder) or [Mobile Finder](/docs/v1/reference/mobile-finder) for contact details.
  </Accordion>

  <Accordion title="Inbound enrichment" icon="inbox">
    When a lead signs up, validate the submitted email with [Email Validation](/docs/v1/reference/email-validation), enrich the person with [Email to Profile](/docs/v1/reference/email-to-profile), and enrich their company with [Company Search](/docs/v1/reference/company-search).
  </Accordion>

  <Accordion title="Hiring intent campaigns" icon="briefcase">
    Use [Job Search](/docs/v1/reference/job-search) to find companies hiring for occupations connected to your product, then use People or Contact endpoints to find the right buyer at those accounts.
  </Accordion>

  <Accordion title="CRM cleanup and backfill" icon="database">
    Validate stale emails, refresh profile and company fields, fill missing domains, and identify job changes before routing records to sales or marketing automation.
  </Accordion>

  <Accordion title="Market and competitor research" icon="chart-line">
    Combine [Company Search](/docs/v1/reference/company-search), [Company Lookalike](/docs/v1/reference/company-lookalike), [Technographics](/docs/v1/reference/technographics), and ads endpoints to understand a market before building lists or campaigns.
  </Accordion>

  <Accordion title="AI assistant workflows" icon="wand-magic-sparkles">
    Connect the [LeadMagic MCP Server](/docs/mcp/introduction) to compatible AI tools so agents can validate emails, enrich records, estimate costs, check credits, and run structured research workflows.
  </Accordion>
</AccordionGroup>

## Choose the Right Starting Point

<CardGroup>
  <Card title="I have an email" icon="envelope-circle-check" href="/v1/reference/email-validation">
    Validate it first, then enrich the profile if needed.
  </Card>

  <Card title="I have a profile URL" icon="id-card" href="/v1/reference/profile-to-email">
    Use profile-based enrichment to find contact data.
  </Card>

  <Card title="I have a company" icon="building" href="/v1/reference/company-search">
    Enrich the account, then find people or jobs connected to it.
  </Card>

  <Card title="I have a target role" icon="user-tie" href="/v1/reference/role-finder">
    Find matching contacts at companies you care about.
  </Card>

  <Card title="I have a hiring signal" icon="briefcase" href="/v1/reference/job-search">
    Use job filters to discover companies with active demand.
  </Card>

  <Card title="I have a large file" icon="file-csv" href="/v1/integrations">
    Use integrations, bulk workflows, or MCP tools to process rows safely.
  </Card>
</CardGroup>

<Tip>
  Most endpoints only consume credits when data is found. See [Credits & Pricing](/docs/v1/credits) before scaling a workflow.
</Tip>