# LeadMagic API Documentation

LeadMagic provides a comprehensive B2B data enrichment API designed for sales, recruitment, and business intelligence applications. The API offers 19 endpoints across email finding and validation, profile enrichment, company intelligence, job data, mobile number discovery, and advertisement tracking. All endpoints are accessible via HTTPS at `https://api.leadmagic.io` and require authentication through the `X-API-Key` header.

The API uses a credit-based billing system where each operation consumes a specific number of credits. All request and response fields use snake_case naming convention, and most endpoints use POST method even for data retrieval operations. The specification is 100% OpenAPI 3.1 compliant, enabling seamless code generation in 40+ programming languages and integration with tools like Swagger UI, Postman, and Insomnia.

---

## Check Credits

Retrieves the current credit balance for the authenticated user. This is a free operation that consumes no credits and is useful for monitoring usage, implementing billing alerts, and displaying remaining credits in applications.

```bash
curl --request POST \
     --url https://api.leadmagic.io/credits \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json'

# Response:
# {
#   "credits": 7333.8
# }
```

---

## Email Validation

Validates email deliverability and retrieves associated company information. Returns status values: `valid`, `valid_catch_all`, `invalid`, `unknown`, or `catch_all`. Consumes 0.05 credits per validation.

```bash
curl --request POST \
     --url https://api.leadmagic.io/email-validate \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "email": "jesse@leadmagic.io",
       "first_name": "Jesse",
       "last_name": "Ouellette"
     }'

# Response:
# {
#   "email": "jesse@leadmagic.io",
#   "email_status": "valid",
#   "credits_consumed": 0.05,
#   "message": "Email is valid.",
#   "is_domain_catch_all": false,
#   "mx_record": "aspmx.l.google.com",
#   "mx_provider": "Google Workspace",
#   "mx_security_gateway": false,
#   "company_name": "Leadmagic",
#   "company_industry": "Internet",
#   "company_size": "11-50",
#   "company_founded": 2022,
#   "company_type": "private",
#   "company_linkedin_url": "linkedin.com/company/leadmagichq",
#   "company_linkedin_id": "75153174",
#   "company_location": {
#     "name": "boston, massachusetts, united states",
#     "locality": "boston",
#     "region": "massachusetts",
#     "country": "united states"
#   }
# }
```

---

## Email Finder

Finds verified email addresses based on a person's name and company domain. Requires `first_name` and `last_name`, with optional `domain` or `company_name`. Returns status: `valid`, `valid_catch_all`, or `not_found`. Consumes 1 credit.

```bash
curl --request POST \
     --url https://api.leadmagic.io/email-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "first_name": "Bill",
       "last_name": "Gates",
       "domain": "microsoft.com",
       "company_name": "Microsoft"
     }'

# Response:
# {
#   "email": "billg@microsoft.com",
#   "status": "valid",
#   "credits_consumed": 1,
#   "message": "Valid email found.",
#   "first_name": "Bill",
#   "last_name": "Gates",
#   "domain": "microsoft.com",
#   "is_domain_catch_all": false,
#   "mx_record": "microsoft-com.mail.protection.outlook.com",
#   "mx_provider": "Microsoft 365",
#   "mx_security_gateway": false,
#   "company_name": "Microsoft",
#   "company_industry": "Computer Software",
#   "company_size": "10001+",
#   "company_founded": 1975,
#   "company_type": "public",
#   "company_linkedin_url": "linkedin.com/company/microsoft",
#   "company_linkedin_id": "1035"
# }
```

---

## Personal Email Finder

Finds personal email addresses from B2B profile URLs (e.g., LinkedIn profiles). Consumes 1 credit when an email is found.

```bash
curl --request POST \
     --url https://api.leadmagic.io/personal-email-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "profile_url": "https://www.linkedin.com/in/williamhgates/"
     }'

# Response:
# {
#   "personal_email": "bill.gates@gmail.com",
#   "status": "found",
#   "credits_consumed": 1,
#   "message": "Personal email found"
# }
```

---

## B2B Social to Email

Finds work email addresses from B2B profile URLs. Useful for converting LinkedIn profiles to verified work emails. Consumes 1 credit.

```bash
curl --request POST \
     --url https://api.leadmagic.io/b2b-social-email \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "profile_url": "https://www.linkedin.com/in/williamhgates/"
     }'

# Response:
# {
#   "work_email": "bill.gates@microsoft.com",
#   "status": "found",
#   "credits_consumed": 1,
#   "message": "Work email found"
# }
```

---

## Email to B2B Profile

