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

# Job Search

> Search jobs with occupation taxonomy, company, location, salary, tag, and title filters.

# Job Search

Search jobs with frontend-friendly filters. The `/v3/jobs/search` route resolves company domains, country codes, tags, occupation taxonomy, and title terms into normalized filter IDs before running a bounded query.

<Info>
  `POST /v3/jobs-search` is an alias for this endpoint with a simplified request shape. Use `/v3/jobs/search` for new integrations.
</Info>

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Metric         | Value                                                                                               |
    | -------------- | --------------------------------------------------------------------------------------------------- |
    | **Cost**       | **1 credit** per returned job/signal                                                                |
    | **No Results** | **FREE** when no jobs are returned                                                                  |
    | **Helpers**    | Companies, resolve, tags, titles, occupation taxonomy, locations, catalogs, and stats are **FREE**. |

    <Tip>
      Pre-resolve filters with [helpers](/docs/v1/reference/job-search-helpers) when your UI needs autocomplete. Free helpers + targeted search beat paying for resolve on every query.
    </Tip>
  </Tab>

  <Tab title="Rate Limits" icon="gauge">
    | Metric              | Value               |
    | ------------------- | ------------------- |
    | **Requests/Minute** | 300                 |
    | **Burst Capacity**  | \~5 requests/second |

    <Info>
      Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
    </Info>
  </Tab>
</Tabs>

***

## Quick Example

Start with `limit: 5` and `totalMode: "none"` while testing. Add facets, deep mode, salary, company, and taxonomy filters only after the base search works.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/jobs/search' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "titles": { "include": ["Software Engineer"] },
      "location": { "regions": ["North America"] },
      "postedWithin": 30,
      "limit": 5,
      "totalMode": "none"
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/jobs/search', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      titles: { include: ['Software Engineer'] },
      location: { regions: ['North America'] },
      postedWithin: 30,
      limit: 5,
      totalMode: 'none'
    })
  });
  const data = await response.json();
  console.log(`${data.signals.length} jobs`);
  ```

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

  response = requests.post(
      'https://api.leadmagic.io/v3/jobs/search',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'titles': {'include': ['Software Engineer']},
          'location': {'regions': ['North America']},
          'postedWithin': 30,
          'limit': 5,
          'totalMode': 'none'
      }
  )
  data = response.json()
  print(f"{len(data['signals'])} jobs")
  ```
</CodeGroup>

