llms-full.txt

# LeadMagic API - Current Reference Snapshot

> This file is a concise, current LLM-oriented reference aligned to `https://leadmagic.io/docs` during the latest cleanup pass. The public docs remain authoritative.

## Basics

Base URL: `https://api.leadmagic.io`

Auth header: `X-API-Key`

Primary docs:
- `https://leadmagic.io/docs`
- `https://leadmagic.io/docs/llms.txt`

Important: current public docs are not uniform about field naming. Some endpoints still show snake_case while others show mixed or camelCase examples. Check the endpoint-specific docs before hard-coding field assumptions.

## Current MCP Surface

The hosted LeadMagic MCP exposes:

- 10 tools (see README for the full mapping to REST endpoints)
- 1 shared docs resource: `leadmagic://docs`
- 2 built-in prompts (for example `account_research`, `contact_lookup`)

The MCP surface currently covers credits, people enrichment, company research, technographics, competitors, job-change detection, and role lookup.

Important distinction: ads endpoints and some jobs endpoints exist in the broader REST API and this OpenAPI snapshot, but they are not part of the current MCP tool surface.

## Hosted MCP Sign-In

The hosted MCP is the canonical way for AI clients (Cursor, Claude, ChatGPT, VS Code/Copilot, Windsurf, Zed, and many others) to call LeadMagic tools without per-developer REST wiring.

### Entrypoint

- MCP URL: `https://mcp.leadmagic.io/mcp` (streamable HTTP)
- Per-client install snippets (canonical source): `https://mcp.leadmagic.io/clients`

### Authentication

| Mode | Detail |
| --- | --- |
| OAuth 2.1 + Dynamic Client Registration (recommended) | Client auto-registers at `https://mcp.leadmagic.io/oauth/register` and runs Authorization Code + PKCE. |
| OAuth with the static public client | `client_id=4b9eLjoGVCJ1Dvnc`, secret blank (PKCE S256). Clerk consent screen reads "LeadMagic MCP & CLI (static)". The client ID is public by design. |
| API-key header | `x-leadmagic-key: <YOUR_API_KEY>` on every MCP request. |
| Bearer token | `Authorization: Bearer <YOUR_LEADMAGIC_TOKEN>`. |

### OAuth metadata

- Authorization server: `https://mcp.leadmagic.io/.well-known/oauth-authorization-server`
- Protected resource: `https://mcp.leadmagic.io/.well-known/oauth-protected-resource/mcp`
- Registration endpoint: `https://mcp.leadmagic.io/oauth/register`
- Issuer: `https://clerk.leadmagic.io`
- JWKS: `https://clerk.leadmagic.io/.well-known/jwks.json`
- Scopes: `openid profile email offline_access`
- Grant types: `authorization_code`, `refresh_token`
- Code challenge methods: `S256`
- Response types: `code`
- ID token signing: `RS256`

### Client coverage

All clients below speak the same streamable-HTTP transport. The discovery document at `https://mcp.leadmagic.io/clients` returns up-to-date install snippets per client and is the source of truth if any CLI or config shape changes.

- Cursor (prefer the official plugin: `https://github.com/LeadMagic/leadmagic-cursor-plugin`; manual URL-only `.cursor/mcp.json` also supported on v0.48+)
- Claude Desktop, Claude Code CLI, claude.ai, Cowork (Anthropic)
- ChatGPT Developer Mode, OpenAI Responses API
- VS Code / GitHub Copilot in VS Code
- Windsurf (Codeium)
- Zed, Cline, Roo Code, OpenCode, Continue, Amp (Sourcegraph), Augment Code
- Gemini CLI (Google)
- JetBrains IDEs (2025.1+)
- Amazon Q Developer (AWS)
- GitHub Copilot Coding Agent
- Vercel AI SDK via `@ai-sdk/mcp` `createMCPClient` or `openai.tools.mcp`

### Security reminders