Finds B2B profile URLs using work email addresses. Enables reverse lookup from email to social profile. Consumes 10 credits.

```bash
curl --request POST \
     --url https://api.leadmagic.io/b2b-profile \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "work_email": "jesse@leadmagic.io"
     }'

# Response:
# {
#   "profile_url": "http://www.linkedin.com/in/jesseouehwx",
#   "message": "Profile URL found",
#   "credits_consumed": 10
# }
```

---

## Mobile Finder

Finds mobile phone numbers using profile URL, work email, or personal email. Provide at least one parameter. Consumes credits only when a number is found.

```bash
curl --request POST \
     --url https://api.leadmagic.io/mobile-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "profile_url": "https://www.linkedin.com/in/williamhgates/",
       "work_email": "jesse@leadmagic.io",
       "personal_email": "jesse.ouellette@gmail.com"
     }'

# Response (when found):
# {
#   "message": "Mobile found",
#   "credits_consumed": 1,
#   "mobile_number": "+1234567890"
# }

# Response (when not found):
# {
#   "message": "mobile not found",
#   "credits_consumed": 0,
#   "mobile_number": null
# }
```

---

## Profile Search

Retrieves comprehensive B2B profile information from a LinkedIn URL. Rate limited to 300 requests per minute. Consumes 1 credit.

```bash
curl --request POST \
     --url https://api.leadmagic.io/profile-search \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "profile_url": "https://www.linkedin.com/in/williamhgates/"
     }'

# Response:
# {
#   "profile_url": "https://www.linkedin.com/in/williamhgates/",
#   "first_name": "Bill",
#   "last_name": "Gates",
#   "full_name": "Bill Gates",
#   "public_identifier": "williamhgates",
#   "headline": "Chair, Gates Foundation and Founder, Breakthrough Energy",
#   "company_name": "Gates Foundation",
#   "company_size": "1001-5000",
#   "company_industry": "investment management",
#   "company_linkedin_url": "linkedin.com/company/bill-&-melinda-gates-foundation",
#   "company_website": "gatesfoundation.org",
#   "total_tenure_months": "305",
#   "total_tenure_days": "9150",
#   "total_tenure_years": "25.42",
#   "connections": 8,
#   "followers": 37841613,
#   "country": "United States",
#   "location": "Seattle, Washington, United States",
#   "about": "Chair of the Gates Foundation. Founder of Breakthrough Energy...",
#   "experiences": [
#     {
#       "company_id": "8736",
#       "title": "Co-chair",
#       "subtitle": "Gates Foundation",
#       "caption": "2000 - Present · 25 yrs 5 mos"
#     }
#   ],
#   "educations": [
#     {
#       "title": "Harvard University",
#       "caption": "1973 - 1975"
#     }
#   ],
#   "credits_consumed": 1
# }
```

---

## Role Finder

Finds people with specific job titles within companies. Requires `job_title` plus at least one of: `company_name`, `company_domain`, or `company_profile_url`. Consumes 0-1 credits.

```bash
curl --request POST \
     --url https://api.leadmagic.io/role-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "job_title": "Developer",
       "company_name": "Microsoft",
       "company_domain": "microsoft.com"
     }'

# Response:
# {
#   "message": "Role found.",
#   "credits_consumed": 1,
#   "company_name": "Microsoft",
#   "company_website": "microsoft.com"
# }
```

---

## Employee Finder

Finds employees of a specific company with pagination support. Maximum 50 results per page. Consumes 1 credit per request.

```bash
curl --request POST \
     --url https://api.leadmagic.io/employee-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_name": "Microsoft",
       "page": 1,
       "per_page": 5
     }'

# Response:
# {
#   "message": "Data found for the given company.",
#   "total_count": 5000,
#   "returned_count": 5,
#   "credits_consumed": 1,
#   "data": [
#     {
#       "first_name": "John",
#       "last_name": "Doe",
#       "title": "Senior Software Engineer",
#       "website": "http://www.microsoft.com",
#       "company_name": "Microsoft"
#     }
#   ]
# }
```

---

## Company Search

Retrieves detailed company information including locations, employee data, and social profiles. Provide at least one of: `company_domain`, `company_name`, or `profile_url`. Consumes 1 credit.

