Skip to main content
This guide covers request format, rate limits, and error handling for the LeadMagic API. If you haven’t made your first call yet, start with the Quickstart.

​
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
Personal Email Finder3,000/min
Profile to Email3,000/min
Profile Search500/min
Email to Profile3,000/min
Mobile Finder3,000/min
Job Change Detector3,000/min
Role Finder1,000/min
Employee Finder3,000/min
Company Search500/min
Company Funding3,000/min
Competitors Search2,000/min
Technographics1,000/min
Jobs Finder100/min
Google Ads Search3,000/min
Meta Ads Search3,000/min
B2B Ads Search3,000/min
B2B Ad Details3,000/min
Analytics (all)No limit
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://leadmagic.io/docs/v1/making-api-calls"
  }],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-10-01T12:00:00.000Z"
  }
}
Every error includes a request_id for debugging, suggested action to resolve, and link to relevant docs.

​
Security

See the Authentication guide for API key security best practices, including environment variables, server-side usage, and key rotation.

​
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.