LeadMagic

https://leadmagic.io/docs/v1
Admin
LeadMagic is a B2B data enrichment API and infrastructure platform providing REST endpoints, MCP...
Tokens:11,621
Snippets:170
Trust Score:8.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /v1/analytics/products

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

Returns a per-product breakdown showing requests, credits, success rates, and average costs.

```APIDOC
## GET /v1/analytics/products

### Description
Returns a per-product breakdown showing requests, credits, success rates, and average costs.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/products

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to retrieve (1-90)
```

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

### GET /v1/credits

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

Retrieves the current credit balance for the authenticated account.

```APIDOC
## GET /v1/credits

### Description
Get current credit balance.

### Method
GET

### Endpoint
/v1/credits

### Response
#### Success Response (200)
- **credits** (number) - Available credit balance

#### Response Example
{
  "credits": 15432.50
}
```

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

### Example Support Request

Source: https://leadmagic.io/docs/v1/support

A template for submitting a clear and actionable support request including the API key prefix, endpoint, request body, and response.

```markdown
**Issue:** Email validation returning "unknown" for valid emails

**API Key Prefix:** abc12345...

**Endpoint:** POST /v1/people/email-validation

**Request Body:**
{
  "email": "john@example.com"
}

**Response:**
{
  "status": "unknown",
  "email": "john@example.com"
}

**Expected:** Status should be "valid" as the email exists.

**Environment:** Node.js 20, using fetch API
```

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

### GET /v1/analytics/daily

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

Returns detailed daily metrics including latency percentiles, error rates, and performance data.

```APIDOC
## GET /v1/analytics/daily

### Description
Returns detailed daily metrics including latency percentiles, error rates, and performance data.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/daily

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to retrieve (1-90)
```

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

### Complete API Response Header Reference

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

A comprehensive example of all headers returned in a typical API response, including rate limits, credits, and concurrency metrics.

```http
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
```

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

### GET /v1/analytics/day/:date

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

Provides a per-product breakdown for a specific day, including the top 15 products and an aggregated 'other' category.

```APIDOC
## GET /v1/analytics/day/:date

### Description
Provides a per-product breakdown for a specific day, including the top 15 products and an aggregated 'other' category.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/day/:date

### Parameters
#### Path Parameters
- **date** (string) - Required - The date in YYYY-MM-DD format
```

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

### GET /v1/analytics/usage

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

Provides a daily usage summary including total requests, credits consumed, and chargeable rates.

```APIDOC
## GET /v1/analytics/usage

### Description
Provides a daily usage summary including total requests, credits consumed, and chargeable rates.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/usage

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to retrieve (1-90)
```

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

### Example API response

Source: https://leadmagic.io/docs/v1/quickstart

The structure of the JSON object returned by the email validation endpoint.

```json
{
  "email_status": "valid",
  "email": "test@leadmagic.io",
  "domain": "leadmagic.io",
  "credits_consumed": 0.25,
  "company": {
    "name": "LeadMagic",
    "domain": "leadmagic.io",
    "company_website": "https://leadmagic.io"
  }
}
```

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

### GET /v1/analytics/credits

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

Retrieves credit consumption history with a daily breakdown and chargeable request analysis.

```APIDOC
## GET /v1/analytics/credits

### Description
Retrieves credit consumption history with a daily breakdown and chargeable request analysis.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/credits

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to retrieve (1-90)
```

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

### GET /v1/credits/health

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

Validates the provided API key and checks the current authentication status.

```APIDOC
## GET /v1/credits/health

### Description
Validate API key and check authentication status.

### Method
GET

### Endpoint
/v1/credits/health
```

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

### Example Error Response

Source: https://leadmagic.io/docs/v1/making-api-calls

Standardized JSON structure returned when an API request fails, including validation details and debugging metadata.

```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",
    "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": "2025-10-01T12:00:00.000Z"
  }
}
```

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

### Validate an email address via API

Source: https://leadmagic.io/docs/v1/quickstart

