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

# Use Cases - Job Posting Search API

_Copy-pasteable workflows for common Job Posting Search API use cases_

# Use Cases

This page contains **real-world workflows** using the Job Posting Search API.

Each use case is designed to be:

* ✅ Easy to copy and run
* 🔧 Simple to customize
* 🎯 Aligned with common customer goals

<br />

***

<br />

## How to Use These Examples

1. Copy the example
2. Replace inputs (e.g. [`location`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#location), [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website))
3. Run the request

<Callout icon="📘" theme="info">
  **Need help getting started?**

  See the full [Quickstart guide](https://docs.peopledatalabs.com/docs/quickstart-job-posting-api) to make your first Job Posting Search API request.

  Looking for more patterns? Browse the [Examples page](https://docs.peopledatalabs.com/docs/examples-job-posting-api) for a library of additional query examples.
</Callout>

<br />

<Callout icon="❗️" theme="error">
  **Credit Usage Reminder**

  Each job posting returned costs **1 credit**.

  If your query may return many results, start with a small [`size`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#size) (e.g. 10) and paginate using [`scroll_token`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#scroll_token).
</Callout>

<br />

***

<br />

# **🧭 Keep a Job Board Up to Date**

**Goal:** Keep the job postings shown in your job board fresh as users search and browse.

**Recommended workflow:** Query the Job Posting API when a user runs a search, filter to active postings, and paginate with `scroll_token`. This gives users current results without requiring a full background refresh of every matching job.

<br />

## **A. Recommended: Fetch Results When Users Search**

**When to use this:**

* Power a live job board or search experience
* Keep displayed jobs fresh
* Avoid refreshing every possible matching posting upfront

```py
import requests

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

payload = {
    "location": "united states",
    "title": "data engineer",
    "is_active": True,
    "size": 20,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
first_page = response.json()

print(f"Showing {len(first_page['data'])} active job postings")
print(f"Next page token: {first_page.get('scroll_token')}")
```

To load the next page, send the same query with the latest `scroll_token`:

```py
next_payload = {
    **payload,
    "scroll_token": first_page["scroll_token"]
}

next_response = requests.post(API_ENDPOINT, json={**next_payload, "api_key": API_KEY})
next_response.raise_for_status()
next_page = next_response.json()

print(f"Showing {len(next_page['data'])} more active job postings")
print(f"Next page token: {next_page.get('scroll_token')}")
```

<br />

## **B. Full Refresh: Pull All Active Matches on a Schedule**

Use this when your use case needs a complete refreshed result set for a fixed filter, such as all active engineering jobs in a country.

<Callout icon="⚠️" theme="warn">
  This strategy is simple and keeps your data current, **but it can return many records**. Start with a small `size`, estimate result volume with `total`, and paginate using `scroll_token`.
</Callout>

<br />

```py
import requests

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

payload = {
    "location": "united states",
    "title_role": "engineering",
    "is_active": True,
    "size": 100,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
page = response.json()

print(f"Total active matches: {page['total']}")
print(f"Pulled {len(page['data'])} records in this page")
```

<br />

## **Customize This**

* Replace [`location`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#location) with your target geography, such as `"united states"`, `"california"`, or `"san francisco, california, united states"`.
* Change the title filter from [`title`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title) to a structured field such as [`title_role`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_role), [`title_sub_role`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_sub_role), or [`title_levels`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_levels).
* Keep [`is_active`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#is_active) set to `true` when you only want active postings.
* Adjust [`size`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#size) based on your UI. A search results page often starts with 10-20 records, while a scheduled refresh can use up to 100 records per request.
* Use [`scroll_token`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#scroll_token) to load additional pages until you have enough results or pagination is complete.

<br />

***

<br />

# 🌍 **Get All Job Postings in a Country**

**Goal:** Retrieve job postings for a specific country.

**When to use this:**

* Analyze hiring trends by region
* Build geo-based prospecting lists
* Monitor hiring activity in new markets

<br />

## Example

```python
import requests

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

payload = {
    "location": "singapore",  # Change this to your target country
    "size": 10,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
print(response.text)

```

<br />

## **Customize This**

* Replace `"singapore"` with any country in our <Anchor label="canonical countries list" target="_blank" href="doc:location-countries">canonical countries list</Anchor> such as:
  * `"australia"`
  * `"india"`
  * `"united kingdom"`
* Add additional search criteria like [`title`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title), [`title_role`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_role), or [`title_levels`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title_levels).
* Filter to only active jobs using the [`is_active`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#is_active) filter or only jobs posted in the past year using the [`first_seen_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#first_seen_min) filter
* To retrieve all job postings for the country, use the [`scroll_token`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#scroll_token) pattern as shown in the [Bulk Retrieval Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api#bulk-retrieval-examples).

<br />

***

<br />

# **🏢 Get All Job Postings from a Company**

## **A. Single Company**

**Goal:** Retrieve all job postings for a specific company.

**When to use this:**

* Track hiring activity for a target account
* Monitor competitor hiring

```python
import requests

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

payload = {
    "company_website": "stripe",  # Change this
    "size": 10,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
print(response.text)
```

<br />

## **B. Multiple Companies (Target Account List)**

**Goal:** Retrieve job postings across a list of companies.

**When to use this:**

* Analyze hiring across target accounts
* Build outbound prospecting signals
* Compare competitors

```python
import requests

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

payload = {
    "query": {
        "terms": {
            "company_website": [
                "stripe.com",
                "openai.com",
                "airbnb.com"
            ]
        }
    },
    "size": 10,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
print(response.text)
```

<br />

## **Customize This**

* Add or remove companies in the list
* Use [`company_id`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_id) instead of [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) for more precision or use [`company_name`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_name) when a website isn't available to you.
* To retrieve all job postings for your queries, use the [`scroll_token`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#scroll_token) pattern as shown in the [Bulk Retrieval Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api#bulk-retrieval-examples).

<br />

***

<br />

# **🔗 Find Companies → Then Get Their Job Postings**

**Goal:**

1. Find companies matching a criteria
2. Retrieve all job postings for those companies

Example scenario:\
Find companies headquartered in San Francisco, CA with >10k employees, then get all their job postings.

<br />

## **Step 1: Find Companies**

Use the [Company Search API](https://docs.peopledatalabs.com/docs/company-search-api) to retrieve companies in your target region.

```python
import requests

API_KEY = "YOUR_API_KEY"
API_ENDPOINT = "https://api.peopledatalabs.com/v5/company/search"


payload = {
  "size": 25,
  "query": {
    "bool": {
      "must": [
        # Companies located in San Francisco, California
        {"term": {"location.metro": "san francisco, california"}},
        # Headcount of 10000 or more employees
        {"range": {"employee_count": {"gte": 10000}}}
      ]
    }
  }
}

# Get Search Results
response = requests.get(API_ENDPOINT, headers={"X-Api-Key": API_KEY}, json=payload)
response.raise_for_status()
company_response = response.json()

# Extract list of Company IDs
company_ids = [company.get("id") for company in company_response.get("data", [])]

# Print Match Results
print(f"Company IDs: {company_ids}")
print(f"Total Companies Found: {company_response.get('total', 'N/A')}")
print(f"Number of Companies Pulled: {len(company_ids)}")
```

*(Example Results)*

```python
company_ids = [
    "MUmQQfYqtsuKmlbipURRywewO7SK",
    "2kBZISO0NiVIcCStZwrF5g2YM7xE",
    "azWjYmMaDbflV5f9Bic2QQ0RS38i",
    "OGpJ3caiC2UPrpzNTA6EHwFL1Yjc",
    ...
]
```

<br />

## **Step 2: Get Job Postings for Those Companies**

```py
import requests

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

company_ids = [
    "MUmQQfYqtsuKmlbipURRywewO7SK",
    "2kBZISO0NiVIcCStZwrF5g2YM7xE",
    "azWjYmMaDbflV5f9Bic2QQ0RS38i",
    "OGpJ3caiC2UPrpzNTA6EHwFL1Yjc",
    # Other company IDs can be added here
]

payload = {
    "query": {
        "terms": {
            "company_id": company_ids
        }
    },
    "size": 50,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
print(response.text)
```

<br />

## **Why This Matters**

This pattern is powerful for:

* Territory-based prospecting
* Market mapping
* Lead generation workflows

<br />

***

<br />

# **📈 Use Job Postings as an Intent Signal**

**Goal:** Identify companies showing hiring intent for a specific function so you can prioritize outreach.

**Example:** Find companies with newly posted SDR roles since April 9, 2026.

<br />

## **Example**

```py
import requests

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

payload = {
    "title": "sdr",
    "first_seen_min": "2026-04-09",  # Change this to your lookback start date
    "is_active": True,
    "size": 25,
    "pretty": True
}

response = requests.post(API_ENDPOINT, json={**payload, "api_key": API_KEY})
response.raise_for_status()
print(response.text)
```

<br />

## **Why This Works**

This pattern is useful when job postings act as a buying or growth signal.

If a company is actively hiring SDRs, AEs, recruiters, or engineers, that can indicate:

* Team expansion
* New budget or headcount
* Operational pain points they may want to solve
* A reason to prioritize outreach with a relevant message

<br />

## **Customize This**

You can adapt this pattern for:

* Other functions like [`title`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title) = `"account executive"`, `"recruiter"`, or `"gtm engineer"`
* Search for keywords in the description [`description`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#description) like `"salesforce"`, `"python"`, or "`databricks"`.
* Different recency windows using [`first_seen_min`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#first_seen_min)
* Regional targeting by adding [`location`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#location)
* Account-based monitoring by layering on [`company_id`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_id) or [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website)

<br />

***

<br />

# **🚀 What to Try Next**

* Combine multiple filters ([`location`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#location) + [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) + [`title`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#title)) - see the [Field Filter](https://docs.peopledatalabs.com/docs/examples-job-posting-api#field-filter-examples) examples
* Add date filters to track recent job postings - see [Search by Exact Date](https://docs.peopledatalabs.com/docs/examples-job-posting-api#search-by-exact-date), [Search by Last Verified Date](https://docs.peopledatalabs.com/docs/examples-job-posting-api#search-by-last-verified-date), and [Active Jobs Only](https://docs.peopledatalabs.com/docs/examples-job-posting-api#active-jobs-only). If you need custom Elasticsearch date logic, see [Date Range Query](https://docs.peopledatalabs.com/docs/examples-job-posting-api#date-range-query)
* Use pagination ([`scroll_token`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#scroll_token)) for large datasets - see the [Bulk Retrieval](https://docs.peopledatalabs.com/docs/examples-job-posting-api#bulk-retrieval-examples) examples

For a comprehensive list of query patterns, see the [Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api) page.