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

> Resolve companies, tags, occupation taxonomy values, titles, locations, and catalogs for Job Search.

# Job Search Helpers

Helpers let your frontend send friendly values (a company name, a tag, a country code) and get back canonical filter IDs before running [Job Search](/docs/v1/reference/job-search). Use them for autocomplete, filter builders, and preflight validation screens.

## Endpoint Details

<Tabs>
  <Tab title="Pricing" icon="coins">
    | Helper                                                                     | Credits  |
    | -------------------------------------------------------------------------- | -------- |
    | **Resolve** (this page)                                                    | **FREE** |
    | **Companies**                                                              | **FREE** |
    | **Tags**, **Titles**, **Occupation Taxonomy**, **Locations**, **Catalogs** | **FREE** |

    <Tip>
      The main [Job Search](/docs/v1/reference/job-search) route auto-resolves friendly values when `autoResolve: true`. Use these helpers directly when you want to show choices before search, or to avoid ambiguous fuzzy matches in production.
    </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

Resolve a draft search request into canonical filter IDs and labels:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v3/jobs/search/resolve' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "companies": { "include": ["leadmagic.io"] },
      "tags": { "include": ["kubernetes"] },
      "occupationTaxonomy": { "level2": ["DevOps"] },
      "location": { "countries": ["US"] },
      "titles": { "include": ["Site Reliability Engineer"] }
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.leadmagic.io/v3/jobs/search/resolve', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies: { include: ['leadmagic.io'] },
      tags: { include: ['kubernetes'] },
      occupationTaxonomy: { level2: ['DevOps'] },
      location: { countries: ['US'] },
      titles: { include: ['Site Reliability Engineer'] }
    })
  });
  const data = await response.json();
  console.log(data.resolved);
  ```

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

  response = requests.post(
      'https://api.leadmagic.io/v3/jobs/search/resolve',
      headers={'X-API-Key': 'YOUR_API_KEY'},
      json={
          'companies': {'include': ['leadmagic.io']},
          'tags': {'include': ['kubernetes']},
          'occupationTaxonomy': {'level2': ['DevOps']},
          'location': {'countries': ['US']},
          'titles': {'include': ['Site Reliability Engineer']}
      }
  )
  data = response.json()
  print(data['resolved'])
  ```
</CodeGroup>

***

## Autocomplete endpoints

Each autocomplete helper has its own page with full request/response docs and an interactive playground:

<CardGroup cols={2}>
  <Card title="Companies" icon="building" href="/docs/v1/reference/job-search-companies">
    `GET /v3/jobs/search/companies?q=leadmagic` — FREE
  </Card>

  <Card title="Tags" icon="tag" href="/docs/v1/reference/job-search-tags">
    `GET /v3/jobs/search/tags?q=kuber` — FREE
  </Card>

  <Card title="Titles" icon="briefcase" href="/docs/v1/reference/job-search-titles">
    `GET /v3/jobs/search/titles?q=devops engineer` — FREE
  </Card>

  <Card title="Occupation Taxonomy" icon="diagram-project" href="/docs/v1/reference/job-search-occupation-taxonomy">
    `GET /v3/jobs/search/occupation-taxonomy?q=DevOps&level=level2` — FREE
  </Card>

  <Card title="Locations" icon="location-dot" href="/docs/v1/reference/job-search-locations">
    `GET /v3/jobs/search/locations?type=country&q=United` — FREE
  </Card>

  <Card title="Catalogs" icon="list" href="/docs/v1/reference/job-search-catalogs">
    `GET /v3/jobs/search/catalogs` — FREE
  </Card>
</CardGroup>

***

## Resolve request parameters

The resolve endpoint accepts the same filter blocks as [Job Search](/docs/v1/reference/job-search), but instead of running a search it returns canonical IDs and labels for whatever you passed in.

<ParamField body="companies" type="object">
  Company filters: `include`, `exclude`, and `ids` arrays.
</ParamField>

<ParamField body="tags" type="object">
  Tag filters: `include` and `exclude` arrays of names or IDs.
</ParamField>

<ParamField body="occupationTaxonomy" type="object">
  Taxonomy filters: `level1`, `level2`, `level3` arrays of names or IDs.
</ParamField>

<ParamField body="location" type="object">
  Location filters: `countries`, `regions`, `states`, `cities`.
</ParamField>

<ParamField body="titles" type="object">
  Title filters: `include` and `exclude` arrays.
</ParamField>

***

## Response

<ResponseField name="resolved" type="object">
  Mirrors the request shape, with each input value replaced by `{ id, name, ... }` objects for canonical filter IDs.
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Any inputs that could not be resolved (typos, ambiguous matches, unsupported values).
</ResponseField>

<ResponseField name="credits_consumed" type="number">
  Always `1` for this helper.
</ResponseField>

<Tip>
  Cache resolve responses for the lifetime of a user session. The same friendly inputs will resolve to the same canonical IDs.
</Tip>

***

## Related endpoints

<CardGroup cols={2}>
  <Card title="Job Search" icon="briefcase" href="/docs/v1/reference/job-search">
    Run search with the resolved filter IDs.
  </Card>

  <Card title="Job Search" icon="briefcase" href="/docs/v1/reference/job-search">
    Discover which filter dimensions are searchable.
  </Card>

  <Card title="Job Search Catalogs" icon="list" href="/docs/v1/reference/job-search-catalogs">
    Full static filter catalogs (countries, job types, etc.).
  </Card>

  <Card title="Facets in Job Search" icon="filter" href="/docs/v1/reference/job-search">
    Get filter counts alongside search results.
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v3/jobs/search/resolve
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/resolve:
    post:
      tags:
        - Jobs Data
      summary: Resolve Job Search filters
      description: >-
        Resolve friendly companies, countries, tags, occupation taxonomy values,
        and titles into canonical filter IDs. This endpoint does not return job
        rows and is free.
      operationId: job-search-resolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companies:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        type: string
                    exclude:
                      type: array
                      items:
                        type: string
                    ids:
                      type: array
                      items:
                        type: integer
                tags:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    exclude:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                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
                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
                titles:
                  type: object
                  properties:
                    include:
                      type: array
                      items:
                        type: string
                    exclude:
                      type: array
                      items:
                        type: string
              example:
                companies:
                  include:
                    - leadmagic.io
                tags:
                  include:
                    - kubernetes
                occupationTaxonomy:
                  level2:
                    - DevOps
                location:
                  countries:
                    - US
                titles:
                  include:
                    - Site Reliability Engineer
      responses:
        '200':
          description: Resolved filters
components:
  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).

````