Use these examples to send a POST request to the email validation endpoint. Ensure you replace YOUR_API_KEY or set the LEADMAGIC_API_KEY environment variable.

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

```javascript
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"
```

```python
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"
```

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

### GET /v1/analytics/summary

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

Provides all-time statistics including total requests, credits consumed, success rates, and first/last request timestamps.

```APIDOC
## GET /v1/analytics/summary

### Description
Provides all-time statistics including total requests, credits consumed, success rates, and first/last request timestamps.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/summary

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - Start date in YYYY-MM-DD format
- **end_date** (string) - Optional - End date in YYYY-MM-DD format
```

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

### Error Response with Request ID

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

Example of an error response structure containing the request identifier used for debugging.

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

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

### Standardized error response format

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

Example of an RFC 9457 compliant error response returned when a request fails.

```json
{
  "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/settings/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": "2025-10-01T12:00:00.000Z",
    "environment": "production"
  }
}
```

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

### GET /v1/analytics/dashboard

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

Retrieves a real-time dashboard snapshot including current credits, rate limit status, and usage statistics for today, this week, and this month.

```APIDOC
## GET /v1/analytics/dashboard

### Description
Retrieves a real-time dashboard snapshot including current credits, rate limit status, and usage statistics for today, this week, and this month.

### Method
GET

### Endpoint
https://api.leadmagic.io/v1/analytics/dashboard

### Response
#### Success Response (200)
- **user** (object) - User account details
- **credits** (object) - Current credit balance and formatting
- **rate_limit** (object) - Minute and daily rate limit usage statistics
- **concurrency** (object) - Current and peak concurrency metrics
- **stats** (object) - Aggregated usage stats for today, this week, and this month
```

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

### Retrieve Daily Usage Breakdown

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

Fetch a daily summary of requests and credit consumption for a specified number of days.

```bash
curl 'https://api.leadmagic.io/v1/analytics/usage?days=7' \
  -H 'X-API-Key: YOUR_API_KEY'
```

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

### Set API Key via Environment Variable

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

Use this command to store the API key in the environment rather than hardcoding it.

```bash
export LEADMAGIC_API_KEY="your_key_here"
```

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

### Retrieve Dashboard Overview

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

Fetch a real-time snapshot of account status, including current credits and rate limit utilization.

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

```javascript
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
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']}")
```

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

### Check credit balance via API

Source: https://leadmagic.io/docs/v1/credits

Use this cURL request to retrieve the current credit balance for the authenticated workspace.

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

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

### Configure Shared API Settings

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

Required base URL, authentication header, and content type for all API requests.

```text
Base URL: https://api.leadmagic.io
Authentication header: X-API-Key
Content type: application/json
```

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

### Retrieve operational context via cURL

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

Use the -I flag with cURL to inspect response headers containing credit and rate limit information without needing additional API calls.

```bash
# 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"}'
```

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

### Monitor Rate Limit Headers

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

Proactively monitor API usage by checking response headers for daily usage percentage and remaining credits.

```javascript
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;
}
```

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

### Authenticate API requests with an API key

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

Include the API key in the X-API-Key header for all requests. Ensure the key is stored securely, such as in environment variables.

```bash
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
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
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'}
)
```

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

### Handle 5xx Server Error

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

Returned when an unexpected server-side issue occurs; includes instructions for retrying or contacting support.

```json
{
  "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."
  }]
}
```

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

### Standard API Rate Limit and Credit Headers

Source: https://leadmagic.io/docs/v1/making-api-calls

Headers returned for standard metered requests, indicating remaining limits and credit consumption.

```http
RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 42
X-Credits-Remaining: 15432.50
X-Credits-Cost: 1
```

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

### POST /v1/credits/refresh

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

Forces a refresh of the credit balance from the database.

```APIDOC
## POST /v1/credits/refresh

### Description
Force refresh credits from database.

### Method
POST

### Endpoint
/v1/credits/refresh
```

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

### Implement Exponential Backoff

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

