Skip to main content
Have a Question You Want Answered? Ask Us!Head over to the Help Center 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.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.

​
What is the easiest way to make my first successful request?

Start with 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.

​
Should I use Field Filters or the Elasticsearch query field?

Use 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 are the best starting point because they are simpler and easier to debug.

​
Can I use 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 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 combined with AND or OR?

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 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 or 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. If not, company_website or company_profile are great next-best options when you have either. If you only know the company name, 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 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.

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

Related topics

Quickstart - Job Posting Search APIFAQs - Company Search APIFAQs - Person Search APIExamples - Job Posting Search APIJob Posting Search API