> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/v1/quickstart).

## Request Format

All API requests should:

<CardGroup cols={2}>
  <Card title="Use POST Method" icon="paper-plane">
    All enrichment endpoints use HTTP POST requests with JSON body.
  </Card>

  <Card title="Include Headers" icon="heading">
    Set `Content-Type: application/json` and `X-API-Key` headers.
  </Card>

  <Card title="Send JSON Body" icon="brackets-curly">
    Request parameters go in the JSON body, not query string.
  </Card>

  <Card title="Handle Responses" icon="reply">
    Parse JSON responses and check the `status` field.
  </Card>
</CardGroup>

## Base URL

<Note>
  All API requests should be made to `https://api.leadmagic.io`.
</Note>

## Rate Limits

<Note>
  Rate limits are subject to change. Need higher throughput? Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
</Note>

| 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    |
| People Search         | 300/min    |
| Company Search        | 500/min    |
| Company Funding       | 300/min    |
| Company Lookalike     | 500/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:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 42
X-Credits-Remaining: 15432.50
X-Credits-Cost: 1
```

<Tip>
  See our [Developer Experience](/docs/v1/developer-experience) guide for complete header documentation and monitoring best practices.
</Tip>

## Error Handling

LeadMagic uses [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) 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                         |

<Accordion title="Example Error Response">
  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "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"
    }
  }
  ```
</Accordion>

<Info>
  Every error includes a `request_id` for debugging, suggested `action` to resolve, and link to relevant `docs`.
</Info>

## Security

<Tip>
  See the [Authentication](/docs/v1/authentication) guide for API key security best practices, including environment variables, server-side usage, and key rotation.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Developer Experience" icon="code" href="/docs/v1/developer-experience">
    Comprehensive guide to headers, analytics, error handling, and best practices.
  </Card>

  <Card title="Authentication Details" icon="key" href="/docs/v1/authentication">
    Learn more about API authentication and security.
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/docs/v1/reference/analytics">
    Monitor your usage with real-time dashboards and detailed metrics.
  </Card>

  <Card title="Email Validation" icon="envelope-circle-check" href="/docs/v1/reference/email-validation">
    Start validating emails with our most popular endpoint.
  </Card>
</CardGroup>