Use this fuller body when you want to combine all supported filters:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "titles": {
    "include": ["Software Engineer", "DevOps Engineer"],
    "exclude": ["Intern"],
    "vector": false
  },
  "occupationTaxonomy": {
    "level1": ["Engineering"],
    "level2": ["DevOps"],
    "level3": []
  },
  "companies": {
    "include": ["leadmagic.io"],
    "exclude": ["meta.com"],
    "ids": []
  },
  "location": {
    "countries": ["US", "GB"],
    "regions": [],
    "states": [],
    "cities": []
  },
  "tags": {
    "include": ["kubernetes", "terraform"],
    "exclude": []
  },
  "salary": {
    "min_usd": 120000,
    "max_usd": 280000
  },
  "seniority": ["SE", "EX"],
  "languages": ["en"],
  "hasRemote": true,
  "jobTypeIds": [],
  "industryIds": [],
  "companyTypeIds": [],
  "companySizeCodes": [],
  "postedAfter": "2026-05-01",
  "postedWithin": 30,
  "workModes": [1, 2],
  "includeAgencies": false,
  "includeCompany": true,
  "includeDescription": false,
  "includeFacets": false,
  "includeOccupationTaxonomy": true,
  "dryRun": false,
  "limit": 25,
  "totalMode": "capped",
  "mode": "fast",
  "autoResolve": true,
  "_query_budget_ms": 8000
}
```

## Request Parameters

<ParamField body="titles.include" type="string[]">
  Job title terms. Uses indexed title search.
</ParamField>

<ParamField body="titles.exclude" type="string[]">
  Title terms to exclude.
</ParamField>

<ParamField body="titles.vector" type="boolean" default="false">
  Request semantic title matching where available.
</ParamField>

<ParamField body="occupationTaxonomy.level1" type="string[] | integer[]">
  Broad occupation families. Results include `occupation_taxonomy.level1.id` and `occupation_taxonomy.level1.name`.
</ParamField>

<ParamField body="occupationTaxonomy.level2" type="string[] | integer[]">
  Mid-level occupation categories. Results include `occupation_taxonomy.level2.id` and `occupation_taxonomy.level2.name`.
</ParamField>

<ParamField body="occupationTaxonomy.level3" type="string[] | integer[]">
  Specific normalized job titles. Results include `occupation_taxonomy.level3.id` and `occupation_taxonomy.level3.name`.
</ParamField>

<ParamField body="companies.include" type="string[]">
  Company domains or names. Domains are resolved exactly; names use fuzzy helper matching.
</ParamField>

<ParamField body="companies.exclude" type="string[]">
  Company domains or names to exclude.
</ParamField>

<ParamField body="companies.ids" type="integer[]">
  Exact company IDs from helper responses.
</ParamField>

<ParamField body="location.countries" type="string[] | integer[]">
  Country codes, names, or IDs.
</ParamField>

<ParamField body="location.regions" type="string[] | integer[]">
  Region names or IDs.
</ParamField>

<ParamField body="location.states" type="string[] | integer[]">
  State or province names or IDs.
</ParamField>

<ParamField body="location.cities" type="string[] | integer[]">
  City names or IDs.
</ParamField>

<ParamField body="location.text" type="string">
  Free-text location. Use `mode: "deep"` when you need text location matching.
</ParamField>

<ParamField body="tags.include" type="string[] | integer[]">
  Tag names or IDs. Tags are resolved before search and can attach occupation taxonomy metadata.
</ParamField>

<ParamField body="tags.exclude" type="string[] | integer[]">
  Tag names or IDs to exclude.
</ParamField>

<ParamField body="salary.min_usd" type="integer">
  Minimum normalized USD salary.
</ParamField>

<ParamField body="salary.max_usd" type="integer">
  Maximum normalized USD salary.
</ParamField>

<ParamField body="seniority" type="string[]">
  Experience levels. Use `EN`, `MI`, `SE`, or `EX`.
</ParamField>

<ParamField body="languages" type="string[]">
  Two-letter language codes such as `en`, `de`, or `fr`.
</ParamField>

<ParamField body="hasRemote" type="boolean">
  Filter for jobs that support remote work.
</ParamField>

<ParamField body="workModes" type="integer[]">
  Work mode IDs. Allowed values are `1`, `2`, and `3`.
</ParamField>

<ParamField body="jobTypeIds" type="integer[]">
  Job type IDs from the job type catalog.
</ParamField>

<ParamField body="industryIds" type="integer[]">
  Company industry IDs.
</ParamField>

<ParamField body="companyTypeIds" type="integer[]">
  Company type IDs.
</ParamField>

<ParamField body="companySizeCodes" type="integer[]">
  Company size bucket codes.
</ParamField>

<ParamField body="postedAfter" type="string">
  Include jobs posted on or after a date in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="postedBefore" type="string">
  Include jobs posted before or on a date in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="postedWithin" type="integer">
  Include jobs posted within the last N days.
</ParamField>

<ParamField body="includeAgencies" type="boolean" default="false">
  Include staffing/recruiting agency jobs. Defaults to excluding agencies.
</ParamField>

<ParamField body="limit" type="integer" default="25">
  Number of jobs to return. Maximum is 50.
</ParamField>

<ParamField body="cursor" type="object">
  Cursor from `pagination.next_cursor` for the next page.
</ParamField>

<ParamField body="includeDescription" type="boolean" default="false">
  Include a short description snippet. Use only when you need description text.
</ParamField>

<ParamField body="includeCompany" type="boolean" default="true">
  Include the company object in each returned job.
</ParamField>

<ParamField body="includeFacets" type="boolean" default="false">
  Request facet metadata where available.
</ParamField>

<ParamField body="includeOccupationTaxonomy" type="boolean" default="true">
  Include normalized occupation taxonomy fields in each returned job.
</ParamField>

<ParamField body="totalMode" type="string" default="capped">
  Count mode. Use `none`, `capped`, or `exact`.
</ParamField>

<ParamField body="mode" type="string" default="fast">
  Query mode. Use `fast` by default. Use `deep` only for broader text matching.
</ParamField>

<ParamField body="dryRun" type="boolean" default="false">
  Validate/resolve the request without charging credits.
</ParamField>

<ParamField body="autoResolve" type="boolean" default="true">
  Resolve friendly strings like company domains, countries, tags, and occupation taxonomy values before search.
</ParamField>

<ParamField body="_query_budget_ms" type="integer">
  Optional internal query budget hint. Omit unless instructed by support.
</ParamField>

## Built-in Search Modes

Facets, semantic title matching, and deep matching are all part of `POST /v3/jobs/search`. You do not need separate endpoints.

| Capability              | Request field         | Use when                                                                                |
| ----------------------- | --------------------- | --------------------------------------------------------------------------------------- |
| Semantic title matching | `titles.vector: true` | Title intent is broader than exact keywords, such as `platform operations engineer`.    |
| Facets                  | `includeFacets: true` | Your UI needs filter counts or summary metadata alongside the returned jobs.            |
| Deep matching           | `mode: "deep"`        | Standard filters are too strict and you need broader matching across searchable fields. |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "titles": {
    "include": ["AI infrastructure engineer"],
    "vector": true
  },
  "tags": { "include": ["kubernetes", "machine learning"] },
  "location": { "countries": ["US"] },
  "includeFacets": true,
  "mode": "deep",
  "includeDescription": true,
  "limit": 10,
  "totalMode": "capped"
}
```

