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

# Company Search

> Canonical V3 company lookup with all company filters.

# Company Search

`POST /v3/companies/search` is the single V3 company lookup endpoint for building and paging through account lists from structured criteria.

Use Company Search for both one-company lookup and filtered company lists. Send a single identifier such as `company_domain`, `domain`, `website`, `company_name`, `profile_url`, or `linkedin_url` for one company, or use `company_filters` for account lists.

<Info>
  Existing clients that send one-company search bodies such as `company_domain`, `domain`, `website`, `company_name`, `profile_url`, or `linkedin_url` can keep using the same request shape. When no broad filters or explicit `limit` are supplied, the API treats the request as a one-row lookup and returns the richer company record plus legacy-friendly aliases such as `companyName`, `companyDomain`, and `websiteUrl`.
</Info>

<Tip>
  You can pass multiple company identities at once using `company_domains`, `company_websites`, B2B company profile inputs, and `company_names`. Those identity filters are treated as alternatives, then the rest of your filters narrow the matched set.
</Tip>

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                                            |
    | -------------- | ------------------------------------------------ |
    | **Search**     | **1 credit** per returned company                |
    | **No results** | **FREE**                                         |
    | **Page cap**   | `limit` max is `50`; use `offset` for pagination |

    <Tip>
      Credits finalize by returned company count, not by requested limit.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value                       |
    | ------------------- | --------------------------- |
    | **Requests/Minute** | 500                         |
    | **Burst Capacity**  | Subject to workspace limits |
  </Tab>
</Tabs>

***

## Quick Examples

Use **one** of the patterns below. They hit the same endpoint but return different response shapes.