```bash
curl --request POST \
     --url https://api.leadmagic.io/company-search \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_domain": "leadmagic.io",
       "company_name": "Leadmagic"
     }'

# Response:
# {
#   "company_name": "LeadMagic",
#   "company_id": 75153174,
#   "locations": [
#     {
#       "country": "US",
#       "city": "Boston",
#       "geographic_area": "Massachusetts",
#       "postal_code": "02210",
#       "line1": "1 Seaport Ln",
#       "description": "Headquarters",
#       "headquarter": true,
#       "localized_name": "Boston",
#       "latitude": 42.36041,
#       "longitude": -71.05798
#     }
#   ],
#   "employee_count": 9,
#   "specialities": ["Sales", "Marketing", "ABM", "RevOps"],
#   "employee_count_range": {"start": 11, "end": 50},
#   "tagline": "LeadMagic tells you who is interested in your products or services...",
#   "follower_count": 6096,
#   "industry": "Internet",
#   "description": "LeadMagic tells you exactly what businesses are on your website...",
#   "website_url": "https://leadmagic.io",
#   "founded_on": {"year": 2022},
#   "universal_name": "leadmagichq",
#   "industry_v2_taxonomy": "Internet Publishing",
#   "url": "https://www.linkedin.com/company/leadmagichq/",
#   "credits_consumed": 1
# }
```

---

## Company Funding

Retrieves comprehensive funding information, financials, and competitor intelligence. Consumes 4 credits.

```bash
curl --request POST \
     --url https://api.leadmagic.io/company-funding \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_domain": "microsoft.com",
       "company_name": "Microsoft"
     }'

# Response:
# {
#   "basicInfo": {
#     "companyName": "Microsoft Corp.",
#     "description": "Microsoft develops and manufactures software and hardware...",
#     "shortName": "Microsoft",
#     "founded": "1975",
#     "primaryDomain": "microsoft.com",
#     "phone": "1-124-415-8000",
#     "status": "NEW",
#     "followers": 181691,
#     "ownership": "Public"
#   },
#   "financialInfo": {
#     "revenue": 270010000000,
#     "formattedRevenue": "270B",
#     "totalFunding": 61000000,
#     "formattedFunding": "61M"
#   },
#   "companySize": {
#     "employees": 221000,
#     "employeeRange": "100,000 - 9,999,999"
#   },
#   "topCompetitors": [
#     {
#       "name": "IBM",
#       "employees": "311,300",
#       "website": "https://www.ibm.com"
#     }
#   ],
#   "credits_consumed": 4
# }
```

---

## Jobs Finder

Searches for job postings with various filtering options. Supports pagination up to 50 results per page. Credits consumed based on results returned.

```bash
curl --request POST \
     --url https://api.leadmagic.io/jobs-finder \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_name": "Microsoft",
       "job_title": "Developer",
       "location": "New York",
       "experience_level": "senior",
       "job_description": "python \"software engineer\"",
       "country_id": "US",
       "page": 1,
       "per_page": 5
     }'

# Response:
# {
#   "total_count": 105,
#   "page": 1,
#   "per_page": 5,
#   "total_pages": 21,
#   "credits_consumed": 5,
#   "results": [
#     {
#       "company": {
#         "name": "Microsoft",
#         "website_url": "https://www.microsoft.com/",
#         "linkedin_url": "https://www.linkedin.com/company/microsoft/",
#         "twitter_handle": "Microsoft",
#         "github_url": "https://github.com/microsoft",
#         "is_agency": false
#       },
#       "title": "Technical Program Manager - Developer (AI)",
#       "location": "Redmond, Washington, United States",
#       "types": [{"id": 1, "name": "Full Time"}],
#       "cities": [{"geonameid": 5808079, "name": "Redmond", "country": {"code": "US", "name": "United States"}}],
#       "has_remote": false,
#       "published": "2025-06-25T20:36:00Z",
#       "application_url": "https://jobs.careers.microsoft.com/global/en/job/1833754/",
#       "language": "en",
#       "salary_min": "100600",
#       "salary_max": "215400",
#       "salary_currency": "USD",
#       "experience_level": "Mid Level"
#     }
#   ]
# }
```

---

## Get Job Countries

Retrieves the list of available countries for job filtering. Free metadata endpoint.

```bash
curl --request GET \
     --url https://api.leadmagic.io/job-country \
     --header 'X-API-Key: your-api-key'

# Response:
# [
#   {"id": "US", "name": "United States"},
#   {"id": "CA", "name": "Canada"},
#   {"id": "UK", "name": "United Kingdom"}
# ]
```

---

## Get Job Types

Retrieves the list of available job types for filtering. Free metadata endpoint.

```bash
curl --request GET \
     --url https://api.leadmagic.io/job-types \
     --header 'X-API-Key: your-api-key'

# Response:
# [
#   {"id": 1, "name": "Full Time"},
#   {"id": 2, "name": "Part Time"},
#   {"id": 3, "name": "Contract"}
# ]
```

