> ## 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
> LeadMagic's Jobs Finder
# Job Search
This is the legacy v1 jobs endpoint (`POST /v1/jobs/jobs-finder`). For new integrations, use the [Job Search](/docs/v1/reference/job-search) endpoint backed by `/v3/jobs/search`, which supports occupation taxonomy, helper resolution, vector search, and richer filters. This page remains available for existing integrations.
Search and filter job listings across companies with a straightforward page-based jobs search.
## Endpoint Details
| Metric | Value |
| -------------- | ----------------------------- |
| **Cost** | **1 credit** per job returned |
| **No Results** | **FREE** if no jobs found |
**Hiring Signals:** Companies with open positions are actively investing and growing - perfect timing for sales outreach.
### Per-Endpoint Limit
| Metric | Value |
| ------------------- | ------------------- |
| **Requests/Minute** | 100 |
| **Burst Capacity** | \~2 requests/second |
Rate limits are subject to change. Custom rate limits are available on enterprise plans — [contact us](mailto:support@leadmagic.io).
***
## Quick Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v1/jobs/jobs-finder' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"job_title": "Sales Director",
"country_id": "US",
"experience_level": "senior",
"has_remote": true,
"posted_within": 14,
"page": 1,
"per_page": 20
}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v1/jobs/jobs-finder', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
job_title: 'Sales Director',
country_id: 'US',
experience_level: 'senior',
has_remote: true,
posted_within: 14,
page: 1,
per_page: 20
})
});
const { results, total_count } = await response.json();
console.log(`Found ${total_count} jobs`);
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
response = requests.post(
'https://api.leadmagic.io/v1/jobs/jobs-finder',
headers={'X-API-Key': 'YOUR_API_KEY'},
json={
'job_title': 'Sales Director',
'country_id': 'US',
'experience_level': 'senior',
'has_remote': True,
'posted_within': 14,
'page': 1,
'per_page': 20
}
)
data = response.json()
print(f"Found {data['total_count']} jobs")
```
***
## Request Parameters
All fields are optional - combine them to filter results:
Company name to search
Company domain
Company type ID (see [Company Types](/docs/v1/reference/job-company-types))
Industry ID (see [Industries](/docs/v1/reference/job-industry))
Minimum company size
Maximum company size
Title keyword search
Description keyword search
Level: `entry`, `mid`, `senior`, `executive`
Job type ID (see [Job Types](/docs/v1/reference/job-types))
Filter for remote work options
City or region name
Specific city
Country code (US, UK, etc.) - see [Countries](/docs/v1/reference/job-country)
State/region ID (see [Regions](/docs/v1/reference/job-regions))
Days since posting (e.g., 14 for last 2 weeks)
Posted on or after (YYYY-MM-DD)
Posted on or before (YYYY-MM-DD)
Page number
Results per page (max: 50)
***
## Response
Total jobs matching filters
Current page
Results per page
Total pages available
Credits used (1 per job returned)
Array of job listings
### Job Object
| Field | Type | Description |
| ------------------------- | ------- | ----------------------------- |
| `title` | string | Job title |
| `company.name` | string | Company name |
| `company.website_url` | string | Company website |
| `company.b2b_profile_url` | string | Company profile URL |
| `location` | string | Job location |
| `types` | array | Job types (Full-time, etc.) |
| `experience_level` | string | Entry, Mid, Senior, Executive |
| `has_remote` | boolean | Remote work available |
| `published` | string | Posted date |
| `description` | string | Full job description |
| `application_url` | string | Apply link |
### Example Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"total_count": 142,
"page": 1,
"per_page": 20,
"total_pages": 8,
"credits_consumed": 20,
"results": [
{
"title": "VP of Sales",
"company": {
"name": "LeadMagic",
"website_url": "https://leadmagic.io",
"b2b_profile_url": "https://linkedin.com/company/leadmagichq"
},
"location": "San Francisco, CA",
"types": ["Full-time"],
"experience_level": "Executive",
"has_remote": true,
"published": "2026-01-28",
"description": "Leading enterprise sales team...",
"application_url": "https://leadmagic.io/careers/vp-sales"
}
]
}
```
***
## Reference Endpoints
Get valid filter IDs from these endpoints (all free, no credits):
Get country IDs
Get region/state IDs
Get job type IDs
Get company type IDs
Get industry IDs
***
## Best Practices
Use `posted_within: 14` to focus on companies actively hiring right now.
Companies hiring for your buyer's role have active budget and immediate need.
After finding hiring companies, use [Role Finder](/docs/v1/reference/role-finder) to find decision makers.
Start with `per_page: 20` and paginate. Don't request large pages you won't use.
***
## Use Cases
Companies hiring for your buyer persona have active budget.
Find companies hiring roles that need your product.
Analyze hiring trends across industries.
Discover open positions matching candidate profiles.
## OpenAPI
````yaml post /v1/jobs/jobs-finder
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:
/v1/jobs/jobs-finder:
post:
tags:
- Jobs Data
summary: Jobs Finder
description: LeadMagic's Jobs Finder
operationId: jobs-finder
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
company_name:
type: string
description: Provide the Company Name. (Optional)
example: Clay
company_website:
type: string
description: Provide the Company Website. (Optional)
example: clay.com
job_title:
type: string
description: Provide the Job Title.
example: RevOps Engineer
location:
type: string
description: Location of the job
example: United States
experience_level:
type: string
description: >-
Indicates the required experience level for the job. Choose
"entry" for Entry Level, "mid" for Mid Level, "senior" for
Senior Level, or "executive" for Executive Level. If not
specified, jobs from all experience levels will be included.
example: senior
job_description:
type: string
description: >-
Filters jobs based on specific keywords or phrases found in
the job description.
example: leadmagic
country_id:
type: string
description: >-
Filter jobs by country code, such as US or GB. Use the
country helper for supported values.
example: US
region_id:
type: integer
description: Filter jobs by region ID.
example: 5
job_type_id:
type: integer
description: Filter jobs by job type ID.
example: 1
company_type_id:
type: integer
description: Filter jobs by company type ID.
example: 1
company_industry_id:
type: integer
description: Filter jobs by company industry ID.
example: 7
min_employees:
type: integer
description: Minimum number of employees
example: 51
max_employees:
type: integer
description: Maximum number of employees
example: 10000
has_remote:
type: boolean
description: >-
Determines whether the jobs offer remote work options. Set
to true to include remote-only listings, or false to include
non-remote listings.
example: true
posted_within:
type: integer
description: Specify the number of days within which the job was posted.
example: 30
posted_after:
type: string
format: date
description: >-
Filters jobs posted on or after a specific date. Use the
format YYYY-MM-DD.
example: '2026-05-01'
posted_before:
type: string
format: date
description: >-
Filters jobs posted on or before a specific date. Use the
format YYYY-MM-DD.
example: '2026-05-15'
page:
type: integer
description: Page number
default: 1
per_page:
type: integer
description: >-
Provide number of results needed per page. (Maximum per_page
can be 50)
default: 20
example:
company_website: clay.com
job_title: RevOps Engineer
country_id: US
has_remote: true
posted_within: 30
page: 1
per_page: 20
responses:
'200':
description: Successful response with job listings
content:
application/json:
schema:
type: object
properties:
total_count:
type: integer
default: 0
page:
type: integer
default: 0
per_page:
type: integer
default: 0
total_pages:
type: integer
default: 0
credits_consumed:
type: integer
default: 0
results:
type: array
items:
type: object
properties:
company:
type: object
properties:
name:
type: string
example: LeadMagic
website_url:
type: string
example: https://leadmagic.io
b2b_profile_url:
type: string
nullable: true
example: leadmagichq
twitter_handle:
type: string
nullable: true
example: leadmagichq
github_url:
type: string
nullable: true
example: https://github.com/leadmagic
title:
type: string
location:
type: string
types:
type: array
items:
type: object
properties:
id:
type: integer
default: 0
name:
type: string
cities:
type: array
items:
type: object
properties:
geonameid:
type: integer
default: 0
asciiname:
type: string
name:
type: string
country:
type: object
timezone:
type: string
latitude:
type: string
longitude:
type: string
countries:
type: array
items:
type: object
properties:
code:
type: string
name:
type: string
region:
type: object
regions:
type: array
items:
type: object
properties:
id:
type: integer
default: 0
name:
type: string
has_remote:
type: boolean
default: true
published:
type: string
description:
type: string
application_url:
type: string
language:
type: string
nullable: true
clearance_required:
type: boolean
default: true
salary_min:
type: string
nullable: true
salary_max:
type: string
nullable: true
salary_currency:
type: string
nullable: true
experience_level:
type: string
example:
total_count: 50
page: 1
per_page: 20
total_pages: 3
credits_consumed: 20
results:
- company:
name: LeadMagic
website_url: https://leadmagic.io
b2b_profile_url: leadmagichq
twitter_handle: leadmagichq
github_url: https://github.com/leadmagic
title: Senior Software Engineer
location: San Jose, San José, Costa Rica
types:
- id: 1
name: Full Time
cities:
- geonameid: 3621849
asciiname: San Jose
name: San José
country:
code: CR
name: Costa Rica
region:
id: 5
name: North America
timezone: America/Costa_Rica
latitude: '9.93333'
longitude: '-84.08333'
countries:
- code: CR
name: Costa Rica
region:
id: 5
name: North America
regions:
- id: 5
name: North America
has_remote: false
published: '2024-07-23T15:25:00Z'
description: ''
application_url: https://leadmagic.io/careers
language: en
clearance_required: false
salary_min: null
salary_max: null
salary_currency: null
experience_level: Senior Level
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
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'
InternalServerError:
description: >
Internal Server Error - Something went wrong on our end.
**Action required:** Wait 30 seconds and retry. If the problem persists,
contact support@leadmagic.io
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerError'
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'
InternalServerError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/INTERNAL_ERROR
title: >-
Something went wrong on our end. Our team has been notified and is
investigating.
status: 500
code: INTERNAL_ERROR
detail: >-
This is a temporary server error. The issue has been automatically
reported to our team.
action: >-
Wait 30 seconds and retry your request. If the problem persists,
contact support@leadmagic.io
docs: https://leadmagic.io/docs/api-reference/errors
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).
````