Reference

The Job Posting Search API can be used to search and retrieve full job posting records from our complete Job Posting Dataset. The API offers two ways to query:

Using Field Filters
Using an Elasticsearch query

See the quickstart guide for an easy to follow tutorial for using this endpoint.

Endpoint

The endpoint for the Job Posting Search API is https://api.peopledatalabs.com/v5/job_posting/search.

Access

The Job Posting Search API is currently in Beta, and is available to all customers. To request access, please reach out to your customer success team or contact us.

Billing

The Job Posting Search API consumes 1 credit per record retrieved. Each job posting record in the data array in the response counts as one credit against your credit limit.

For example, a query that returns 10 job posting records will consume 10 credits.

📘
Controlling the Number of Credits Used Per API Call
You can use the size parameter to limit the number of records returned in a query (and therefore control the number of credits consumed by your API calls).

Authentication

See Authentication to learn how to authenticate input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.

Rate Limiting

The current default rate limit is 20 requests per minute.

Input Parameters

Required: Search Mode

The Job Posting Search API requires exactly one of the following:

Mode	Input Parameter(s)	Description
Field Filters	Any filter fields (e.g. `company_website`, `title`, `location`, etc)	Field-based filtering. Multiple fields are combined with AND logic
Elasticsearch Query	`query`	Full Elasticsearch DSL query

⚠️
Search Modes are Mutually Exclusive
If the query parameter is provided, all Field Filters are ignored.

Field Filters

📘
See Field Filter Examples for working examples of these built-in filters.

Field Filters are the simplest way to search for job posting records through the Job Posting Search API (as compared to Elasticsearch Queries).

Each filter maps to predefined search behavior on a specific field (or fields).
Multiple filters are combined using AND logic
Each field has fixed matching and input standardization behavior

Example: company_website=peopledatalabs.com AND title=data engineer

📘
Behavior Legend

Exact = exact match

Phrase = case-insensitive, supports substring match

Match = case-insensitive, allows partial string matching

Cleaned = input is normalized via PDL cleaners before matching

Canonical = must match a predefined set of values

Range ≥ / ≤ = numeric comparison against stored values

Boolean = filters based on true / false behavior

Field Filter	Description	Behavior	Example
`id`	PDL job posting ID	Exact	`+/vVJ9lbrec`
`first_seen_min`	Earliest date first seen	Range ≥	`2026-01-01`
`first_seen_max`	Latest date first seen	Range ≤	`2026-01-01`
`deactivated_date_min`	Earliest date deactivated	Range ≥	`2026-01-01`
`deactivated_date_max`	Latest date deactivated	Range ≤	`2026-01-01`
`last_verified_min`	Earliest date last verified	Range ≥	`2026-01-01`
`last_verified_max`	Latest date last verified	Range ≤	`2026-01-01`
`title`	Job title	Cleaned + Phrase	`data engineer`
`title_class`	Job class	Canonical + Exact	`research_and_development`
`title_role`	Job role	Canonical + Exact	`engineering`
`title_sub_role`	Job sub-role	Canonical + Exact	`data_engineering`
`title_levels`	Seniority level	Canonical + Exact	`senior`
`company_id`	PDL company ID	Exact	`LGrXE14x4Kvzj2cbaeRUngOCTuJA`
`company_name`	Company name	Cleaned + Exact	`anthropic`
`company_website`	Company website	Cleaned + Exact	`amazon.com`
`company_profile`	Company LinkedIn profile	Cleaned + Exact	`linkedin.com/company/amazon`
`location`	Location (city, country, etc.)	Cleaned	`united states`
`description`	Job description	Phrase	`LLM`
`salary_range_min`	Minimum salary	Range ≥	`100000`
`salary_range_max`	Maximum salary	Range ≤	`200000`
`salary_currency`	Salary currency	Canonical + Cleaned + Exact	`usd`
`salary_period`	Salary period	Canonical + Exact	`annual`
`remote_work_policy`	Remote policy	Canonical + Exact	`Remote`
`inferred_skills`	Extracted skills	Match	`javascript`
`is_active`	Active / deactivated filter	Boolean	`true`

Elasticsearch Query

📘
See Elasticsearch Query Examples for working examples of these queries.

Use query to send a raw Elasticsearch(v7.7) query to the Job Posting Search API:

Supports ES queries like bool, term, terms, match, range, exists (full list)
Overrides all Field Filters if both are provided
Limited to only fields that are mapped in the Elasticsearch Index

Parameter Name	Description	Example
`query`	An Elasticsearch (v7.7) query. See our underlying Elasticsearch Mapping for reference. ⚠️ Using this field disables and overrides any Field Filters provided in your API request.	`{"match": {"title": "developer"}}`

Optional Input Fields

These are additional input parameters you can provide to the Job Posting Search API.

Parameter Name	Description	Default	Example
`size`	The batch size or the maximum number of matched records to return for this query if they exist. Must be between `1` and `100`.	`10`	`100`
`scroll_token`	An offset key for paginating between batches. Each Job Posting Search API response returns a `scroll_token`, which you can use to fetch the next batch (`size`) records.	`None`	`WzE3NzY0NzA0MDAwMDA`
`pretty`	Whether the output should have human-readable indentation.	`false`	`true`
`api_key`	Your secret API key (Note: you can also provide this in the request header instead, as shown on the Authentication page).

Output Response

The Job Posting Search API returns an HTTP response code of 200 for any valid request with at least one matching result. Each record in the response counts as a single credit against your total credit limit.

Response Fields

Field	Description	Type
`status`	The response code. See Errors & Status Codes for additional details.	`Integer`
`data`	The job posting records that match the input request parameters. Records are sorted by most recent (based on `first_seen`).	`Array (Object)`
`total`	The number of records from the job posting dataset matching the input request query.	`Integer`
`scroll_token`	The scroll value, which you can use for further pagination.	`String`
`dataset_version`	The current release version of the data in this API response.	`34.0`

Response Data Structure

The response from the Job Posting Search API will be in this format:

{
    "status": 200,
    "data": [
        {
          "id": "mCxejm1sT+Q",
          "first_seen": "2025-02-27",
          "last_verified": "2025-02-27",
          ... // Rest of the details for this Job Posting record
        },
        ... // Rest of the Job Posting records in the response
    ],
    "total": 6,
    "scroll_token": "13.312621$543927",
    "dataset_version": "34.0"
}

See Example Job Posting Record for a full example of the fields included in the data object.

Errors

If your request encounters an error, it will return an Error Response.

No credits are consumed for API calls that return an error or non-200 status code.

For additional details, see our page on Errors & Status Codes.