Skip to Content
Prospecting data

Job post search

Find the companies and people behind job postings and import them.

Prospecting data4 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List hiring companies

POST/v1/job-post-searches/companiesjob-post-searches.companies
Permission
Search view
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

List the companies hiring for your job filters, one page at a time. Use it to check the job filters before you search for people.

Send jobFilters. Page through the companies with jobFilters.limit and jobFilters.cursor, set to the previous page's pagination.next_cursor. Each company comes with its matching postings and match_count. hiringSet describes the whole set: total companies and truncated.

By default the page lists only companies Kenso Search knows. Send includeUnmatched: true to also list the hiring companies it has no record of, in the same order. Every row then has match_status, matched or unmatched. An unmatched row has a null ken_search_id, the best-known domain with its domain_source, and no people yet. The page's total counts both kinds and unmatched_total counts the unmatched rows. hiringSet.unmatched counts the unmatched companies, while hiringSet.total stays the matched companies that the people searches cover.

The call is free.

Errors:

  • 400 validation_failed: the body is not a JSON object, jobFilters is missing or not an object, or includeUnmatched is not true or false.
  • 422 filter_required: jobFilters sets no filter.
  • 422 invalid_cursor: jobFilters.cursor did not come from a previous page.
  • 503 service_unavailable: job postings are not available right now. Try again.

Requires Search view.

Request body

application/json, optional: object.

Request
curl -X POST "https://api.ken.so/v1/job-post-searches/companies" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a JobPostSearchCompanies.

Show the 5 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Search people at hiring companies

POST/v1/job-post-searches/peoplejob-post-searches.people
Permission
Search view
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

Search for people at the companies hiring for your job filters, and get one page of people. Use it to reach the buyers at companies that are hiring for a role you sell into.

Send jobFilters and peopleFilters. Omit peopleFilters to match everyone at the hiring companies. Kenso limits the search to the hiring set, so a company filter in peopleFilters has no effect. Page with the page and pageSize fields of peopleFilters.

To get the people at each company of a hiring-companies page, send companyIds, up to 25 ken_search_id values from that page, and perCompany, from 1 to 50 people per company (3 when omitted). Kenso then searches each company on its own, so a big company does not crowd out a small one. The answer holds up to perCompany people at each company, in the order of companyIds, and companies, with the companyId and totalResults of each company it searched. A company that is not in the hiring set is not searched and not listed. totalResults adds up the companies' totals, and paging does not apply.

The answer is a people search page, plus hiringSet (count companies and truncated). Each person carries jobPost, the role their company is hiring for: title, url, location, postedAt, openRoles and moreRoles. When no company is hiring, the page is empty. Each person on the page counts against the workspace's daily searchBrowseRows quota.

Errors:

  • 400 validation_failed: the body is not a JSON object, jobFilters is missing or not an object, peopleFilters is not an object, companyIds is not a list of 1 to 25 ids, perCompany is not a whole number from 1 to 50 or comes without companyIds, or Search refused the people filters.
  • 401 unauthenticated: the API key belongs to no member. The search runs as a member.
  • 403 forbidden: Search refused a people filter for this member.
  • 422 filter_required: jobFilters sets no filter.
  • 429 quota_exceeded: the workspace used its daily searchBrowseRows quota.
  • 503 service_unavailable: job postings or Search are not available right now. Try again.

Requires Search view.

Request body

application/json, optional: object.

Request
curl -X POST "https://api.ken.so/v1/job-post-searches/people" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a JobPostSearchPeopleResults.

Show the 11 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Count people at hiring companies

POST/v1/job-post-searches/people/countjob-post-searches.count
Permission
Search view
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

Count the people at the companies hiring for your job filters, without returning them. Use it to size an import.

Send the same jobFilters and peopleFilters as POST /v1/job-post-searches/people. The answer holds totalResults and hiringSet. Counting does not use the searchBrowseRows quota.

Errors:

  • 400 validation_failed: the body is not a JSON object, jobFilters is missing or not an object, peopleFilters is not an object, or Search refused the people filters.
  • 401 unauthenticated: the API key belongs to no member.
  • 403 forbidden: Search refused a people filter for this member.
  • 422 filter_required: jobFilters sets no filter.
  • 503 service_unavailable: job postings or Search are not available right now. Try again.

Requires Search view.

Request body

application/json, optional: object.

Request
curl -X POST "https://api.ken.so/v1/job-post-searches/people/count" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a JobPostSearchPeopleCount.

Show the 2 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Import people at hiring companies

POST/v1/job-post-searches/importjob-post-searches.import
Permission
Campaigns edit and Search view and the import permission
Rate limit
480 requests a minute per API key

Try it on developer.ken.so

Add the people at the companies hiring for your job filters to a campaign as contacts. Each contact gets the five hiring variables, filled from its company's newest matching posting and its number of matching postings.

Send jobFilters, peopleFilters, campaignId (required) and importLimit, a positive whole number that caps how many people Kenso imports. A lookalike search cannot be imported this way.

The import runs in the background. The answer holds jobId: poll GET /v1/search/imports/{importId} with it.

Errors:

  • 400 validation_failed: the body is not valid, campaignId is missing, importLimit is not a positive whole number, or no company is hiring for the job filters (detail code empty_hiring_set).
  • 400 lookalike_not_storable: peopleFilters carries a lookalike filter.
  • 400 validation_failed: the workspace is a developer sandbox. A sandbox holds seeded and test data only, so search imports are not available in it.
  • 401 unauthenticated: the API key belongs to no member. An import runs as a member.
  • 403 forbidden: Search refused the import for this member.
  • 404 not_found: the campaign is not in this workspace.
  • 422 filter_required: jobFilters sets no filter.
  • 503 service_unavailable: job postings or Search are not available right now. Try again.

Requires Campaigns edit and the import permission, plus Search view.

Request body

application/json, optional: object.

Request
curl -X POST "https://api.ken.so/v1/job-post-searches/import" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

data is a JobPostSearchImportResult.

Show the 1 response field and an example

The fields and an example are also on this endpoint's Markdown page.


On this page