Quickstart - Job Posting Search API

⚡ Quickstart

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

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

🎗️ Before You Start

🏁 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

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 -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"
  }'

📘

Don't forget your API Key!

For the example above, you will have to replace YOUR_API_KEY with your actual API Key.

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.

📘

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.

Example Response

Your response will look something like this:

{
  "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, including fields such as title, company, location, description, salary information when available, and lifecycle dates like first_seen, last_verified, and deactivated_date.

📘

Full Field List

You can see the full list of fields returned for each Job Posting record here: Job Posting Data Overview. For a field-by-field breakdown of the API response, see Output Response.

🫠 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 and FAQs.

What To Do Next

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

• Use Cases for examples of real-world use cases for the Job Posting Search API
• Examples for more query patterns, pagination examples, and advanced Elasticsearch examples
• Reference for endpoint behavior, billing, and request rules
• Input Parameters for detailed field-by-field behavior
• Output Response for response structure details
• FAQs 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 page as your query gets more specific.