POST

jobs

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
}
'

import requests

url = "https://api.leadmagic.io/v3/jobs/search"

payload = {
    "titles": {
        "include": ["Engineer"],
        "vector": False
    },
    "occupationTaxonomy": { "level2": ["DevOps"] },
    "location": { "countries": ["US"] },
    "postedWithin": 30,
    "limit": 5,
    "totalMode": "none",
    "mode": "fast",
    "autoResolve": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    titles: {include: ['Engineer'], vector: false},
    occupationTaxonomy: {level2: ['DevOps']},
    location: {countries: ['US']},
    postedWithin: 30,
    limit: 5,
    totalMode: 'none',
    mode: 'fast',
    autoResolve: true
  })
};

fetch('https://api.leadmagic.io/v3/jobs/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/jobs/search"

	payload := strings.NewReader("{\n  \"titles\": {\n    \"include\": [\n      \"Engineer\"\n    ],\n    \"vector\": false\n  },\n  \"occupationTaxonomy\": {\n    \"level2\": [\n      \"DevOps\"\n    ]\n  },\n  \"location\": {\n    \"countries\": [\n      \"US\"\n    ]\n  },\n  \"postedWithin\": 30,\n  \"limit\": 5,\n  \"totalMode\": \"none\",\n  \"mode\": \"fast\",\n  \"autoResolve\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/jobs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'titles' => [
        'include' => [
                'Engineer'
        ],
        'vector' => false
    ],
    'occupationTaxonomy' => [
        'level2' => [
                'DevOps'
        ]
    ],
    'location' => [
        'countries' => [
                'US'
        ]
    ],
    'postedWithin' => 30,
    'limit' => 5,
    'totalMode' => 'none',
    'mode' => 'fast',
    'autoResolve' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $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
}

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

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

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

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

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

Pricing
Rate Limits

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.

Pre-resolve filters with helpers when your UI needs autocomplete. Free helpers + targeted search beat paying for resolve on every query.

