### Set API Key and Install Dependencies

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Export your API key to the environment variable and install project dependencies before running API tests.

```bash
export LEADMAGIC_API_KEY=your-api-key-here
npm install
```

--------------------------------

### Clone Repository and Set Up Environment

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the directory, set your API key, install dependencies, and run initial tests.

```bash
git clone https://github.com/LeadMagic/leadmagic-openapi.git
cd leadmagic-openapi

export LEADMAGIC_API_KEY=your-api-key-here

npm install
npm run test:api
```

--------------------------------

### Sales Prospecting Workflow Example

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

This JavaScript snippet demonstrates a typical sales prospecting workflow using the LeadMagic API. It includes calls for finding emails, validating them, and searching for companies.

```javascript
// Sales prospecting workflow
await fetch("https://api.leadmagic.io/v1/people/email-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/email-validation", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/companies/company-search", { /* ... */ });
```

--------------------------------

### Recruiting Workflow Example

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

This JavaScript snippet illustrates a common recruiting workflow. It shows how to use the API to find suitable candidates based on roles, employee details, and general profile searches.

```javascript
// Recruiting workflow
await fetch("https://api.leadmagic.io/v1/people/role-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/employee-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/profile-search", { /* ... */ });
```

--------------------------------

### Competitive Intelligence Workflow Example

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

This JavaScript snippet outlines a competitive intelligence workflow. It demonstrates API calls for tracking company funding, finding relevant jobs, and searching for ad campaigns.

```javascript
// Competitive intelligence workflow
await fetch("https://api.leadmagic.io/v1/companies/company-funding", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/jobs/jobs-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/ads/google-ads-search", { /* ... */ });
```

--------------------------------

### MCP Client Configuration

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Guides on configuring AI clients like Cursor, Claude, and VS Code to use LeadMagic's hosted MCP server with OAuth or API key authentication.

```APIDOC
## MCP Client Configuration

### Description
Configure AI clients (Cursor, Claude, VS Code) to use LeadMagic's hosted MCP server with OAuth or API key authentication.

### OAuth Configuration (Recommended for Cursor v0.48+)

#### File: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "leadmagic": {
      "url": "https://mcp.leadmagic.io/mcp"
    }
  }
}
```

### API Key Fallback Configuration

#### File: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "leadmagic": {
      "type": "http",
      "url": "https://mcp.leadmagic.io/mcp",
      "headers": {
        "x-leadmagic-key": "${LEADMAGIC_API_KEY}"
      }
    }
  }
}
```

### Vercel AI SDK Integration

#### Code Example (TypeScript)

```typescript
import { createMCPClient } from "@ai-sdk/mcp";

const leadmagicMcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://mcp.leadmagic.io/mcp",
    headers: {
      "x-leadmagic-key": process.env.LEADMAGIC_API_KEY!,
    },
    redirect: "error",
  },
});

try {
  const tools = await leadmagicMcp.tools();
  // Pass `tools` into generateText, streamText, or your agent runtime
} finally {
  await leadmagicMcp.close();
}
```
```

--------------------------------

### Get Current Credit Balance

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Use this endpoint to retrieve your current credit balance. Requires an API key for authentication.

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

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

--------------------------------

### GET /v1/credits

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves credit information. This endpoint is free and has no rate limit specified.

```APIDOC
## GET /v1/credits

### Description
Retrieves the current credit balance. This endpoint is free to use.

### Method
GET

### Endpoint
/v1/credits

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **credits** (integer) - The current number of credits available.

#### Response Example
```json
{
  "credits": 1000
}
```
```

--------------------------------

### GET /v1/credits

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Retrieves the current credit balance for the authenticated user.

```APIDOC
## GET /v1/credits

### Description
Returns the current credit balance.

### Method
GET

### Endpoint
/v1/credits

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

### Response
#### Success Response (200)
- **credits** (number) - The total available credits.
- **is_frozen** (boolean) - Indicates if credits are frozen.
- **credits_frozen** (number) - The amount of frozen credits.
- **credits_liquid** (number) - The amount of liquid (usable) credits.
- **credit_freeze_message** (string | null) - Message explaining why credits are frozen.
- **credit_freeze_plan_hint** (string | null) - Hint about the plan related to credit freezing.

#### Response Example
```json
{
  "credits": 15432.5,
  "is_frozen": false,
  "credits_frozen": 0,
  "credits_liquid": 15432.5,
  "credit_freeze_message": null,
  "credit_freeze_plan_hint": null
}
```
```

