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
2. 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:

⚠️

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

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

Optional Input Fields

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

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

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.