## Response

<ResponseField name="signals" type="object[]">
  Returned jobs/signals.
</ResponseField>

<ResponseField name="signals[].title" type="string">
  Job title.
</ResponseField>

<ResponseField name="signals[].company" type="object">
  Company object with `id`, `name`, `website_url`, and (when available) `linkedin_url`.
</ResponseField>

<ResponseField name="signals[].location" type="string | null">
  Display location string.
</ResponseField>

<ResponseField name="signals[].salary" type="object">
  Salary fields, including normalized USD ranges where available.
</ResponseField>

<ResponseField name="signals[].posted_at" type="string | null">
  Published timestamp/date for the job.
</ResponseField>

<ResponseField name="signals[].has_remote" type="boolean">
  Whether the job supports remote work.
</ResponseField>

<ResponseField name="signals[].application_url" type="string">
  Application URL for the job posting.
</ResponseField>

<ResponseField name="signals[].job_types" type="object[]">
  Job type metadata.
</ResponseField>

<ResponseField name="signals[].tags" type="object[]">
  Full tag metadata.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level1" type="object">
  Broad occupation taxonomy level with `id` and `name`.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level2" type="object">
  Mid-level occupation taxonomy level with `id` and `name`.
</ResponseField>

<ResponseField name="signals[].occupation_taxonomy.level3" type="object">
  Specific normalized title level with `id` and `name`.
</ResponseField>

<ResponseField name="total" type="integer">
  Total matching jobs (bounded by `totalMode`).
</ResponseField>

<ResponseField name="totalMode" type="string">
  Echoes the count mode used (`none`, `capped`, or `exact`).
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination wrapper with `next_cursor` for cursor-based pagination.
</ResponseField>

<ResponseField name="resolved" type="object">
  How input filters were resolved (only present when `autoResolve: true`).
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Non-fatal notes about fallback behavior, unsupported combinations, or broad matching.
</ResponseField>

<ResponseField name="metadata.query_path" type="string">
  Query path describing how the search was executed, such as `title+geo_bridge+vector_requested`.
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Finalized credits charged for this request.
</ResponseField>