--------------------------------

### Get Available Job Types

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Fetch a list of available job type IDs for use in job search filters. This endpoint is free and does not consume credits.

```bash
curl 'https://api.leadmagic.io/v1/jobs/job-types' \
  -H 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### Get Available Job Countries

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Retrieve a list of country codes supported for job search filtering. This is a free endpoint with no credit cost.

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

--------------------------------

### GET /v1/jobs/job-types

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Retrieves a list of supported job types for filtering.

```APIDOC
## GET /v1/jobs/job-types

### Description
Metadata: Returns a list of supported job types for filtering.

### Method
GET

### Endpoint
/v1/jobs/job-types

### Response
#### Success Response (200)
- **job_types** (array of objects) - List of job types with their IDs and names.

#### Response Example
```json
[
  { "id": "full_time", "name": "Full-time" },
  { "id": "part_time", "name": "Part-time" }
]
```
```

--------------------------------

### GET /v1/jobs/countries

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Retrieves a list of supported countries for job searches.

```APIDOC
## GET /v1/jobs/countries

### Description
Metadata: Returns a list of supported countries for job searches.

### Method
GET

### Endpoint
/v1/jobs/countries

### Response
#### Success Response (200)
- **countries** (array of objects) - List of countries with their codes and names.

#### Response Example
```json
[
  { "code": "US", "name": "United States" },
  { "code": "CA", "name": "Canada" }
]
```
```

--------------------------------

### GET /v1/jobs/job-types

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves a list of job types. This is a metadata endpoint and is free.

```APIDOC
## GET /v1/jobs/job-types

### Description
Retrieves a list of common job types or categories.

### Method
GET

### Endpoint
/v1/jobs/job-types

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **job_types** (array of strings) - A list of job type names.

#### Response Example
```json
{
  "job_types": ["Full-time", "Part-time", "Contract", "Internship"]
}
```
```

--------------------------------

### GET /v1/jobs/countries

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves a list of countries relevant to job postings. This is a metadata endpoint and is free.

```APIDOC
## GET /v1/jobs/countries

### Description
Retrieves a list of countries for which job data is available.

### Method
GET

### Endpoint
/v1/jobs/countries

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **countries** (array of strings) - A list of country names.

#### Response Example
```json
{
  "countries": ["USA", "Canada", "United Kingdom"]
}
```
```

--------------------------------

### Search Jobs with Filters

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Use the jobs-finder endpoint to search for job postings. Specify criteria like job title, company name, country, and experience level. Costs 1 credit per job returned.

```bash
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": "Software Engineer",
    "company_name": "Microsoft",
    "country_id": "US",
    "experience_level": "senior",
    "page": 1,
    "per_page": 5
  }'
```

--------------------------------

### Validate Against Live API

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/CONTRIBUTING.md

Ensure your API key is set as an environment variable and run the comprehensive test suite to validate changes against the live API.

```bash
# Ensure your API key is set
export LEADMAGIC_API_KEY=your-actual-api-key

# Run the comprehensive test suite
npm run test:api

# Test specific endpoints if you made targeted changes
```

--------------------------------

### Retrieve Company Funding and Financials

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Fetches comprehensive funding details, financial data, competitor information, and leadership insights for a company. This costs 4 credits and is free if no data is found.

```bash
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": "stripe.com"
  }'
```

--------------------------------

### Initialize LeadMagic MCP Client with API Key Header

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

This TypeScript code snippet demonstrates how to initialize the LeadMagic MCP client using the Vercel AI SDK. It configures the client to use an API key from the environment variable `LEADMAGIC_API_KEY` for programmatic access.

```typescript
import { createMCPClient } from "@ai-sdk/mcp";

const leadmagicMcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://mcp.leadmagic.io/mcp",
    headers: {
      "x-leadmagic-key": process.env.LEADMAGIC_API_KEY!,
    },
    redirect: "error",
  },
});

try {
  const tools = await leadmagicMcp.tools();
  // Pass `tools` into generateText, streamText, or your agent runtime.
} finally {
  await leadmagicMcp.close();
}
```

--------------------------------

### POST /v1/people/role-finder

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Finds people by job role. Costs 2 credits, free if no match is found.

```APIDOC
## POST /v1/people/role-finder

### Description
Finds individuals based on their job role within a company.

### Method
POST

### Endpoint
/v1/people/role-finder

### Parameters
#### Request Body
- **role** (string) - Required - The job role to search for.
- **company_domain** (string) - Required - The company domain.

### Request Example
```json
{
  "role": "Data Scientist",
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **people** (array of objects) - A list of people matching the role.
  - **name** (string) - The name of the person.
  - **email** (string, optional) - The person's email address.

#### Response Example
```json
{
  "people": [
    {
      "name": "Charlie Green",
      "email": "charlie.green@example.com"
    }
  ]
}
```
```

--------------------------------

### Configure MCP Client with API Key Fallback

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Configure the MCP client using an API key as a fallback authentication method. Ensure the LEADMAGIC_API_KEY environment variable is set.

```json
// .cursor/mcp.json - API key fallback
{
  "mcpServers": {
    "leadmagic": {
      "type": "http",
      "url": "https://mcp.leadmagic.io/mcp",
      "headers": {
        "x-leadmagic-key": "${LEADMAGIC_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Validate Email Address

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Validate an email address to check deliverability and get free company enrichment. The request body must contain an 'email' field.

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

--------------------------------

### Run API Tests

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Execute the API tests. If the API key is not exported, the script will prompt for it securely.

```bash
npm run test:api
```

--------------------------------

### Configure Cursor MCP with Default OAuth

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Use this JSON configuration for the Cursor IDE to connect to LeadMagic MCP using its default OAuth flow. Ensure Cursor is restarted after saving the configuration.

```json
{
  "mcpServers": {
    "leadmagic": {
      "url": "https://mcp.leadmagic.io/mcp"
    }
  }
}
```

--------------------------------

### Create Feature Branch

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/CONTRIBUTING.md

Fork the repository, checkout the main branch, and create a new feature branch for your contributions.

```bash
git checkout -b feature/improve-email-validation-docs
```

--------------------------------

### Configure Cursor MCP with API Key

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

This configuration is for Cursor IDE when OAuth is blocked. It uses an API key from the environment variable `LEADMAGIC_API_KEY`. Never commit the literal API key.

```json
{
  "mcpServers": {
    "leadmagic": {
      "type": "http",
      "url": "https://mcp.leadmagic.io/mcp",
      "headers": {
        "x-leadmagic-key": "${LEADMAGIC_API_KEY}"
      }
    }
  }
}
```

--------------------------------

### Run API Tests and Generate JSON Report

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Execute API tests and generate a JSON report without storing the API key in the report file.

```bash
npm run test:api -- --report reports/smoke-test.json
```

--------------------------------

### Use Environment Variables for API Keys in JavaScript

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/SECURITY.md

Always retrieve API keys from environment variables. Ensure the variable is set, and throw an error if it's missing.

```javascript
// DO: Use environment variables
const apiKey = process.env.LEADMAGIC_API_KEY;
if (!apiKey) {
  throw new Error("LEADMAGIC_API_KEY environment variable is required");
}
```

--------------------------------

### Credit System Overview

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Information about the credit system and costs associated with various API endpoints.

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

--------------------------------

### Fetch B2B Ad Details

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Use this endpoint to retrieve detailed information about a specific B2B ad using its ID. This operation costs 2 credits, or is free if the ad is not found.

```bash
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_id": "12345"
  }'
