Making API Calls

Learn how to integrate LeadMagic’s Data Enrichment API into your applications

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

Rate limits are subject to change. Need higher throughput? Custom rate limits are available on enterprise plans — contact us.

Endpoint	Rate Limit
Email Validation	300/min
Email Finder	300/min
Personal Email Finder	300/min
Profile to Email	300/min
Profile Search	100/min
Email to Profile	300/min
Mobile Finder	300/min
Job Change Detector	300/min
Role Finder	300/min
Employee Finder	300/min
Company Search	100/min
Company Funding	300/min
Competitors Search	300/min
Technographics	300/min
Jobs Finder	100/min
Google Ads Search	300/min
Meta Ads Search	300/min
B2B Ads Search	300/min
B2B Ad Details	300/min
Analytics (all)	No limit

Every response includes rate limit headers:

RateLimit-Limit: 300
RateLimit-Remaining: 287
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:

Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid parameters, malformed JSON
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits
404	Not Found	Profile or resource not found
429	Too Many Requests	Rate limit exceeded (check Retry-After header)
500	Server Error	Temporary issue - retry with backoff
502	Bad Gateway	External service error
503	Service Unavailable	Service temporarily down

Example Error Response

{
  "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.