---

## Google Ads Search

Searches for Google Ads campaigns by company domain or name. Returns ad creatives, dates, and advertiser information. Credits consumed based on ads found.

```bash
curl --request POST \
     --url https://api.leadmagic.io/google/searchads \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_domain": "gong.io",
       "company_name": "gong"
     }'

# Response:
# {
#   "credits_consumed": 8,
#   "ads": [
#     {
#       "advertiser_id": "AR14106062795078369281",
#       "creative_id": "CR14003695067076755457",
#       "advertiser_name": "Gong.io Inc",
#       "format": "Text",
#       "start": "2025-03-06",
#       "last_seen": "2025-06-27",
#       "original_url": "https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457",
#       "variants": [
#         {
#           "content": "<html content or JavaScript URL>",
#           "height": null,
#           "width": null
#         }
#       ]
#     }
#   ]
# }
```

---

## Meta Ads Search

Searches for Facebook and Instagram ads by company domain or name. Returns ad snapshots including images and videos. Credits consumed based on ads found.

```bash
curl --request POST \
     --url https://api.leadmagic.io/meta/searchads \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_domain": "gong.io",
       "company_name": "gong"
     }'

# Response:
# {
#   "credits_consumed": 2.6,
#   "ads": [
#     {
#       "ad_archive_id": "618153827656899",
#       "page_id": "105549201674375",
#       "page_name": "Lykkedal Retreat",
#       "is_active": true,
#       "publisher_platform": ["facebook", "instagram"],
#       "snapshot": {
#         "body": {"markup": "Ad body content..."},
#         "title": "Ad Title",
#         "cta_text": "Learn More",
#         "images": [{"original_image_url": "https://..."}],
#         "videos": [{"video_hd_url": "https://..."}]
#       }
#     }
#   ]
# }
```

---

## B2B Ads Search

Searches for B2B advertisement campaigns (LinkedIn ads) by company domain or name. Credits consumed based on ads found.

```bash
curl --request POST \
     --url https://api.leadmagic.io/b2b/searchads \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "company_domain": "microsoft.com",
       "company_name": "Microsoft"
     }'

# Response:
# {
#   "credits_consumed": 5,
#   "ads": [
#     {
#       "ad_id": "12345",
#       "company_name": "Microsoft",
#       "ad_title": "Microsoft Azure Cloud Services",
#       "ad_description": "Cloud computing platform description...",
#       "ad_url": "https://azure.microsoft.com"
#     }
#   ]
# }
```

---

## B2B Ad Details

Retrieves detailed information about a specific B2B ad including campaign information. Consumes 2 credits.

```bash
curl --request POST \
     --url https://api.leadmagic.io/b2b/ad-details \
     --header 'X-API-Key: your-api-key' \
     --header 'Content-Type: application/json' \
     --data '{
       "ad_id": "12345"
     }'

# Response:
# {
#   "ad_id": "12345",
#   "company_name": "Microsoft",
#   "ad_title": "Microsoft Azure Cloud Services",
#   "ad_description": "Detailed ad description...",
#   "ad_url": "https://azure.microsoft.com",
#   "campaign_info": {
#     "campaign_name": "Azure Q2 Campaign",
#     "start_date": "2025-04-01",
#     "end_date": "2025-06-30"
#   },
#   "credits_consumed": 2
# }
```

---

## Summary

LeadMagic API excels in three primary use cases: **Sales and Marketing Automation** (lead enrichment pipelines combining email validation, finder, and profile search for complete prospect profiles), **Recruitment and Talent Acquisition** (employee and role finder combined with profile search for building qualified candidate pipelines), and **Business Intelligence** (company search, funding data, job market analysis, and advertisement tracking for competitive landscape analysis). Common integration patterns include real-time enrichment via webhooks for instant lead scoring, batch processing for CRM synchronization and bulk data enhancement, and hybrid workflows that balance speed versus cost optimization.

Integration follows a credit-based model where operations consume varying credits: email validation (0.05), standard lookups (1), premium features like B2B profile reverse lookup (10), and comprehensive company funding (4). Error handling is consistent across all endpoints with standard HTTP status codes (400 for bad requests, 401 for authentication failures, 429 for rate limits) and a uniform error response format containing `error` and `message` fields. The OpenAPI 3.1 specification enables automatic client generation in 40+ languages, making it straightforward to integrate LeadMagic into any technology stack using tools like OpenAPI Generator, Swagger Codegen, or native platform importers.