> ## 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.

# Quickstart - Job Posting Search API

## :zap: Quickstart

This guide walks through how to make your first Job Posting Search API request from start to finish. :tada:

You can copy the examples below and run them as-is after adding your API key.

***

## :reminder\_ribbon: Before You Start

<Steps name="quickstart">
  <Step title="Make sure you have access">
    The Job Posting Search API is currently in **beta**.

    To use it, you need:

    * An active PDL API key
    * Beta access enabled for the Job Posting Search API on that key

    Existing customers can request access through their customer account team. If you are new to PDL, you can [meet with our team to join the beta here](https://www.peopledatalabs.com/job-posting-beta-sign-up).

    As a reminder, you can find your API key in the [PDL dashboard](https://dashboard.peopledatalabs.com/).
  </Step>

  <Step title="Know what this endpoint does">
    The Job Posting Search API lets you search the full PDL Job Posting Dataset and return complete job posting records.

    Endpoint: `https://api.peopledatalabs.com/v5/job_posting/search`

    There are two ways to search:

    1. [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) (parameterized input fields)
    2. An [Elasticsearch query](https://docs.peopledatalabs.com/docs/reference-job-posting-api#elasticsearch-query)

    This quickstart uses [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) because they are a clear and practical way to get started.
  </Step>
</Steps>

***

## :checkered\_flag: Your First Request

To start off, let’s try a simple search:

> Give me a few engineering-related job postings at OpenAI.

We will use these filters:

* `company_website`: limits results to a company
* `title_role`: limits results to a PDL role category
* `size`: controls how many records come back

### Example

```python
import requests

API_ENDPOINT = "https://api.peopledatalabs.com/v5/job_posting/search"

payload = {
    "company_website": "openai.com",    # specify the company website
    "title_role": "engineering", # specify the job type
    "size": 3,                   # limit to 3 results max
    "pretty": True,              # return the response in a human-readable format
    "api_key": "YOUR_API_KEY"    # Replace this with your actual API key
}

response = requests.post(API_ENDPOINT, json=payload)
print(response.text)
```

```curl
curl -X POST "https://api.peopledatalabs.com/v5/job_posting/search" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "openai",
    "title_role": "engineering",
    "size": 3,
    "pretty": true,
    "api_key": "YOUR_API_KEY"
  }'
```

<Callout icon="📘" theme="info">
  **Don't forget your API Key!**

  For the example above, you will have to replace `YOUR_API_KEY` with your actual API Key.
</Callout>

### Why This Query Works

The request above uses the simple filter approach:

* `company_website: "openai.com"` tells PDL which company to search for
* `title_role: "engineering"` filters to job postings classified into the `engineering` role
* `size: 3` keeps the response small and easy to inspect

This is a useful pattern because it is easy to read and helps control credit usage while you test.

<Callout icon="📘" theme="info">
  **Credits and record counts**

  Each returned job posting record consumes 1 credit. If `size` is `3` and the API returns 3 records, that request uses 3 credits.
</Callout>

### Example Response

Your response will look something like this:

```json
{
  "status": 200,
  "data": [
    {
      "id": "1Gh/X/FOjeI",
      "first_seen": "2026-04-08",
      "deactivated_date": null,
      "title": "ai workflow engineer, marketing innovation",
      "title_role": "engineering",
      "company_id": "30x8wUj6MNfspLBBgNqOawgOLDP9",
      "company_name": "openai",
      "company_website": "openai.com",
      "location": {
        "country": "united states"
      },
      "description": "...", // (omitted for brevity)
      "last_verified": "2026-04-08"
      ... // Additional fields for this record (omitted for brevity)
    }
    ... // Other records matching your query (omitted for brevity)
  ],
  "total": 673,
  "scroll_token": "WzE3NzQ0ODMyMDAwMDAsICI5bVVtcGdYTjBmOCJd",
  "dataset_version": "34.0"
}
```

### How To Read The Response

Here are the key fields to notice:

* `data`: the list of job posting records returned for this request
* `total`: the total number of matching records in the dataset, not just the number returned in this response
* `scroll_token`: a token you can use to fetch the next batch of results if you want more records

Each item in `data` is a [full job posting record](https://docs.peopledatalabs.com/docs/job-posting-data-overview), including fields such as title, company, location, description, salary information when available, and lifecycle dates like `first_seen`, `last_verified`, and `deactivated_date`.

<Callout icon="📘" theme="info">
  **Full Field List**

  You can see the full list of fields returned for each Job Posting record here: [Job Posting Data Overview](https://docs.peopledatalabs.com/docs/job-posting-data-overview). For a field-by-field breakdown of the API response, see [Output Response](https://docs.peopledatalabs.com/docs/output-response-job-posting-api).
</Callout>

***

## :melting\_face: Common Mistakes

If you get a `401 Unauthorized` response, check that:

* your API key is included in the request
* your API key is correct
* your API key has beta access to the Job Posting Search API enabled

For additional troubleshooting, see [Reference](https://docs.peopledatalabs.com/docs/reference-job-posting-api) and [FAQs](https://docs.peopledatalabs.com/docs/faqs-job-posting-api).

***

## What To Do Next

Once you are ready to go further, these are the most useful next pages:

* [Use Cases](https://docs.peopledatalabs.com/docs/use-cases-job-posting-api) for examples of real-world use cases for the Job Posting Search API
* [Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api) for more query patterns, pagination examples, and advanced Elasticsearch examples
* [Reference](https://docs.peopledatalabs.com/docs/reference-job-posting-api) for endpoint behavior, billing, and request rules
* [Input Parameters](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api) for detailed field-by-field behavior
* [Output Response](https://docs.peopledatalabs.com/docs/output-response-job-posting-api) for response structure details
* [FAQs](https://docs.peopledatalabs.com/docs/faqs-job-posting-api) for additional tips and answers to common questions

As you continue on, one general workflow to follow is to start with a small `size`, inspect real results, and then add filters or move into the [Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api) page as your query gets more specific.