```

```json
{
  "ad_id": "12345",
  "company_name": "Microsoft",
  "ad_title": "Microsoft Azure Cloud Services",
  "ad_description": "Build, deploy, and scale applications...",
  "ad_url": "https://azure.microsoft.com",
  "campaign_info": {
    "campaign_name": "Azure Q2 Campaign",
    "start_date": "2025-04-01",
    "end_date": null
  },
  "credits_consumed": 2
}
```

--------------------------------

### Configure MCP Client with OAuth

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Configure the MCP client for AI assistants like Cursor using OAuth authentication. This is the recommended method for Cursor v0.48+.

```json
// .cursor/mcp.json - OAuth (recommended for Cursor v0.48+)
{
  "mcpServers": {
    "leadmagic": {
      "url": "https://mcp.leadmagic.io/mcp"
    }
  }
}
```

--------------------------------

### Run API Tests with Group and Report

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Combine flags to run tests for a specific group and generate a JSON report.

```bash
npm run test:api -- --group companies --report reports/companies.json
```

--------------------------------

### Enrich Company Information by Domain

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Obtains detailed company information using its domain name. This operation costs 1 credit and is free if the company is not found.

```bash
curl -X POST 'https://api.leadmagic.io/v1/companies/company-search' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_domain": "leadmagic.io"
  }'
```

--------------------------------

### Find Person by Job Title and Company

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Locates a person within a specific company based on their job title. This costs 2 credits and is free if the person is not found.

```bash
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": "microsoft.com"
  }'
```

--------------------------------

### Retrieve Comprehensive Profile Data

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Fetches detailed professional profile information using a profile URL. This costs 1 credit per request and is subject to a rate limit of 100 requests per minute.

```bash
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": "https://www.linkedin.com/in/williamhgates/"
  }'
```

--------------------------------

### POST /v1/jobs/jobs-finder

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Finds job postings. Costs 1 credit per job, free if no jobs are found.

```APIDOC
## POST /v1/jobs/jobs-finder

### Description
Searches for job postings based on specified criteria.

### Method
POST

### Endpoint
/v1/jobs/jobs-finder

### Parameters
#### Request Body
- **query** (string) - Required - The job search query (e.g., job title, keywords).
- **company_domain** (string) - Optional - Filter by a specific company domain.

### Request Example
```json
{
  "query": "Senior Software Engineer",
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **jobs** (array of objects) - A list of matching job postings.
  - **title** (string) - The job title.
  - **company** (string) - The company offering the job.
  - **location** (string) - The job location.
  - **url** (string) - The URL to the job posting.

#### Response Example
```json
{
  "jobs": [
    {
      "title": "Senior Software Engineer",
      "company": "Tech Innovations Inc.",
      "location": "Remote",
      "url": "https://example.com/jobs/123"
    }
  ]
}
```
```

--------------------------------

### Authenticate API Request with X-API-Key

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

All endpoints require an X-API-Key header for authentication. Ensure you never commit your API key directly; use environment variables or a secrets manager.

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

--------------------------------

### POST /v1/ads/b2b-ads-details

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves details for B2B Ads. Costs 2 credits, free if not found.

```APIDOC
## POST /v1/ads/b2b-ads-details

### Description
Retrieves detailed information about specific B2B Ads.

### Method
POST

### Endpoint
/v1/ads/b2b-ads-details

### Parameters
#### Request Body
- **ad_id** (string) - Required - The unique identifier for the B2B Ad.

### Request Example
```json
{
  "ad_id": "b2b-ad-xyz789"
}
```

### Response
#### Success Response (200)
- **ad_details** (object, optional) - Detailed information about the B2B Ad.
  - **headline** (string) - The ad headline.
  - **description** (string) - The ad description.
  - **company** (string) - The company advertising.
  - **url** (string) - The URL of the ad.
  - **targeting_criteria** (object) - Information on the ad's targeting.

#### Response Example
```json
{
  "ad_details": {
    "headline": "Leading B2B Marketing Software",
    "description": "Increase your lead generation with our powerful tools.",
    "company": "B2B Software Co.",
    "url": "https://example-b2b-ad-details.com",
    "targeting_criteria": {
      "industry": "Technology",
      "job_title": "Marketing Manager"
    }
  }
}
```
```

--------------------------------

