> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reference - Job Posting Search API
## 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:
1. Using [Field Filters](#field-filters)
2. Using an [Elasticsearch query](#elasticsearch-query)
See the [quickstart guide](https://docs.peopledatalabs.com/docs/quickstart-job-posting-api) 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](https://www.peopledatalabs.com/job-posting-beta-sign-up).
## 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`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#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](https://docs.peopledatalabs.com/docs/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](#field-filters)** | Any filter fields (e.g. `company_website`, `title`, `location`, etc) | Field-based filtering. Multiple fields are combined with **AND** logic |
| **[Elasticsearch Query](#elasticsearch-query)** | `query` | Full Elasticsearch DSL query |
**Search Modes are Mutually Exclusive**
If the `query` parameter is provided, all [Field Filters](#field-filters) are **ignored**.
### **Field Filters**
See [Field Filter Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api#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](#elasticsearch-query)).
* 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`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#id) | PDL job posting ID | Exact | `+/vVJ9lbrec` |
| [`first_seen_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#first_seen_min) | Earliest date first seen | Range ≥ | `2026-01-01` |
| [`first_seen_max`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#first_seen_max) | Latest date first seen | Range ≤ | `2026-01-01` |
| [`deactivated_date_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#deactivated_date_min) | Earliest date deactivated | Range ≥ | `2026-01-01` |
| [`deactivated_date_max`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#deactivated_date_max) | Latest date deactivated | Range ≤ | `2026-01-01` |
| [`last_verified_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#last_verified_min) | Earliest date last verified | Range ≥ | `2026-01-01` |
| [`last_verified_max`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#last_verified_max) | Latest date last verified | Range ≤ | `2026-01-01` |
| [`title`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title) | Job title | Cleaned + Phrase | `data engineer` |
| [`title_class`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_class) | Job class | Canonical + Exact | `research_and_development` |
| [`title_role`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_role) | Job role | Canonical + Exact | `engineering` |
| [`title_sub_role`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_sub_role) | Job sub-role | Canonical + Exact | `data_engineering` |
| [`title_levels`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_levels) | Seniority level | Canonical + Exact | `senior` |
| [`company_id`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_id) | PDL company ID | Exact | `LGrXE14x4Kvzj2cbaeRUngOCTuJA` |
| [`company_name`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_name) | Company name | Cleaned + Exact | `anthropic` |
| [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) | Company website | Cleaned + Exact | `amazon.com` |
| [`company_profile`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_profile) | Company LinkedIn profile | Cleaned + Exact | `linkedin.com/company/amazon` |
| [`location`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#location) | Location (city, country, etc.) | Cleaned | `united states` |
| [`description`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#description) | Job description | Phrase | `LLM` |
| [`salary_range_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#salary_range_min) | Minimum salary | Range ≥ | `100000` |
| [`salary_range_max`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#salary_range_max) | Maximum salary | Range ≤ | `200000` |
| [`salary_currency`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#salary_currency) | Salary currency | Canonical + Cleaned + Exact | `usd` |
| [`salary_period`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#salary_period) | Salary period | Canonical + Exact | `annual` |
| [`remote_work_policy`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#remote_work_policy) | Remote policy | Canonical + Exact | `Remote` |
| [`inferred_skills`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#inferred_skills) | Extracted skills | Match | `javascript` |
| [`is_active`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#is_active) | Active / deactivated filter | Boolean | `true` |
### **Elasticsearch Query**
See [Elasticsearch Query Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api#elasticsearch-query-examples) for working examples of these queries.
Use `query` to send a raw [Elasticsearch(v7.7) query](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/query-dsl.html) to the Job Posting Search API:
* Supports ES queries like `bool`, `term`, `terms`, `match`, `range`, `exists` ([full list](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#query))
* Overrides all [Field Filters](#field-filters) if both are provided
* Limited to only fields that are mapped in the [Elasticsearch Index](https://docs.peopledatalabs.com/docs/elasticsearch-mapping-1)
| Parameter Name | Description | Example |
| :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
| [`query`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#query) | An [Elasticsearch (v7.7) query](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/query-dsl.html).
See our underlying [Elasticsearch Mapping](https://docs.peopledatalabs.com/docs/elasticsearch-mapping-1) for reference.
:warning: Using this field **disables and overrides** any [Field Filters](#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`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#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`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#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`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#pretty) | Whether the output should have [human-readable](http://jsonprettyprint.net/) indentation. | `false` | `true` |
| [`api_key`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#api_key) | Your secret API key (**Note**: you can also provide this in the request header instead, as shown on the [Authentication](https://docs.peopledatalabs.com/docs/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`](https://docs.peopledatalabs.com/docs/output-response-job-posting-api#status) | The response code. See [Errors & Status Codes](https://docs.peopledatalabs.com/docs/errors) for additional details. | `Integer` |
| [`data`](https://docs.peopledatalabs.com/docs/output-response-job-posting-api#data) | The job posting records that match the input request parameters. Records are sorted by most recent (based on `first_seen`). | `Array (Object)` |
| [`total`](https://docs.peopledatalabs.com/docs/output-response-job-posting-api#total) | The number of records from the job posting dataset matching the input request query. | `Integer` |
| [`scroll_token`](https://docs.peopledatalabs.com/docs/output-response-job-posting-api#scroll_token) | The scroll value, which you can use for further pagination. | `String` |
| [`dataset_version`](https://docs.peopledatalabs.com/docs/output-response-job-posting-api#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:
```json
{
"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](https://docs.peopledatalabs.com/docs/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](https://docs.peopledatalabs.com/docs/errors).