### Example Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "signals": [
    {
      "title": "Full-Stack Software Engineer",
      "company": {
        "id": 102413,
        "name": "Example Company",
        "website_url": "https://example.com"
      },
      "occupation_taxonomy": {
        "level1": { "id": 1, "name": "Developer" },
        "level2": { "id": 20, "name": "Full-Stack Development" },
        "level3": { "id": 774, "name": "Full-stack software engineer" }
      }
    }
  ],
  "total": 3,
  "totalMode": "capped",
  "credits_consumed": 1
}
```

***

## Related endpoints

<CardGroup cols={2}>
  <Card title="Helpers" icon="wand-magic-sparkles" href="/docs/v1/reference/job-search-helpers">
    Resolve companies, tags, occupation taxonomy values, titles, locations, and catalogs.
  </Card>

  <Card title="Search Stats" icon="chart-simple" href="/docs/v1/reference/search-stats">
    See coverage, capabilities, and top dimensions across Jobs, Company, and People Search.
  </Card>

  <Card title="Job Search v2" icon="briefcase" href="/docs/v1/reference/jobs-finder">
    Previous jobs finder shape.
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v3/jobs/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/jobs/search:
    post:
      tags:
        - Jobs Data
      summary: Job Search
      description: >-
        Search jobs with title, occupation taxonomy, company, location, tag,
        salary, seniority, and date filters. The endpoint resolves friendly
        values into normalized filter IDs before searching.
      operationId: job-search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                titles:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        type: string
                    exclude:
                      type: array
                      items:
                        type: string
                    vector:
                      type: boolean
                      default: false
                occupationTaxonomy:
                  type: object
                  properties:
                    level1:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    level2:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    level3:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                companies:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        type: string
                    exclude:
                      type: array
                      items:
                        type: string
                    ids:
                      type: array
                      items:
                        type: integer
                location:
                  type: object
                  properties:
                    countries:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    regions:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    states:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    cities:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                tags:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    exclude:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                salary:
                  type: object
                  properties:
                    min_usd:
                      type: integer
                    max_usd:
                      type: integer
                seniority:
                  type: array
                  items:
                    type: string
                postedAfter:
                  type: string
                  format: date
                postedBefore:
                  type: string
                  format: date
                postedWithin:
                  type: integer
                  description: Include jobs posted within the last N days.
                languages:
                  type: array
                  items:
                    type: string
                hasRemote:
                  type: boolean
                jobTypeIds:
                  type: array
                  items:
                    type: integer
                industryIds:
                  type: array
                  items:
                    type: integer
                companyTypeIds:
                  type: array
                  items:
                    type: integer
                companySizeCodes:
                  type: array
                  items:
                    type: integer
                limit:
                  type: integer
                  default: 25
                  maximum: 50
                cursor:
                  type: object
                  description: Cursor from pagination.next_cursor.
                includeDescription:
                  type: boolean
                  default: false
                includeFacets:
                  type: boolean
                  default: false
                totalMode:
                  type: string
                  default: capped
                  enum:
                    - none
                    - capped
                    - exact
                mode:
                  type: string
                  default: fast
                  enum:
                    - fast
                    - deep
                autoResolve:
                  type: boolean
                  default: true
            example:
              titles:
                include:
                  - Engineer
                vector: false
              occupationTaxonomy:
                level2:
                  - DevOps
              location:
                countries:
                  - US
              postedWithin: 30
              limit: 5
              totalMode: none
              mode: fast
              autoResolve: true
      responses:
        '200':
          description: Job search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  signals:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                  totalMode:
                    type: string
                  pagination:
                    type: object
                  resolved:
                    type: object
                  credits_consumed:
                    type: integer
              example:
                signals:
                  - title: Full-Stack Software Engineer
                    company:
                      id: 102413
                      name: Example Company
                      website_url: https://example.com
                    occupation_taxonomy:
                      level1:
                        id: 1
                        name: Developer
                      level2:
                        id: 20
                        name: Full-Stack Development
                      level3:
                        id: 774
                        name: Full-stack software engineer
                total: 3
                totalMode: capped
                credits_consumed: 1
        '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).

````