### Convert B2B Profile URL to Work Email

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Converts a professional profile URL into a verified work email address. This costs 5 credits and is free if no email is found. Requires an X-API-Key header.

```bash
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": "https://www.linkedin.com/in/jesseouellette/"
  }'
```

```json
{
  "email": "jesse@leadmagic.io",
  "profile_url": "https://www.linkedin.com/in/jesseouellette/",
  "credits_consumed": 5,
  "message": "Work email found"
}
```

--------------------------------

### POST /v1/companies/company-funding

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves funding information for companies. Costs 4 credits, free if not found.

```APIDOC
## POST /v1/companies/company-funding

### Description
Retrieves funding rounds and investment information for a company.

### Method
POST

### Endpoint
/v1/companies/company-funding

### Parameters
#### Request Body
- **company_domain** (string) - Required - The domain of the company.

### Request Example
```json
{
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **funding_rounds** (array of objects) - A list of funding rounds.
  - **round_type** (string) - The type of funding round (e.g., Seed, Series A).
  - **amount** (string) - The amount raised.
  - **date** (string) - The date of the funding round.

#### Response Example
```json
{
  "funding_rounds": [
    {
      "round_type": "Series B",
      "amount": "$50,000,000",
      "date": "2023-01-15"
    }
  ]
}
```
```

--------------------------------

### POST /v1/jobs/jobs-finder Request

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Search for jobs using filters for company, title, location, pagination, and posting age. The minimal request includes job title, country ID, and days posted within.

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

--------------------------------

### Commit Changes

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/CONTRIBUTING.md

Commit your changes with a clear, descriptive message following conventional commit guidelines. Include details about the changes made.

```bash
git commit -m "docs: improve email validation response examples

- Added more realistic company data examples
- Clarified mx_provider field values
- Updated use cases section"
```

--------------------------------

### Employee Finder API

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Returns multiple employees for a company with pagination. Costs 0.05 credits per employee returned (20 employees per credit).

```APIDOC
## POST /api/people/employee-finder

### Description
Returns multiple employees for a company with pagination.

### Method
POST

### Endpoint
https://api.leadmagic.io/v1/people/employee-finder

### Parameters
#### Request Body
- **company_name** (string) - Required - The name of the company.
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **per_page** (integer) - Optional - The number of results per page. Defaults to 10.

### Request Example
```json
{
  "company_name": "Microsoft",
  "page": 1,
  "per_page": 10
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **total_count** (integer) - The total number of employees found.
- **returned_count** (integer) - The number of employees returned in this request.
- **credits_consumed** (number) - The number of credits consumed.
- **data** (array) - A list of employee objects.
  - **first_name** (string) - The first name of the employee.
  - **last_name** (string) - The last name of the employee.
  - **title** (string) - The job title of the employee.
  - **website** (string) - The website of the company.
  - **company_name** (string) - The name of the company.

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

--------------------------------

### LeadMagic Hosted MCP Sign-In

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms.txt

Details regarding the hosted LeadMagic MCP (Multi-Channel Platform) sign-in and authentication methods.

```APIDOC
## Hosted MCP Sign-In

The LeadMagic MCP provides various endpoints for sign-in and OAuth.

### Endpoints
- **Entrypoint**: `https://mcp.leadmagic.io/mcp`
- **Client Snippets**: `https://mcp.leadmagic.io/clients`
- **OAuth Authorization Server Metadata**: `https://mcp.leadmagic.io/.well-known/oauth-authorization-server`
- **OAuth Protected Resource Metadata**: `https://mcp.leadmagic.io/.well-known/oauth-protected-resource/mcp`
- **Registration Endpoint (DCR)**: `https://mcp.leadmagic.io/oauth/register`

### OAuth Scopes
- `openid`
- `profile`
- `email`
- `offline_access`

### Public OAuth Client
- **Client ID**: `4b9eLjoGVCJ1Dvnc`
- **Client Secret**: Blank (for PKCE, S256)

### Fallback Authentication Headers
- **API Key**: `x-leadmagic-key: <YOUR_API_KEY>`
- **Bearer Token**: `Authorization: Bearer <YOUR_LEADMAGIC_TOKEN>`

### Supported Clients
LeadMagic MCP supports integration with various clients including Cursor, Claude, ChatGPT, VS Code, and more. For Cursor, it is recommended to use the official plugin.
```

--------------------------------

### POST /v1/people/b2b-profile

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Retrieves B2B profile information. Costs 10 credits, free if not found.

```APIDOC
## POST /v1/people/b2b-profile

### Description
Retrieves detailed B2B profile information for an individual.

### Method
POST

### Endpoint
/v1/people/b2b-profile

### Parameters
#### Request Body
- **name** (string) - Required - The name of the person.
- **company_domain** (string) - Required - The company domain of the person.

### Request Example
```json
{
  "name": "Alice Brown",
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **profile** (object, optional) - The B2B profile details.
  - **job_title** (string) - The person's job title.
  - **linkedin_url** (string) - The LinkedIn profile URL.
  - **location** (string) - The person's location.

#### Response Example
```json
{
  "profile": {
    "job_title": "Software Engineer",
    "linkedin_url": "https://linkedin.com/in/alicebrown",
    "location": "San Francisco, CA"
  }
}
```
```

--------------------------------

### Find Employees within a Company

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Retrieves a list of employees for a given company, supporting pagination. The cost is 0.05 credits per employee, equivalent to 20 employees per credit.

```bash
curl -X POST 'https://api.leadmagic.io/v1/people/employee-finder' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Microsoft",
    "page": 1,
    "per_page": 10
  }'
```

--------------------------------

### Convert Work Email to B2B Profile URL

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Converts a work email address into a professional profile URL. This operation costs 10 credits and is free if no profile URL is found. Requires an X-API-Key header.

```bash
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": "jesse@leadmagic.io"
  }'
```

```json
{
  "profile_url": "https://www.linkedin.com/in/jesseouellette/",
  "message": "Profile URL found",
  "credits_consumed": 10
}
```

--------------------------------

### POST /v1/companies/company-funding Request

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Use this endpoint to retrieve funding rounds, investors, and leadership details for a company. A minimal request requires only the company domain.

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

--------------------------------

### Find Work Email with LeadMagic API

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Finds a verified work email address using a person's name and company domain or name. This costs 1 credit and is free if no email is found. Requires an X-API-Key header.

```bash
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": "Bill",
    "last_name": "Gates",
    "domain": "microsoft.com"
  }'
```

```json
{
  "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",
  "company_name": "Microsoft",
  "company_industry": "Computer Software",
  "company_size": "10001+",
  "company_founded": 1975,
  "company_type": "public"
}
```

--------------------------------

### Vercel AI SDK MCP Client Integration

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Integrate LeadMagic's MCP client with the Vercel AI SDK for programmatic agent access. Ensure the LEADMAGIC_API_KEY environment variable is set.

```typescript
// Vercel AI SDK integration
import { createMCPClient } from "@ai-sdk/mcp";

const leadmagicMcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://mcp.leadmagic.io/mcp",
    headers: {
      "x-leadmagic-key": process.env.LEADMAGIC_API_KEY!,
    },
    redirect: "error",
  },
});

try {
  const tools = await leadmagicMcp.tools();
  // Pass `tools` into generateText, streamText, or your agent runtime
} finally {
  await leadmagicMcp.close();
}
```

--------------------------------

### POST /v1/ads/b2b-ads-details Request

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/llms-full.txt

Fetch detailed information about B2B ads using either an ad library URL or an ad ID. The minimal request requires the ad URL.

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

--------------------------------

### POST /v1/people/employee-finder

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Finds employees within a company. Costs 0.05 credits per employee, with 20 employees per credit.

```APIDOC
## POST /v1/people/employee-finder

### Description
Finds employees within a specified company.

### Method
POST

### Endpoint
/v1/people/employee-finder

### Parameters
#### Request Body
- **company_domain** (string) - Required - The domain of the company.
- **limit** (integer) - Optional - The maximum number of employees to retrieve.

### Request Example
```json
{
  "company_domain": "example.com",
  "limit": 50
}
```

### Response
#### Success Response (200)
- **employees** (array of objects) - A list of employees.
  - **name** (string) - The employee's name.
  - **job_title** (string) - The employee's job title.

#### Response Example
```json
{
  "employees": [
    {
      "name": "David Lee",
      "job_title": "Product Manager"
    },
    {
      "name": "Eve Adams",
      "job_title": "UX Designer"
    }
  ]
}
```
```

--------------------------------

### POST /v1/people/email-finder

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Finds email addresses for individuals. Costs 1 credit, free if no result is found.

```APIDOC
## POST /v1/people/email-finder

### Description
Finds email addresses associated with a person based on provided details.

### Method
POST

### Endpoint
/v1/people/email-finder

### Parameters
#### Request Body
- **name** (string) - Required - The name of the person.
- **company_domain** (string) - Required - The company domain of the person.

### Request Example
```json
{
  "name": "John Doe",
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **email** (string, optional) - The found email address.

#### Response Example
```json
{
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### Search Google Ads

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Find Google Ads by specifying a company domain. This search costs 0.2 credits per query, allowing for 5 searches per credit.

```bash
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": "gong.io"
  }'
```

--------------------------------

### Profile Search API

Source: https://context7.com/leadmagic/leadmagic-openapi/llms.txt

Returns comprehensive professional profile data including work experience, education, and company information. Costs 1 credit. Rate limit: 100 requests/minute.

```APIDOC
## POST /api/people/profile-search

### Description
Returns comprehensive professional profile data including work experience, education, and company information.

### Method
POST

### Endpoint
https://api.leadmagic.io/v1/people/profile-search

### Parameters
#### Request Body
- **profile_url** (string) - Required - The URL of the professional profile.

### Request Example
```json
{
  "profile_url": "https://www.linkedin.com/in/williamhgates/"
}
```

### Response
#### Success Response (200)
- **credits_consumed** (integer) - The number of credits consumed.
- **profile_url** (string) - The URL of the profile.
- **first_name** (string) - The first name of the person.
- **last_name** (string) - The last name of the person.
- **full_name** (string) - The full name of the person.
- **public_identifier** (string) - The public identifier of the profile.
- **headline** (string) - The headline of the person.
- **company_name** (string) - The current company name.
- **company_size** (string) - The size of the company.
- **company_industry** (string) - The industry of the company.
- **connections** (integer) - The number of connections.
- **followers** (integer) - The number of followers.
- **country** (string) - The country of the person.
- **location** (string) - The location of the person.
- **about** (string) - A summary about the person.
- **experiences** (array) - List of work experiences.
  - **title** (string) - Job title.
  - **subtitle** (string) - Company name.
  - **caption** (string) - Duration.
- **educations** (array) - List of educational background.
  - **title** (string) - Institution name.
  - **caption** (string) - Duration.

#### Response Example
```json
{
  "credits_consumed": 1,
  "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",
  "connections": 8,
  "followers": 37841613,
  "country": "United States",
  "location": "Seattle, Washington, United States",
  "about": "Chair of the Gates Foundation. Founder of Breakthrough Energy.",
  "experiences": [
    {
      "title": "Co-chair",
      "subtitle": "Gates Foundation",
      "caption": "2000 - Present"
    }
  ],
  "educations": [
    {
      "title": "Harvard University",
      "caption": "1973 - 1975"
    }
  ]
}
```
```

--------------------------------

### POST /v1/people/personal-email-finder

Source: https://github.com/leadmagic/leadmagic-openapi/blob/main/README.md

Finds personal email addresses for individuals. Costs 2 credits, free if not found.

```APIDOC
## POST /v1/people/personal-email-finder

### Description
Finds personal email addresses for individuals.

### Method
POST

### Endpoint
/v1/people/personal-email-finder

### Parameters
#### Request Body
- **name** (string) - Required - The name of the person.
- **company_domain** (string) - Required - The company domain of the person.

### Request Example
```json
{
  "name": "Jane Smith",
  "company_domain": "example.com"
}
```

### Response
#### Success Response (200)
- **email** (string, optional) - The found personal email address.

#### Response Example
```json
{
  "email": "jane.smith@personaldomain.com"
}
```
```