- Never commit real API keys or bearer tokens. Reference them via `${LEADMAGIC_API_KEY}` or a secret manager.
- The static OAuth client ID (`4b9eLjoGVCJ1Dvnc`) is intentionally public (PKCE, no secret). It is not a credential.
- Only install LeadMagic-branded MCP servers, skills, or plugins from the official locations listed in `SECURITY.md`. See the impersonation guidance there before running any "LeadMagic" install snippet you find elsewhere.

## Error Shape

Public docs describe RFC 9457-style error responses:

```json
{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}
```

Common status codes: `200`, `400`, `401`, `402`, `404`, `429`, `500`

## Credit System

These values reflect the current public docs for the core endpoints covered in this repo.

| Route | Cost | Notes |
| --- | --- | --- |
| `GET /v1/credits` | 0 | Free |
| `POST /v1/people/email-validation` | 0.25 | 4 validations per credit |
| `POST /v1/people/email-finder` | 1 | Free if result is null |
| `POST /v1/people/personal-email-finder` | 2 | Free if not found |
| `POST /v1/people/b2b-profile-email` | 5 | Free if not found |
| `POST /v1/people/b2b-profile` | 10 | Free if not found |
| `POST /v1/people/mobile-finder` | 5 | Free if not found |
| `POST /v1/people/profile-search` | 1 | Docs show 100 req/min |
| `POST /v1/people/role-finder` | 2 | Free if not found |
| `POST /v1/people/employee-finder` | 0.05 per employee | 20 employees per credit |
| `POST /v1/companies/company-search` | 1 | Free if not found |
| `POST /v1/companies/company-funding` | 4 | Free if not found |
| `POST /v1/jobs/jobs-finder` | 1 per job | Free if no jobs found |
| `GET /v1/jobs/countries` | 0 | Metadata |
| `GET /v1/jobs/job-types` | 0 | Metadata |
| `POST /v1/ads/google-ads-search` | 0.2 | 5 searches per credit |
| `POST /v1/ads/meta-ads-search` | 0.2 | 5 searches per credit |
| `POST /v1/ads/b2b-ads-search` | 0.2 | 5 searches per credit |
| `POST /v1/ads/b2b-ads-details` | 2 | Free if not found |

## Endpoint Summary

### Credits

#### `GET /v1/credits`
Returns the current credit balance.

