Skip to main content
POST
/
v3
/
jobs
/
search
Job Search
curl --request POST \
  --url https://api.leadmagic.io/v3/jobs/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "titles": {
    "include": [
      "Engineer"
    ],
    "vector": false
  },
  "occupationTaxonomy": {
    "level2": [
      "DevOps"
    ]
  },
  "location": {
    "countries": [
      "US"
    ]
  },
  "postedWithin": 30,
  "limit": 5,
  "totalMode": "none",
  "mode": "fast",
  "autoResolve": true
}
'
{
  "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
}

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 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.
POST /v3/jobs-search is an alias for this endpoint with a simplified request shape. Use /v3/jobs/search for new integrations.

​
Endpoint Details

MetricValue
Cost1 credit per returned job/signal
No ResultsFREE when no jobs are returned
HelpersCompanies, resolve, tags, titles, occupation taxonomy, locations, catalogs, and stats are FREE.
Pre-resolve filters with helpers when your UI needs autocomplete. Free helpers + targeted search beat paying for resolve on every query.

​
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. 
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"
  }'
Use this fuller body when you want to combine all supported filters: 
{
  "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

​
titles.include
string[]
Job title terms. Uses indexed title search.
​
titles.exclude
string[]
Title terms to exclude.
​
titles.vector
boolean
default:"false"
Request semantic title matching where available.
​
occupationTaxonomy.level1
string[] | integer[]
Broad occupation families. Results include occupation_taxonomy.level1.id and occupation_taxonomy.level1.name.
​
occupationTaxonomy.level2
string[] | integer[]
Mid-level occupation categories. Results include occupation_taxonomy.level2.id and occupation_taxonomy.level2.name.
​
occupationTaxonomy.level3
string[] | integer[]
Specific normalized job titles. Results include occupation_taxonomy.level3.id and occupation_taxonomy.level3.name.
​
companies.include
string[]
Company domains or names. Domains are resolved exactly; names use fuzzy helper matching.
​
companies.exclude
string[]
Company domains or names to exclude.
​
companies.ids
integer[]
Exact company IDs from helper responses.
​
location.countries
string[] | integer[]
Country codes, names, or IDs.
​
location.regions
string[] | integer[]
Region names or IDs.
​
location.states
string[] | integer[]
State or province names or IDs.
​
location.cities
string[] | integer[]
City names or IDs.
​
location.text
string
Free-text location. Use mode: "deep" when you need text location matching.
​
tags.include
string[] | integer[]
Tag names or IDs. Tags are resolved before search and can attach occupation taxonomy metadata.
​
tags.exclude
string[] | integer[]
Tag names or IDs to exclude.
​
salary.min_usd
integer
Minimum normalized USD salary.
​
salary.max_usd
integer
Maximum normalized USD salary.
​
seniority
string[]
Experience levels. Use EN, MI, SE, or EX.
​
languages
string[]
Two-letter language codes such as en, de, or fr.
​
hasRemote
boolean
Filter for jobs that support remote work.
​
workModes
integer[]
Work mode IDs. Allowed values are 1, 2, and 3.
​
jobTypeIds
integer[]
Job type IDs from the job type catalog.
​
industryIds
integer[]
Company industry IDs.
​
companyTypeIds
integer[]
Company type IDs.
​
companySizeCodes
integer[]
Company size bucket codes.
​
postedAfter
string
Include jobs posted on or after a date in YYYY-MM-DD format.
​
postedBefore
string
Include jobs posted before or on a date in YYYY-MM-DD format.
​
postedWithin
integer
Include jobs posted within the last N days.
​
includeAgencies
boolean
default:"false"
Include staffing/recruiting agency jobs. Defaults to excluding agencies.
​
limit
integer
default:"25"
Number of jobs to return. Maximum is 50.
​
cursor
object
Cursor from pagination.next_cursor for the next page.
​
includeDescription
boolean
default:"false"
Include a short description snippet. Use only when you need description text.
​
includeCompany
boolean
default:"true"
Include the company object in each returned job.
​
includeFacets
boolean
default:"false"
Request facet metadata where available.
​
includeOccupationTaxonomy
boolean
default:"true"
Include normalized occupation taxonomy fields in each returned job.
​
totalMode
string
default:"capped"
Count mode. Use none, capped, or exact.
​
mode
string
default:"fast"
Query mode. Use fast by default. Use deep only for broader text matching.
​
dryRun
boolean
default:"false"
Validate/resolve the request without charging credits.
​
autoResolve
boolean
default:"true"
Resolve friendly strings like company domains, countries, tags, and occupation taxonomy values before search.
​
_query_budget_ms
integer
Optional internal query budget hint. Omit unless instructed by support.

​
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.
CapabilityRequest fieldUse when
Semantic title matchingtitles.vector: trueTitle intent is broader than exact keywords, such as platform operations engineer.
FacetsincludeFacets: trueYour UI needs filter counts or summary metadata alongside the returned jobs.
Deep matchingmode: "deep"Standard filters are too strict and you need broader matching across searchable fields.
{
  "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

​
signals
object[]
Returned jobs/signals.
​
signals[].title
string
Job title.
​
signals[].company
object
Company object with id, name, website_url, and (when available) linkedin_url.
​
signals[].location
string | null
Display location string.
​
signals[].salary
object
Salary fields, including normalized USD ranges where available.
​
signals[].posted_at
string | null
Published timestamp/date for the job.
​
signals[].has_remote
boolean
Whether the job supports remote work.
​
signals[].application_url
string
Application URL for the job posting.
​
signals[].job_types
object[]
Job type metadata.
​
signals[].tags
object[]
Full tag metadata.
​
signals[].occupation_taxonomy.level1
object
Broad occupation taxonomy level with id and name.
​
signals[].occupation_taxonomy.level2
object
Mid-level occupation taxonomy level with id and name.
​
signals[].occupation_taxonomy.level3
object
Specific normalized title level with id and name.
​
total
integer
Total matching jobs (bounded by totalMode).
​
totalMode
string
Echoes the count mode used (none, capped, or exact).
​
pagination
object
Pagination wrapper with next_cursor for cursor-based pagination.
​
resolved
object
How input filters were resolved (only present when autoResolve: true).
​
warnings
string[]
Non-fatal notes about fallback behavior, unsupported combinations, or broad matching.
​
metadata.query_path
string
Query path describing how the search was executed, such as title+geo_bridge+vector_requested.
​
credits_consumed
number
Finalized credits charged for this request.

​
Example Response

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

Helpers

Resolve companies, tags, occupation taxonomy values, titles, locations, and catalogs.

Search Stats

See coverage, capabilities, and top dimensions across Jobs, Company, and People Search.

Job Search v2

Previous jobs finder shape.

Authorizations

​
X-API-Key
string
header
required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Body

application/json
​
titles
object
​
occupationTaxonomy
object
​
companies
object
​
location
object
​
tags
object
​
salary
object
​
seniority
string[]
​
postedAfter
string<date>
​
postedBefore
string<date>
​
postedWithin
integer

Include jobs posted within the last N days.

​
languages
string[]
​
hasRemote
boolean
​
jobTypeIds
integer[]
​
industryIds
integer[]
​
companyTypeIds
integer[]
​
companySizeCodes
integer[]
​
limit
integer
default:25
Required range: x <= 50
​
cursor
object

Cursor from pagination.next_cursor.

​
includeDescription
boolean
default:false
​
includeFacets
boolean
default:false
​
totalMode
enum<string>
default:capped
Available options:
none,
capped,
exact
​
mode
enum<string>
default:fast
Available options:
fast,
deep
​
autoResolve
boolean
default:true

Response

Job search results

​
signals
object[]
​
total
integer
​
totalMode
string
​
pagination
object
​
resolved
object
​
credits_consumed
integer