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

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.

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.

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

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.

The most precise company filter is company_id.

In practice, the precision ladder is usually:

• company_name for convenience
• company_website or company_profile as stronger intermediate options
• company_id for the most exact match

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.

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

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.

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.

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.

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.

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.

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.

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.

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.