Metric	Value
Requests/Minute	300
Burst Capacity	~5 requests/second

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

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`);

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")

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

string[]

Job title terms. Uses indexed title search.

string[]

Title terms to exclude.

boolean

default:"false"

Request semantic title matching where available.

string[] | integer[]

Broad occupation families. Results include occupation_taxonomy.level1.id and occupation_taxonomy.level1.name.

string[] | integer[]

Mid-level occupation categories. Results include occupation_taxonomy.level2.id and occupation_taxonomy.level2.name.

string[] | integer[]

Specific normalized job titles. Results include occupation_taxonomy.level3.id and occupation_taxonomy.level3.name.

string[]

Company domains or names. Domains are resolved exactly; names use fuzzy helper matching.

string[]

Company domains or names to exclude.

integer[]

Exact company IDs from helper responses.

string[] | integer[]

Country codes, names, or IDs.

string[] | integer[]

Region names or IDs.

string[] | integer[]

State or province names or IDs.

string[] | integer[]

City names or IDs.

string

Free-text location. Use mode: "deep" when you need text location matching.

string[] | integer[]

Tag names or IDs. Tags are resolved before search and can attach occupation taxonomy metadata.

string[] | integer[]

Tag names or IDs to exclude.

integer

Minimum normalized USD salary.

integer

Maximum normalized USD salary.

string[]

Experience levels. Use EN, MI, SE, or EX.

string[]

Two-letter language codes such as en, de, or fr.

boolean

Filter for jobs that support remote work.

integer[]

Work mode IDs. Allowed values are 1, 2, and 3.

integer[]

Job type IDs from the job type catalog.

integer[]

Company industry IDs.

integer[]

Company type IDs.

integer[]

Company size bucket codes.

string

Include jobs posted on or after a date in YYYY-MM-DD format.

string

Include jobs posted before or on a date in YYYY-MM-DD format.

integer

Include jobs posted within the last N days.

boolean

default:"false"

Include staffing/recruiting agency jobs. Defaults to excluding agencies.

integer

default:"25"

Number of jobs to return. Maximum is 50.

object

Cursor from pagination.next_cursor for the next page.

boolean

default:"false"

Include a short description snippet. Use only when you need description text.

boolean

default:"true"

Include the company object in each returned job.

boolean

default:"false"

Request facet metadata where available.

boolean

default:"true"

Include normalized occupation taxonomy fields in each returned job.

string

default:"capped"

Count mode. Use none, capped, or exact.

string

default:"fast"

Query mode. Use fast by default. Use deep only for broader text matching.

boolean

default:"false"

Validate/resolve the request without charging credits.

boolean

default:"true"

Resolve friendly strings like company domains, countries, tags, and occupation taxonomy values before search.

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.

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.

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

object[]

Returned jobs/signals.

string

Job title.

object

Company object with id, name, website_url, and (when available) linkedin_url.

string | null

Display location string.

object

Salary fields, including normalized USD ranges where available.

string | null

Published timestamp/date for the job.

boolean

Whether the job supports remote work.

string

Application URL for the job posting.

object[]

Job type metadata.

object[]

Full tag metadata.

object

Broad occupation taxonomy level with id and name.

object

Mid-level occupation taxonomy level with id and name.

object

Specific normalized title level with id and name.

integer

Total matching jobs (bounded by totalMode).

string

Echoes the count mode used (none, capped, or exact).

object

Pagination wrapper with next_cursor for cursor-based pagination.

object

How input filters were resolved (only present when autoResolve: true).

string[]

Non-fatal notes about fallback behavior, unsupported combinations, or broad matching.

string

Query path describing how the search was executed, such as title+geo_bridge+vector_requested.

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

Show child attributes

occupationTaxonomy

object

Show child attributes

companies

object

Show child attributes

location

object

Show child attributes

Response

Job search results

signals

object[]

total

integer

totalMode

string

pagination

object

resolved

object

credits_consumed

integer

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
}
'

import requests

url = "https://api.leadmagic.io/v3/jobs/search"

payload = {
    "titles": {
        "include": ["Engineer"],
        "vector": False
    },
    "occupationTaxonomy": { "level2": ["DevOps"] },
    "location": { "countries": ["US"] },
    "postedWithin": 30,
    "limit": 5,
    "totalMode": "none",
    "mode": "fast",
    "autoResolve": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    titles: {include: ['Engineer'], vector: false},
    occupationTaxonomy: {level2: ['DevOps']},
    location: {countries: ['US']},
    postedWithin: 30,
    limit: 5,
    totalMode: 'none',
    mode: 'fast',
    autoResolve: true
  })
};

fetch('https://api.leadmagic.io/v3/jobs/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v3/jobs/search"

	payload := strings.NewReader("{\n  \"titles\": {\n    \"include\": [\n      \"Engineer\"\n    ],\n    \"vector\": false\n  },\n  \"occupationTaxonomy\": {\n    \"level2\": [\n      \"DevOps\"\n    ]\n  },\n  \"location\": {\n    \"countries\": [\n      \"US\"\n    ]\n  },\n  \"postedWithin\": 30,\n  \"limit\": 5,\n  \"totalMode\": \"none\",\n  \"mode\": \"fast\",\n  \"autoResolve\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v3/jobs/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'titles' => [
        'include' => [
                'Engineer'
        ],
        'vector' => false
    ],
    'occupationTaxonomy' => [
        'level2' => [
                'DevOps'
        ]
    ],
    'location' => [
        'countries' => [
                'US'
        ]
    ],
    'postedWithin' => 30,
    'limit' => 5,
    'totalMode' => 'none',
    'mode' => 'fast',
    'autoResolve' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $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
}

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

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

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

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

Get Started

API Endpoints

MCP Server

CLI

Job Search

Job Search

Endpoint Details

Quick Example

Request Parameters

Built-in Search Modes

Response

Example Response

Helpers

Search Stats

Job Search v2

Authorizations

Body

Response

​Job Search

​Endpoint Details

​Quick Example

​Request Parameters

​Built-in Search Modes

​Response

​Example Response

​Related endpoints

Helpers

Search Stats

Job Search v2

Authorizations

Body

Response

Job Search

Endpoint Details

Quick Example

Request Parameters

Built-in Search Modes

Response

Example Response

Related endpoints