Use this pattern to handle 429 rate limit errors by retrying requests with an increasing delay.

```javascript
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');
}
```

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

### Credit Usage Headers

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

Custom headers included in every enrichment response to track credit consumption and remaining balance.

```http
X-Credits-Remaining: 15432.50
X-Credits-Cost: 1
```

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

### Handle 402 Payment Required Error

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

Returned when the account has insufficient credits to perform the requested operation.

```json
{
  "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
    }
  }]
}
```

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

### Cache Credits Check

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

Avoid redundant API calls by caching the credits balance for a specified TTL.

```javascript
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;
}
```

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

### Send Request with Idempotency Header

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

Include a unique X-Request-ID header in your POST requests to track and debug specific operations.

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

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

### Check account credit balance

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

Retrieve the current credit balance using an API key in the request header.

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

```javascript
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
import requests

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

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

### Use Request IDs for Debugging

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

Generate and attach a unique request ID to your fetch calls to facilitate easier troubleshooting.

```javascript
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}`);
```

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

### API Authentication

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

All requests to the LeadMagic API must be authenticated by providing a valid API key in the request header.

```APIDOC
## Authentication

### Description
The LeadMagic API uses API key authentication to secure all requests. You must include your API key in the `X-API-Key` header of every request.

### Authentication Method
- **Header**: `X-API-Key`
- **Value**: Your unique API key obtained from the LeadMagic dashboard settings.
```

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

### IETF Rate Limit Headers

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

Standardized HTTP headers used to communicate rate limit status, supported by many modern HTTP clients.

```http
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 42
```

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

### Handle 429 Rate Limit Error

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

Returned when request volume exceeds defined limits; includes context for retry timing.

```json
{
  "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
    }
  }]
}
```

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

### Unmetered Search API Rate Limit Headers

Source: https://leadmagic.io/docs/v1/making-api-calls

Headers returned for requests utilizing the unmetered search rate lane.

```http
X-LeadMagic-Rate-Lane: search-rps
X-RateLimit-RPS-Limit: 25
X-RateLimit-RPS-Remaining: 23
X-RateLimit-RPS-Reset: 1755993600
X-Credits-Cost: 0
```

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

### Handle 401 Unauthorized API Error Response

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

The structure of the JSON response returned when an API key is missing or invalid.

```json
{
  "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"
  }
}
```

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

### POST /v1/people/email-validation

Source: https://leadmagic.io/docs/v1/quickstart

Validates an email address and returns its status along with optional company firmographics.

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

### Description
Validates an email address to determine if it is valid, invalid, or unknown. The response may also include company context if available.

### Method
POST

### Endpoint
https://api.leadmagic.io/v1/people/email-validation

### Request Body
- **email** (string) - Required - The email address to validate.

### Request Example
{
  "email": "test@leadmagic.io"
}

### Response
#### Success Response (200)
- **email_status** (string) - The validation result (valid, invalid, or unknown).
- **email** (string) - The validated email address.
- **domain** (string) - The domain of the email.
- **credits_consumed** (number) - The amount of credits used for the request.
- **company** (object) - Optional company firmographics.

#### Response Example
{
  "email_status": "valid",
  "email": "test@leadmagic.io",
  "domain": "leadmagic.io",
  "credits_consumed": 0.25,
  "company": {
    "name": "LeadMagic",
    "domain": "leadmagic.io",
    "company_website": "https://leadmagic.io"
  }
}
```

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

### Handle 400 Validation Error

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

Returned when request parameters or JSON bodies fail validation checks.

```json
{
  "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"
  }]
}
```

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

### Conditionally Enrich Contacts

Source: https://leadmagic.io/docs/v1/credits

Use conditional logic to restrict expensive enrichment calls to specific job titles, reducing unnecessary credit consumption.

```javascript
// Only find mobile for VPs and above
if (contact.title.includes('VP') || contact.title.includes('Director')) {
  await findMobile(contact.linkedin_url);
}
```
Tokens:
Raw