<Tabs>
  <Tab title="One company lookup" icon="building">
    Send a single company identifier at the request root. Do **not** include `company_filters`, `query`, or `limit` unless you want list mode.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
        -H 'X-API-Key: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "company_domain": "leadmagic.io"
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
        method: 'POST',
        headers: {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          company_domain: 'leadmagic.io'
        })
      });

      const data = await response.json();
      console.log(data.companyName, data.company?.company_domain);
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api.leadmagic.io/v3/companies/search',
          headers={'X-API-Key': 'YOUR_API_KEY'},
          json={'company_domain': 'leadmagic.io'}
      )

      data = response.json()
      print(data.get('companyName'), data.get('company', {}).get('company_domain'))
      ```
    </CodeGroup>

    **Accepted root fields:** `company_domain` (preferred), `domain`, `website`, `company_name`, `profile_url`, `linkedin_url` (and aliases listed below).

    **Response extras:** `found`, `company`, `companyName`, `companyDomain`, `websiteUrl`, `linkedinUrl` plus `companies[]` with one row.
  </Tab>

  <Tab title="Filtered company list" icon="list">
    Send structured filters to build or page through an account list.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST 'https://api.leadmagic.io/v3/companies/search' \
        -H 'X-API-Key: YOUR_API_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "limit": 10,
          "offset": 0,
          "company_filters": {
            "company_domains": ["leadmagic.io"],
            "country_codes": ["US"],
            "min_total_contacts": 1
          }
        }'
      ```

      ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const response = await fetch('https://api.leadmagic.io/v3/companies/search', {
        method: 'POST',
        headers: {
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          limit: 10,
          offset: 0,
          company_filters: {
            company_domains: ['leadmagic.io'],
            country_codes: ['US'],
            min_total_contacts: 1
          }
        })
      });

      const data = await response.json();
      console.log(`${data.count} companies`);
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import requests

      response = requests.post(
          'https://api.leadmagic.io/v3/companies/search',
          headers={'X-API-Key': 'YOUR_API_KEY'},
          json={
              'limit': 10,
              'offset': 0,
              'company_filters': {
                  'company_domains': ['leadmagic.io'],
                  'country_codes': ['US']
              }
          }
      )

      data = response.json()
      print(f"{data['count']} companies")
      ```
    </CodeGroup>

    **Response focus:** `companies[]`, `count`, `limit_applied`, `offset`, `interpreted_search`. Legacy single-company aliases are omitted in list mode.
  </Tab>
</Tabs>

<Warning>
  Adding `limit`, `company_filters`, or `query` switches the request to **list mode**. For a single-company lookup, send only identity fields such as `company_domain` or `linkedin_url`.
</Warning>

## Request Body

<ParamField body="company_domain" type="string">
  One-company lookup: company domain (preferred). Aliases: `domain`, `website`, `company_website`.
</ParamField>

<ParamField body="company_name" type="string">
  One-company lookup: company name. Aliases: `name`.
</ParamField>

<ParamField body="profile_url" type="string">
  One-company lookup: B2B company profile URL. Aliases: `linkedin_url`, `company_linkedin_url`, `company_url`, `url`.
</ParamField>

<ParamField body="company_filters" type="object">
  List search: primary filter object. You may also send the same fields inside `filters` or at the request root; `company_filters` is preferred for new integrations.
</ParamField>

<ParamField body="query" type="string">
  Optional natural-language/company keyword query. Use structured fields when you know the exact filters.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Number of companies to return. Maximum is `50` for this public API route.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Offset for pagination. Increase by `limit` to fetch the next page.
</ParamField>

## Company Identity Filters

| Field                                   | Type       | Matching behavior                                   |
| --------------------------------------- | ---------- | --------------------------------------------------- |
| `company_domains`                       | `string[]` | Exact normalized domain match, e.g. `leadmagic.io`  |
| `company_websites`                      | `string[]` | Normalized to domain-equivalent exact matches       |
| `linkedin_urls`                         | `string[]` | Exact normalized B2B company profile matches        |
| `company_names`                         | `string[]` | Exact case-insensitive company name match           |
| `company_domain`                        | `string`   | Single-value alias for `company_domains`            |
| `company_website` / `website`           | `string`   | Single-value aliases for `company_websites`         |
| `linkedin_url` / `company_linkedin_url` | `string`   | Single-value aliases for B2B company profile inputs |
| `company_name` / `name`                 | `string`   | Single-value aliases for company name search        |

## Firmographic Filters

| Field                                | Type                  | Description                                        |
| ------------------------------------ | --------------------- | -------------------------------------------------- |
| `country_codes` / `country_code`     | `string[]` / `string` | HQ country codes such as `US`, `GB`, `CA`          |
| `industries` / `industry`            | `string[]` / `string` | B2B industry labels                                |
| `employee_ranges` / `employee_range` | `string[]` / `string` | Ranges such as `51 to 200`, `201 to 500`, `10001+` |
| `min_employees`                      | `integer`             | Minimum employee count/range overlap               |
| `max_employees`                      | `integer`             | Maximum employee count/range overlap               |
| `revenue_ranges` / `revenue_range`   | `string[]` / `string` | Revenue labels such as `$10M to <$50M`             |
| `min_revenue`                        | `integer`             | Minimum revenue                                    |
| `max_revenue`                        | `integer`             | Maximum revenue                                    |
| `founded_after`                      | `integer`             | Minimum founded year                               |
| `founded_before`                     | `integer`             | Maximum founded year                               |
| `company_entity_types`               | `string[]`            | Legal/company entity type labels                   |
| `domain_tlds`                        | `string[]`            | Domain TLDs such as `io`, `com`, `ai`              |

## Location Filters

| Field           | Type       |
| --------------- | ---------- |
| `hq_countries`  | `string[]` |
| `hq_regions`    | `string[]` |
| `hq_cities`     | `string[]` |
| `hq_states`     | `string[]` |
| `hq_continents` | `string[]` |
| `hq_streets`    | `string[]` |
| `hq_postcodes`  | `string[]` |

## Funding Filters

| Field                                                       | Type       | Description                                     |
| ----------------------------------------------------------- | ---------- | ----------------------------------------------- |
| `has_funding`                                               | `boolean`  | Require or exclude companies with known funding |
| `min_total_funding` / `max_total_funding`                   | `integer`  | Funding amount bounds                           |
| `last_funding_types`                                        | `string[]` | Funding round/type labels                       |
| `last_funding_after` / `last_funding_before`                | `string`   | Date bounds for last funding                    |
| `min_funding_investor_count` / `max_funding_investor_count` | `integer`  | Investor-count bounds                           |
| `lead_investors`                                            | `string[]` | Fuzzy lead investor text search                 |

## Contact Coverage Filters

| Field                                                 | Type      |
| ----------------------------------------------------- | --------- |
| `min_total_contacts` / `max_total_contacts`           | `integer` |
| `min_contacts_with_email` / `max_contacts_with_email` | `integer` |
| `min_contacts_with_phone` / `max_contacts_with_phone` | `integer` |
| `min_valid_email_count` / `max_valid_email_count`     | `integer` |

## Technology Filters

| Field                            | Type       | Description                                                     |
| -------------------------------- | ---------- | --------------------------------------------------------------- |
| `has_tech_stack`                 | `boolean`  | Require a detected tech stack                                   |
| `tech_stack` / `technologies`    | `string[]` | Generic technology search across indexed tech/specialty columns |
| `crm_tech`                       | `string[]` | CRM technologies                                                |
| `marketing_automation_tech`      | `string[]` | Marketing automation                                            |
| `sales_automation_tech`          | `string[]` | Sales automation                                                |
| `analytics_tech`                 | `string[]` | Analytics tools                                                 |
| `cloud_provider_tech`            | `string[]` | Cloud platforms such as AWS, GCP, Azure                         |
| `development_tech`               | `string[]` | Development frameworks/tools                                    |
| `ecommerce_tech`                 | `string[]` | Ecommerce platforms                                             |
| `erp_tech`                       | `string[]` | ERP platforms                                                   |
| `email_hosting_tech`             | `string[]` | Email hosting                                                   |
| `email_security_tech`            | `string[]` | Email security                                                  |
| `abm_tech`                       | `string[]` | ABM tools                                                       |
| `cms_tech`                       | `string[]` | CMS tools                                                       |
| `conversation_intelligence_tech` | `string[]` | Conversation intelligence tools                                 |
| `app_security_tech`              | `string[]` | Application security tools                                      |
| `cloud_security_tech`            | `string[]` | Cloud security tools                                            |
| `company_martech`                | `string[]` | Marketing technology                                            |

## Text And Classification Filters

| Field                | Type       |
| -------------------- | ---------- |
| `keyword`            | `string`   |
| `specialties`        | `string[]` |
| `company_headlines`  | `string[]` |
| `company_about`      | `string[]` |
| `company_phones`     | `string[]` |
| `sic_codes`          | `string[]` |
| `naics_codes`        | `string[]` |
| `sic_descriptions`   | `string[]` |
| `naics_descriptions` | `string[]` |

## Website Filters

| Field                                             | Type      |
| ------------------------------------------------- | --------- |
| `website_active`                                  | `boolean` |
| `website_for_sale`                                | `boolean` |
| `min_total_app_reviews` / `max_total_app_reviews` | `integer` |

## Sort

| Field        | Type     | Values                                                              |
| ------------ | -------- | ------------------------------------------------------------------- |
| `sort_by`    | `string` | `company_domain`, `total_funding`, `founded_year`, `total_contacts` |
| `sort_order` | `string` | `asc`, `desc`                                                       |

## Response

<ResponseField name="companies" type="object[]">
  Company records matching your criteria.
</ResponseField>

<ResponseField name="company" type="object">
  Present for one-company lookup requests. Contains the first returned company record.
</ResponseField>

<ResponseField name="found" type="boolean">
  Present for one-company lookup requests. `true` when a company row was returned.
</ResponseField>

<ResponseField name="companyName" type="string">
  Present for one-company lookup requests. Alias for `company.company_name`.
</ResponseField>

<ResponseField name="companyDomain" type="string">
  Present for one-company lookup requests. Alias for `company.company_domain`.
</ResponseField>

<ResponseField name="websiteUrl" type="string">
  Present for one-company lookup requests. Alias for `company.company_website`.
</ResponseField>

<ResponseField name="linkedinUrl" type="string">
  Present for one-company lookup requests. Alias for `company.linkedin_url`.
</ResponseField>

<ResponseField name="count" type="integer">
  Number of companies returned.
</ResponseField>

<ResponseField name="returned_count" type="integer">
  Alias for `count`.
</ResponseField>

<ResponseField name="limit_applied" type="integer">
  Applied page size.
</ResponseField>

<ResponseField name="offset" type="integer">
  Applied offset.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Finalized credits charged (1 per returned company; `0` when no companies match).
</ResponseField>

<ResponseField name="interpreted_search" type="object">
  Normalized filters used by the backend.
</ResponseField>

### Example Responses

<CodeGroup>
  ```json One company lookup theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "message": "Companies found",
    "credits_consumed": 1,
    "found": true,
    "companyName": "LeadMagic",
    "companyDomain": "leadmagic.io",
    "websiteUrl": "https://leadmagic.io",
    "company": {
      "company_domain": "leadmagic.io",
      "company_name": "LeadMagic"
    },
    "companies": [
      {
        "company_domain": "leadmagic.io",
        "company_name": "LeadMagic"
      }
    ],
    "count": 1,
    "returned_count": 1,
    "limit_applied": 1,
    "offset": 0
  }
  ```

  ```json Filtered company list theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "message": "Companies found",
    "credits_consumed": 1,
    "companies": [
      {
        "company_domain": "leadmagic.io",
        "company_name": "LeadMagic",
        "hq_country_code": "US"
      }
    ],
    "count": 1,
    "returned_count": 1,
    "limit_applied": 10,
    "offset": 0,
    "interpreted_search": {
      "company_filters": {
        "company_domains": ["leadmagic.io"],
        "country_codes": ["US"]
      }
    }
  }
  ```
</CodeGroup>

Returned company rows can include:

`company_domain`, `company_name`, `company_website`, `company_industry_linkedin`, `employee_range`, `employee_min`, `employee_max`, `revenue_range`, `revenue_min`, `revenue_max`, `hq_country`, `hq_country_code`, `hq_city`, `hq_state`, `hq_street`, `hq_postcode`, `hq_region`, `hq_continent`, `founded_year`, `category`, `specialties`, `total_funding`, `funding_investor_count`, `last_funding_type`, `last_funding_date`, `last_funding_amount`, `lead_investors`, `linkedin_url`, `company_headline`, `company_about`, `company_logo_url`, `company_phone`, `company_entity_type`, `has_tech_stack`, `total_contacts`, `contacts_with_email`, `contacts_with_phone`, `valid_email_count`, `website_active`, `website_for_sale`, `sic_code`, `naics_code`, `sic_description`, `naics_description`, `domain_tld`, `total_app_reviews`, and all technology columns listed above.

## Related endpoints

<CardGroup cols={2}>
  <Card title="Company Lookalike" icon="sparkles" href="/docs/v1/reference/company-lookalike">
    Find similar accounts from a seed company and return the same full company row shape.
  </Card>

  <Card title="Technographics" icon="microchip" href="/docs/v1/reference/technographics">
    Get detailed technology stack information for one company.
  </Card>

  <Card title="People Search" icon="users" href="/docs/v1/reference/people-search">
    Search contacts across one company or a filtered company set.
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v3/companies/search
openapi: 3.1.0
info:
  title: LeadMagic API
  version: 1.4.34
  description: >
    # LeadMagic API Documentation


    The LeadMagic API provides comprehensive B2B data enrichment services
    including email validation, email finding, profile search, company
    intelligence, and more.


    ## Quick Start


    1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)

    2. Add the `X-API-Key` header to all requests

    3. Start enriching your data!


    ## Base URL


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


    ## Rate Limits


    Each endpoint has specific rate limits (requests per minute). Exceeding
    limits returns a `429 Too Many Requests` response.


    ## Credits


    API calls consume credits based on the endpoint used. Check your balance
    with the `/v1/credits` endpoint.


    ## Support


    Contact us at support@leadmagic.io for assistance.
  contact:
    name: LeadMagic Support
    email: support@leadmagic.io
    url: https://leadmagic.io
  termsOfService: https://leadmagic.io/legal/terms
servers:
  - url: https://api.leadmagic.io
    description: Production API Server
security:
  - ApiKeyAuth: []
tags:
  - name: Credits
    description: Manage and check your credit balance
  - name: Analytics
    description: >-
      Monitor your API usage with comprehensive analytics endpoints (FREE - no
      credits consumed)
  - name: People Enrichment
    description: Find and validate contact information for individuals
  - name: Company Data
    description: Discover company information and intelligence
  - name: Jobs Data
    description: Search job listings and detect career changes
  - name: Ads Data
    description: Search advertising data across platforms
paths:
  /v3/companies/search:
    post:
      tags:
        - Company Data
      summary: Company Search
      description: >
        Canonical V3 company endpoint. Supports two request shapes on the same
        path:


        1. **One-company lookup** — send a single identity field at the root
        (`company_domain`, `domain`, `website`, `company_name`, `profile_url`,
        or `linkedin_url`) without `company_filters`, `query`, or an explicit
        `limit`. Returns one row plus legacy aliases (`found`, `company`,
        `companyName`, `companyDomain`, `websiteUrl`, `linkedinUrl`).


        2. **Filtered company list** — send `company_filters` (and optional
        `limit`, `offset`) to page through matching accounts.
      operationId: company-search-v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                company_domain:
                  type: string
                  description: >-
                    Direct one-company lookup input. Returns one rich company
                    row plus legacy-friendly aliases when no broad filters or
                    explicit limit are supplied.
                  example: leadmagic.io
                domain:
                  type: string
                  description: Alias for company_domain.
                website:
                  type: string
                  description: Company website URL or domain.
                company_name:
                  type: string
                  description: Company name lookup input.
                profile_url:
                  type: string
                  description: Company profile URL.
                linkedin_url:
                  type: string
                  description: Company profile URL.
                company_filters:
                  type: object
                  additionalProperties: true
                  description: Full company filter object.
                query:
                  type: string
                limit:
                  type: integer
                  minimum: 1
                  maximum: 50
                  default: 10
                offset:
                  type: integer
                  default: 0
                  minimum: 0
            examples:
              oneCompanyLookup:
                summary: One company lookup
                description: >-
                  Send only identity fields. Omit limit unless you want list
                  mode.
                value:
                  company_domain: leadmagic.io
              filteredCompanyList:
                summary: Filtered company list
                description: Use company_filters to build or page through account lists.
                value:
                  limit: 10
                  offset: 0
                  company_filters:
                    company_domains:
                      - leadmagic.io
                    country_codes:
                      - US
                    crm_tech:
                      - Salesforce
            example:
              company_domain: leadmagic.io
      responses:
        '200':
          description: Company search results
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  message:
                    type: string
                  credits_consumed:
                    type: number
                  companies:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  found:
                    type: boolean
                    description: Present for one-company lookup requests.
                  company:
                    type: object
                    nullable: true
                    additionalProperties: true
                    description: >-
                      Present for one-company lookup requests. Contains the
                      first returned company row.
                  companyName:
                    type: string
                    nullable: true
                    description: >-
                      Present for one-company lookup requests. Alias for
                      company.company_name.
                  companyDomain:
                    type: string
                    nullable: true
                    description: >-
                      Present for one-company lookup requests. Alias for
                      company.company_domain.
                  websiteUrl:
                    type: string
                    nullable: true
                    description: >-
                      Present for one-company lookup requests. Alias for
                      company.company_website.
                  linkedinUrl:
                    type: string
                    nullable: true
                    description: >-
                      Present for one-company lookup requests. Alias for
                      company.linkedin_url.
                  count:
                    type: integer
                  returned_count:
                    type: integer
                  limit_applied:
                    type: integer
                  offset:
                    type: integer
                  interpreted_search:
                    type: object
                    additionalProperties: true
                  metadata:
                    type: object
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  responses:
    BadRequest:
      description: |
        Bad Request - The request was malformed or contains invalid parameters.

        **Common causes:**
        - Missing required fields
        - Invalid field format (e.g., malformed email)
        - Invalid JSON syntax
        - Invalid parameter values
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    Unauthorized:
      description: |
        Unauthorized - Authentication failed.

        **Common causes:**
        - Missing X-API-Key header
        - Invalid or expired API key
        - Malformed API key
      content:
        application/problem+json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MissingAuthenticationError'
              - $ref: '#/components/schemas/InvalidApiKeyError'
    PaymentRequired:
      description: >
        Payment Required - Insufficient credits for this request.


        **Action required:** Add credits to your account at
        https://app.leadmagic.io/billing
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InsufficientCreditsError'
    RateLimitExceeded:
      description: |
        Too Many Requests - Rate limit exceeded.

        **Action required:** Check the `Retry-After` header for when to retry.

        **Headers returned:**
        - `Retry-After`: Seconds until you can retry
        - `RateLimit-Limit`: Your limit per minute
        - `RateLimit-Remaining`: Remaining requests this minute
        - `RateLimit-Reset`: Seconds until limit resets
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests this minute
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until limit resets
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/RateLimitExceededError'
  schemas:
    ValidationError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        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. Expected format: user@domain.com'
            action: Provide a valid email address in the 'email' field.
            docs: https://leadmagic.io/docs/api-reference/errors
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    MissingAuthenticationError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/missing_authentication
            title: >-
              Authentication required. Provide a valid API key in the X-API-Key
              header (case-insensitive).
            status: 401
            code: missing_authentication
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    InvalidApiKeyError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        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
            docs: https://leadmagic.io/docs/api-reference/authentication
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    InsufficientCreditsError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        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
            code: insufficient_credits
            detail: >-
              This request requires 5 credit(s) but your account only has 2.50
              credits remaining.
            action: >-
              Add credits to your account at https://app.leadmagic.io/billing or
              contact support@leadmagic.io for enterprise plans.
            docs: https://leadmagic.io/docs/api-reference/credits
            context:
              credits_required: 5
              credits_available: 2.5
              credits_needed: 2.5
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    RateLimitExceededError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      example:
        success: false
        errors:
          - type: https://api.leadmagic.io/errors/rate_limit_exceeded
            title: >-
              Rate limit exceeded: 300 requests per 1 minute. Wait and try
              again.
            status: 429
            code: rate_limit_exceeded
            detail: >-
              You have exceeded the maximum allowed request rate. Please wait
              before making additional requests.
            action: >-
              Wait 42 seconds before retrying. Consider implementing exponential
              backoff.
            docs: https://leadmagic.io/docs/api-reference/rate-limits
            context:
              limit: 300
              window: 1 minute
              remaining: 0
              reset_at: 1706745642
              retry_after_seconds: 42
        meta:
          request_id: ea6e3248-f4d2-437d-bca3-20881b529129
          timestamp: '2024-02-01T12:00:00.000Z'
    ErrorResponse:
      type: object
      description: RFC 9457 Problem Details error response
      required:
        - success
        - errors
      properties:
        success:
          type: boolean
          example: false
          description: Always false for error responses
        errors:
          type: array
          description: Array of error details (typically one, but can be multiple)
          items:
            $ref: '#/components/schemas/ErrorDetail'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ErrorDetail:
      type: object
      description: RFC 9457 compliant error detail
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: RFC 9457 - URI reference identifying the error type
          example: https://api.leadmagic.io/errors/validation_error
        title:
          type: string
          description: RFC 9457 - Short human-readable summary
          example: Request validation failed. Check your input parameters.
        status:
          type: integer
          description: RFC 9457 - HTTP status code
          example: 400
        detail:
          type: string
          description: RFC 9457 - Human-readable explanation specific to this occurrence
          example: The email field is required but was not provided.
        instance:
          type: string
          format: uri
          description: RFC 9457 - URI reference for this specific occurrence
          example: /v1/people/email-validation#req_abc123
        code:
          type: string
          description: Machine-readable error code for programmatic handling
          example: validation_error
        param:
          type: array
          description: Parameters that caused the error
          items:
            type: string
          example:
            - email
        action:
          type: string
          description: Suggested action to resolve the error
          example: Provide a valid email address in the 'email' field.
        docs:
          type: string
          format: uri
          description: Link to relevant documentation
          example: https://leadmagic.io/docs/api-reference/errors
        context:
          type: object
          description: Additional context specific to this error type
          additionalProperties: true
    ResponseMeta:
      type: object
      description: Metadata included in all responses
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for this request (use for debugging/support)
          example: ea6e3248-f4d2-437d-bca3-20881b529129
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the response was generated
          example: '2024-02-01T12:00:00.000Z'
        environment:
          type: string
          description: API environment (production, staging)
          example: production
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
        X-API-KEY, x-api-key all work).

````