> ## 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.
# FAQs - Job Posting Search API
### Have a Question You Want Answered? Ask Us!
Head over to the [Help Center](https://support.peopledatalabs.com) and search for your question. If you still can't find what you're looking for, create a support ticket and we will get it answered for you!
## Do I need special access to use the Job Posting Search API?
Yes. The Job Posting Search API is currently in **Beta**.
To use it successfully, you need:
* A valid PDL API key
* Beta access enabled for the Job Posting Search API on that key
Beta access can be provided for any PDL customers. To request access, please reach out to your customer success team or [contact us](https://www.peopledatalabs.com/job-posting-beta-sign-up).
If you receive a `401 Unauthorized` response, first confirm that your API key is valid and that beta access has been enabled.
If have access and would like to get started using the API, take a look at the [Quickstart guide](https://docs.peopledatalabs.com/docs/quickstart-job-posting-api).
## What is the easiest way to make my first successful request?
Start with [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters), not `query`.
The simplest first request is usually something like:
* `company_name`
* `title_role`
* `location`
* a small `size` such as `3` or `10`
This makes it easy to confirm that your access works, inspect a few real records, and control credit usage while testing.
If you want a copy-pasteable first request, start with the [Quickstart guide](https://docs.peopledatalabs.com/docs/quickstart-job-posting-api).
## Should I use [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) or the Elasticsearch `query` field?
Use [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) when your search can be expressed with supported fields such as `company_name`, `company_id`, `title`, `location`, `title_role`, `is_active`, or salary filters.
Use `query` when you need Elasticsearch logic that Field Filters do not support well, such as:
* `OR` logic
* `must_not`
* `exists`
* `terms` queries across a list of values
* more custom boolean or range logic
For most first-time users, [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) are the best starting point because they are simpler and easier to debug.
## Can I use [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) and `query` in the same request?
No. You should treat these as two separate search modes.
If you provide `query`, all [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) in the same request are ignored.
A good rule is:
* Use Field Filters for straightforward searches
* Use `query` only when you need more advanced Elasticsearch behavior
## Are multiple [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) combined with `AND` or `OR`?
[Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) are combined with `AND` logic.
For example, a request with `company_name=openai` and `title=engineer` returns job postings that match both conditions.
If you need `OR` logic, use the `query` field with an Elasticsearch `bool` query.
## What is the most precise way to search for a company?
The most precise company filter is `company_id`.
In practice, the precision ladder is usually:
* [`company_name`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_name) for convenience
* [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) or [`company_profile`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_profile) as stronger intermediate options
* [`company_id`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_id) for the most exact match
[`company_name`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_name) is convenient, but it is cleaner-backed and may not behave like a raw exact string match on the literal text you typed.
[`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) or [`company_profile`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_profile) are often more precise than company name alone because a company website/linkedin url is a stronger identifier, while still being easier to obtain than a PDL company ID.
If you already know the PDL company ID, use [`company_id`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_id). If not, [`company_website`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_website) or [`company_profile`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_profile) are great next-best options when you have either. If you only know the company name, [`company_name`](https://docs.peopledatalabs.com/docs/input-parameters-job-posting-api#company_name) is usually the best place to start.
## Why did my `company_name` or `location` search behave differently from my raw input?
The `company_name` input is standardized using PDL's Company Cleaner, and the `location` input is standardized using PDL's Location Cleaner.
This helps normalize real-world input, but it also means the API is not always doing a literal exact string match on what you typed.
In practice:
* `company_name` is useful when you know the company by name
* `location` is useful for human-friendly geography searches
* `company_id` is the best option when you need the most precise company matching
## Why are my `title` or `description` matches broader or narrower than expected?
The `title` and `description` [Field Filters](https://docs.peopledatalabs.com/docs/reference-job-posting-api#field-filters) use phrase-style matching behavior.
That means matching is case-insensitive and supports substring-style matches, but word order still matters.
For example, `title=data engineer` can match `Senior Data Engineer`, but would not match `Engineer, Data`.
If you need more control over matching behavior, use the `query` field.
## How do date field filters work?
Date field filters such as `first_seen_min`, `first_seen_max`, `deactivated_date_min`, `deactivated_date_max`, `last_verified_min`, and `last_verified_max` expect dates in `YYYY-MM-DD` format.
Use:
* `*_min` for inclusive lower bounds
* `*_max` for inclusive upper bounds
For example:
* `first_seen_min=2026-01-01` means records first seen on or after `2026-01-01`
* `first_seen_max=2026-01-31` means records first seen on or before `2026-01-31`
If you need more advanced date logic, use the Elasticsearch `query` field.
## How are credits charged?
The Job Posting Search API uses 1 credit for each job posting record returned in the `data` array.
For example:
* If a request returns 3 records, it uses 3 credits
* If a request returns 25 records, it uses 25 credits
Credits are charged per returned record, not per request.
If a request returns an error or any non-`200` status code, no credits are consumed.
## How can I control credit usage?
The safest way to control spend is to start with a small `size` value and inspect the results before expanding the query.
A practical workflow is:
* Start with `size=3` or `size=10`
* Confirm that the records match what you expect
* Increase `size` or paginate only when needed
This is especially important for broad queries that may match a large number of records.
## Why does `total` show more matches than I received in `data`?
`total` is the total number of records in the dataset that match your query.
`data` only contains the current batch of records returned in that response.
For example, if `total=673` and `size=3`, the response may include only 3 records in `data`, even though 673 total records matched.
To retrieve additional records, use the returned `scroll_token`.
## How do I get more than 100 results?
Use `size` to control how many records are returned in one response, up to a maximum of `100`.
If your query matches more records than fit in one response, use the returned `scroll_token` to request the next batch.
Keep sending the same query with the newest `scroll_token` until you have the records you need or pagination is complete.
For a working example, see the [Bulk Retrieval Examples](https://docs.peopledatalabs.com/docs/examples-job-posting-api#bulk-retrieval-examples).
## Can I search across multiple companies in one request?
Yes, but usually through the `query` field rather than parameterized Field Filters alone.
The most precise pattern is to use a `terms` query on `company_id` when you want to search across a list of companies in a single request.
See [Search Across Multiple Companies](https://docs.peopledatalabs.com/docs/examples-job-posting-api#search-across-multiple-companies) for an example.
## What should I look at first in the response?
Most first-time users should focus on these three response fields first:
* `data`: the job posting records returned in the current response
* `total`: the full number of dataset records matching your query
* `scroll_token`: the token used to retrieve the next batch of results
If you want a field-by-field breakdown of the response format, see [Output Response](https://docs.peopledatalabs.com/docs/output-response-job-posting-api).