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.
Responses never include logo or company_logo. Company objects include IDs, names, website URLs, and LinkedIn URLs only when full rows are returned.

​
Pricing

ModeCredits
Full search1 credit per returned job/signal
No returned jobs0 credits
Helpers, catalogs, stats0 credits

​
Example

Use this minimal body in the playground first. It is fast, low-risk, and returns a small page: 
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": ["Engineer"] },
    "location": { "countries": ["US"] },
    "occupationTaxonomy": { "level2": ["DevOps"] },
    "postedWithin": 30,
    "limit": 5,
    "totalMode": "none"
  }'
Start with limit: 5 and totalMode: "none" while testing. Add facets, deep mode, salary, company, and taxonomy filters only after the base search works.
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": ["stripe.com", "datadoghq.com"],
    "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",
  "limit": 25,
  "totalMode": "capped",
  "mode": "fast",
  "autoResolve": true
}

​
Request fields

​
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. The response includes a warning if the request falls back to the standard title path.
​
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.
​
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.
​
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.
​
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.
​
includeFacets
boolean
default:"false"
Request facet metadata where available.
​
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.
​
autoResolve
boolean
default:"true"
Resolve friendly strings like company domains, countries, tags, and occupation taxonomy values before search.

​
Response Shape

​
signals
array
Returned jobs/signals.
​
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.
​
pagination.next_cursor
object
Cursor for the next page. Use this instead of deep offset pagination.

Vector

Use semantic title matching for broader title intent.

Facets

Request filter summary metadata with results.

Deep

Expand matching when standard filters are too strict.

Helpers

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

Stats

See jobs data freshness and searchable dimension counts.

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