Example:
```bash
curl 'https://api.leadmagic.io/v1/credits' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Typical response:
```json
{
  "credits": 15432.5,
  "is_frozen": false,
  "credits_frozen": 0,
  "credits_liquid": 15432.5,
  "credit_freeze_message": null,
  "credit_freeze_plan_hint": null
}
```

### People

#### `POST /v1/people/email-validation`
Validate an email and return deliverability plus free company enrichment.

Minimal request:
```json
{ "email": "john@company.com" }
```

Typical fields:
- `email`
- `email_status`
- `credits_consumed`
- `message`
- `mx_record`
- `mx_provider`
- `company_name`
- `company_location`

#### `POST /v1/people/email-finder`
Find a verified work email from person plus company input.

Minimal request:
```json
{
  "first_name": "John",
  "last_name": "Doe",
  "domain": "company.com"
}
```

Typical fields:
- `email`
- `status`
- `credits_consumed`
- `employment_verified`
- company enrichment fields

#### `POST /v1/people/personal-email-finder`
Find personal email data from a professional profile URL.

Minimal request:
```json
{ "profile_url": "https://profiles.example.com/johndoe" }
```

Typical fields in docs:
- `profile_url`
- `personal_email` or `personal_emails`
- `credits_consumed`
- `message`

#### `POST /v1/people/b2b-profile-email`
Convert a professional profile URL into a work email.

Minimal request:
```json
{ "profile_url": "https://profiles.example.com/johndoe" }
```

Typical fields:
- `email`
- `profile_url`
- `credits_consumed`
- `message`

#### `POST /v1/people/b2b-profile`
Convert an email into a professional profile URL.

Minimal request:
```json
{ "work_email": "john@company.com" }
```

Typical fields:
- `profile_url`
- `credits_consumed`
- `message`

#### `POST /v1/people/mobile-finder`
Find a mobile number from `profile_url`, `work_email`, or `personal_email`.

Typical fields:
- `profile_url`
- `email`
- `mobile_number`
- `credits_consumed`
- `message`

#### `POST /v1/people/profile-search`
Return professional profile enrichment data. Current docs show a lower rate limit than older repo docs.

Minimal request:
```json
{ "profile_url": "https://profiles.example.com/johndoe" }
```

Typical fields:
- `profile_url`
- `first_name`
- `last_name`
- `full_name`
- `professional_title`
- `company_name`
- `bio`
- `work_experience`
- `education`
- `credits_consumed`

#### `POST /v1/people/role-finder`
Find a person at a company by job title.

Minimal request:
```json
{
  "job_title": "VP of Sales",
  "company_domain": "company.com"
}
```

Typical fields:
- `first_name`
- `last_name`
- `full_name`
- `profile_url`
- `job_title`
- `company_name`
- `company_website`
- `credits_consumed`

#### `POST /v1/people/employee-finder`
Return multiple employees for a company.

Minimal request:
```json
{
  "company_domain": "company.com",
  "limit": 10
}
```

Typical fields:
- `employees` or `data`
- `total_count`
- `credits_consumed`
- `message`

### Companies

#### `POST /v1/companies/company-search`
Enrich a company by domain, name, or profile URL.

Minimal request:
```json
{ "company_domain": "company.com" }
```

Docs currently show example responses with mixed naming, including fields like:
- `companyName`
- `companyId`
- `industry`
- `employeeCount`
- `employeeRange`
- `founded`
- `headquarters`
- `credits_consumed`

#### `POST /v1/companies/company-funding`
Return funding rounds, investors, and leadership details.

Minimal request:
```json
{ "company_domain": "stripe.com" }
```

Typical fields:
- `company_name`
- `total_funding`
- `latest_round`
- `funding_rounds`
- `investors`
- `leadership`
- `credits_consumed`

### Jobs

#### `POST /v1/jobs/jobs-finder`
Search jobs using company, title, location, pagination, and posting-age filters.

Minimal request:
```json
{
  "job_title": "Sales Director",
  "country_id": "US",
  "posted_within": 14
}
```

Typical fields:
- `total_count`
- `page`
- `per_page`
- `results`
- `credits_consumed`

#### `GET /v1/jobs/countries`
Returns country codes for jobs filtering.

#### `GET /v1/jobs/job-types`
Returns job type IDs for jobs filtering.

### Ads

#### `POST /v1/ads/google-ads-search`
Search Google Ads by company domain or name.

Typical ad fields:
- `headline`
- `description`
- `display_url`
- `final_url`
- `ad_type`

#### `POST /v1/ads/meta-ads-search`
Search Meta ads by company domain or name.

Typical ad fields:
- `ad_id`
- `content`
- `image_url`
- `video_url`
- `platform`
- `started_running`

#### `POST /v1/ads/b2b-ads-search`
Search professional-network B2B ads.

Typical ad fields:
- `content`
- `link`
- `image_url`

#### `POST /v1/ads/b2b-ads-details`
Fetch full B2B ad details from an ad library URL or ID.

Minimal request:
```json
{
  "ad_url": "https://ads.example.com/library/detail/633872143"
}
```

Typical fields:
- `ad_id`
- `headline`
- `content`
- `advertiser`
- `creative`
- `targeting`
- `started_running`
- `impressions`
- `credits_consumed`

## Docs-Only Endpoints Outside This Snapshot
- Analytics API
- Job Change Detector
- Competitors Search
- Technographics
- Job company types
- Job industries
- Job regions
- Credits refresh and health endpoints

## Guidance For Tools
- Prefer the public docs when there is any mismatch with local files
- Use endpoint-specific docs for field names
- Assume pricing and rate limits can change; verify from docs before hard-coding business rules