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 current LeadMagic MCP docs describe:

- 16 tools
- 1 shared docs resource: `leadmagic://docs`
- 2 built-in prompts

That MCP surface currently covers credits, people enrichment, company research, technographics, competitors, job-change detection, and jobs search.

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

## 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