Skip to main content
Welcome to the LeadMagic API! This guide will help you make your first API call and understand the basics of our REST API.

​
Quick Start

1

Get your API Key

Log in to your LeadMagic account and navigate to your Account Profile to find your API key.
Your API key is displayed in the dashboard. Click to copy it to your clipboard.
2

Choose your endpoint

Select the endpoint for your use case: - Email Validation - Verify email addresses - Email Finder - Find emails from name + company - Mobile Finder - Get phone numbers - Profile Search - Enrich contact data
3

Make your first request

Use any HTTP client to make an API call. See the examples below.
4

Handle the response

Parse the JSON response and handle different status codes appropriately.

​
Your First API Call

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

​
Example Response

A successful request returns a JSON response: 
{
  "status": "valid",
  "email": "support@leadmagic.io",
  "domain": "leadmagic.io",
  "credits_consumed": 0.05,
  "company": {
    "name": "LeadMagic",
    "domain": "leadmagic.io",
    "linkedin_url": "https://linkedin.com/company/leadmagichq"
  }
}

​
Request Format

All API requests should:

Use POST Method

All enrichment endpoints use HTTP POST requests with JSON body.

Include Headers

Set Content-Type: application/json and X-API-Key headers.

Send JSON Body

Request parameters go in the JSON body, not query string.

Handle Responses

Parse JSON responses and check the status field.

​
Base URL

All API requests should be made to: https://api.leadmagic.io

​
Rate Limits

LeadMagic uses soft mode rate limiting by default - we log limit violations but allow requests through to prevent unexpected failures.
EndpointRate Limit
Email Validation3,000/min
Email Finder3,000/min
Mobile Finder3,000/min
Profile Search500/min
Company Search500/min
Jobs Finder100/min
Every response includes rate limit headers: 
RateLimit-Limit: 3000
RateLimit-Remaining: 2847
RateLimit-Reset: 42
X-Credits-Remaining: 15432.50
X-Credits-Cost: 1
See our Developer Experience guide for complete header documentation and monitoring best practices.

​
Error Handling

LeadMagic uses RFC 9457 Problem Details for standardized error responses:
CodeDescriptionCommon Causes
200SuccessRequest completed successfully
400Bad RequestInvalid parameters, malformed JSON
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient credits
404Not FoundProfile or resource not found
429Too Many RequestsRate limit exceeded (check Retry-After header)
500Server ErrorTemporary issue - retry with backoff
502Bad GatewayExternal service error
503Service UnavailableService temporarily down
{
  "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://docs.leadmagic.io/api-reference/errors"
  }],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-10-01T12:00:00.000Z"
  }
}
Every error includes a request_id for debugging, suggested action to resolve, and link to relevant docs.

​
Security Best Practices

Your API key is like a password. Never expose it in client-side code or public repositories.
Store your API key in environment variables or a secure secrets manager. Never commit it to version control.
Always make API calls from your backend server, not from client-side JavaScript.
If you suspect your API key has been exposed, regenerate it immediately from your dashboard.

​
Next Steps

Developer Experience

Comprehensive guide to headers, analytics, error handling, and best practices.

Authentication Details

Learn more about API authentication and security.

Analytics API

Monitor your usage with real-time dashboards and detailed metrics.

Email Validation

Start validating emails with our most popular endpoint.