People and company search
Search Kenso's people and company index, look up profiles, read facets and filters, and import people into a campaign.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The 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-Id | header | integer (int64) | optional | The 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. |
Search people
/v1/search/peoplesearch.search-people- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Search Kenso's people index with filters and get one page of people, for example to pick prospects to import.
The body holds the filters (GET /v1/search/filters lists their values), page (from 1) and pageSize (0 to 100, default 25). Each person carries hasKenEmail, true when Kenso holds a verified email, and kenEmailStatus: none, risky, catch_all or verified. view=summary returns only list row fields, about 2 KB a person instead of 20 KB. For people like examples you know, send companyLookalike or lookalike (see GET /v1/search/lookalike-seeds). With the behavior_signals feature, people carry behaviorTags from past outreach, and a behaviorTags list in the body keeps people with one of them, so a page can hold fewer people.
inLinkedInConnections: true keeps only people who are a 1st-degree connection of one of the workspace's LinkedIn seats, together with every other filter. It needs the linkedin_network or linkedin_connections_import feature. With no connections synced, the search matches nobody.
Errors:
400 validation_failed: a filter,view,behaviorTagsorinLinkedInConnectionsis not valid.400 lookalike_conflict: the body sends both lookalike filters.400 too_many_seeds: a lookalike filter has too many seeds.400 invalid_lookalike: a lookalike filter is not valid.400 lookalikes_unavailable: lookalike search is not available right now.403 feature_disabled: a lookalike filter needs thelookalikesfeature, orinLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.422 no_usable_seeds: Kenso could not use any seed.429 quota_exceeded: the daily quota is used up.503 service_unavailable: a lookup the search needs failed. Try again.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
view | query | string | optional | How much of each person to return: full (default) or summary. |
curl -X POST "https://api.ken.so/v1/search/people" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPeopleResults.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a person
/v1/search/people/{personId}search.get-person- Permission
- Search view
- Rate limit
- 240 requests a minute per API key
Get one person's full profile by Search id, with hasKenEmail and kenEmailStatus.
Errors:
404 not_found: no person has this id.429 quota_exceeded: the daily quota is used up.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
personId | path | integer (int64) | required | The kenId of a people search result. |
curl -X GET "https://api.ken.so/v1/search/people/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPerson.
Show the 103 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Look up a person by LinkedIn URL
/v1/search/people/lookupsearch.lookup-person- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Get one person's full profile from their LinkedIn profile URL, when you do not have their Search id.
Errors:
400 validation_failed:linkedInUrlis missing.404 not_found: Search holds no person with this URL.429 quota_exceeded: the daily quota is used up.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
linkedInUrl | query | string | optional | The profile URL, such as https://www.linkedin.com/in/jane-doe. |
curl -X GET "https://api.ken.so/v1/search/people/lookup" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPerson.
Show the 103 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get people search facets
/v1/search/people/facetssearch.get-people-facets- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Count the people that match each value of the main filters, for a POST /v1/search/people body. Facets do not count against searchBrowseRows. With inLinkedInConnections: true, the counts hold only the workspace's LinkedIn connections.
Errors:
400 validation_failed: a filter is not valid.403 feature_disabled: a lookalike filter needs thelookalikesfeature, orinLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.503 service_unavailable: a lookup the search needs failed. Try again.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/people/facets" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPeopleFacets.
Show the 11 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Search companies
/v1/search/companiessearch.search-companies- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Search Kenso's company index with filters and get one page of companies, for example to build an account list.
The body holds the filters, page (from 1) and pageSize (0 to 100, default 25). For companies like examples you know, send lookalike (see GET /v1/search/lookalike-seeds). A lookalike search returns at most 2,000 companies and ignores sortBy.
inLinkedInConnections: true keeps only companies where at least one of the workspace's LinkedIn connections works now or worked before, together with every other filter. It needs the linkedin_network or linkedin_connections_import feature. With no connections synced, the search matches no company.
Errors:
400 validation_failed: a filter orinLinkedInConnectionsis not valid.400 too_many_seeds:lookalikehas too many seeds or negatives.400 invalid_lookalike:lookalikeis not valid.400 lookalikes_unavailable: lookalike search is not available right now.403 feature_disabled: a lookalike filter needs thelookalikesfeature, orinLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.422 no_usable_seeds: Kenso could not use any seed.429 quota_exceeded: the daily quota is used up.503 service_unavailable: a lookup the search needs failed. Try again.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/companies" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchCompaniesResults.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a company from Search
/v1/search/companies/{companyId}search.get-company- Permission
- Search view
- Rate limit
- 240 requests a minute per API key
Get one company's full profile by Search id.
Errors:
404 not_found: no company has this id.429 quota_exceeded: the daily quota is used up.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
companyId | path | integer (int64) | required | The kenId of a company search result. |
curl -X GET "https://api.ken.so/v1/search/companies/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchCompany.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Look up a company by LinkedIn URL
/v1/search/companies/lookupsearch.lookup-company- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Get one company's full profile from its LinkedIn page URL, when you do not have its Search id.
Errors:
400 validation_failed:linkedInUrlis missing.404 not_found: Search holds no company with this URL.429 quota_exceeded: the daily quota is used up.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
linkedInUrl | query | string | optional | The page URL, such as https://www.linkedin.com/company/acme. |
curl -X GET "https://api.ken.so/v1/search/companies/lookup" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchCompany.
Show the 48 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get company search facets
/v1/search/companies/facetssearch.get-company-facets- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Count the companies that match each value of the main filters, for a POST /v1/search/companies body. Facets do not count against searchBrowseRows. With inLinkedInConnections: true, the counts hold only companies where one of the workspace's LinkedIn connections works or worked.
Errors:
400 validation_failed: a filter is not valid.403 feature_disabled: a lookalike filter needs thelookalikesfeature, orinLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.503 service_unavailable: a lookup the search needs failed. Try again.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/companies/facets" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchCompanyFacets.
Show the 11 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get the filter options
/v1/search/filterssearch.get-filters- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
Get the fixed values the people and company filters accept, such as seniority levels, industries and locations.
Page through long lists, such as job titles or cities, with GET /v1/search/metadata.
Requires Search view.
curl -X GET "https://api.ken.so/v1/search/filters" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchFilterCatalog.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List filter values
/v1/search/metadatasearch.get-metadata- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
List the values of one filter category, such as industry, job_title, skill or city, for type-ahead pickers.
q keeps values that contain its text, limit and cursor page the list, and includeTotal=true adds pagination.totalCount. Without category, the answer is the whole filter catalog as one object.
Errors:
400 validation_failed: the category is unknown, orcursoris not valid.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
category | query | string | optional | A filter category, for example industries. Without it the whole catalog is returned. |
q | query | string | optional | Text the category's values must contain. Used only with category. |
limit | query | integer (int32) | optional | Page size, from 1 to 100. Default 50. Used only with category. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. |
includeTotal | query | boolean | optional | Adds pagination.totalCount, the number of values in the category that match q. |
curl -X GET "https://api.ken.so/v1/search/metadata?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
The body is a SearchMetadataValuesResponse or SearchFilterCatalogResponse.
Show an example response
The fields and an example are also on this endpoint's Markdown page.
Search people at given companies
/v1/search/companies/peoplesearch.search-company-people- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
Search people at the companies you name, for example after a company search.
Send a POST /v1/search/people body plus companyIds, the kenId values of the companies. The answer is a people search page.
Errors:
400 validation_failed: a filter is not valid.403 feature_disabled: a lookalike filter needs thelookalikesfeature.422 no_usable_seeds: Kenso could not use any lookalike seed.429 quota_exceeded: the daily quota is used up.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/companies/people" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPeopleResults.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List companies with headcount growth
/v1/search/headcount-changessearch.list-headcount-changes- Permission
- Search view
- Rate limit
- 200 requests a minute per API key
List companies whose headcount grew from one month to the next.
month picks the month (all months, newest first, when omitted), minGrowthPct sets the least growth, and limit and cursor page the list.
Errors:
400 validation_failed:cursoris not valid.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
month | query | string | optional | Detection month as yyyy-MM. Without it every month is returned, most recent first. |
minGrowthPct | query | number (double) | optional | Only companies that grew by at least this percentage, for example 20 for 20%. |
limit | query | integer (int32) | optional | Page size, from 1 to 100. Default 50. |
cursor | query | string | optional | The pagination.nextCursor of the previous page. |
curl -X GET "https://api.ken.so/v1/search/headcount-changes?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of object. Each item has these fields. The response also carries pagination.
Show an example response
The fields and an example are also on this endpoint's Markdown page.
Expand job titles
/v1/search/people/expand-titlessearch.expand-titles- Permission
- Search view
- Rate limit
- 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day)
Get related job titles for the titles you send, so a people search also finds the same role under other names.
Send titles, a list of up to 50 job titles. The answer's expandedTitles maps each title you sent to its related titles. error says why when the expansion failed.
Kenso runs an AI model for each expansion. The same body in the same workspace within an hour gets the earlier answer at no cost. Any other call takes one unit of the workspace's aiSearchExpand quota: 20 a minute and 500 a day, shared with industry expansion.
Errors:
400 validation_failed:titlesis not valid, for example more than 50 titles.429 quota_exceeded: the workspace used itsaiSearchExpandquota. Retry after theRetry-Afterheader.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/people/expand-titles" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchPeopleTitleExpansion.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Expand industries
/v1/search/metadata/expand-industriessearch.expand-industries- Permission
- Search view
- Rate limit
- 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day)
Get related industries for the industries you send, so a search covers neighboring industries too.
Send industries, a list of up to 50 industries. The answer's expandedIndustries maps each industry you sent to its related industries. error says why when the expansion failed.
Kenso runs an AI model for each expansion. The same body in the same workspace within an hour gets the earlier answer at no cost. Any other call takes one unit of the workspace's aiSearchExpand quota: 20 a minute and 500 a day, shared with title expansion.
Errors:
400 validation_failed:industriesis not valid, for example more than 50 industries.429 quota_exceeded: the workspace used itsaiSearchExpandquota. Retry after theRetry-Afterheader.
Requires Search view.
curl -X POST "https://api.ken.so/v1/search/metadata/expand-industries" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchIndustryExpansion.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List lookalike seed suggestions
/v1/search/lookalike-seedssearch.list-lookalike-seeds- Permission
- Accounts view and Search view
- Rate limit
- 12,000 requests a minute per API key
lookalikes feature on your workspace. Until it is on, calls answer 404.List companies from your own data that make good seeds for a lookalike search: your customers, your deals, the companies that replied, a campaign's companies or your website visitors. Send a row's domain as a {"domain": ...} seed in POST /v1/search/companies or POST /v1/search/people.
source is required and picks where the companies come from:
customers: the workspace's customer accounts.countis the number of accounts with the domain, normally 1.crm: companies on your opportunities and synced CRM deals.countis the number of deals.stagepickswon(the default),open(neither won nor lost) orany.crm_wonstill works and meanscrmwithstage=won.interested: companies whose people replied with interest.countis the number of contacts.replies: companies whose people sent a real reply, which leaves out automated replies, bounces and out-of-office replies.countis the number of contacts.campaign: the companies of one campaign's live contacts.countis the number of contacts.website_visitors: companies behind human visits to the workspace's tracked website.countis the number of visits.
campaignId is required with campaign and filters interested and replies to one campaign. Sending it also needs Campaigns view. since, a YYYY-MM-DD day in UTC, keeps only replies or visits on or after that day, for interested, replies and website_visitors.
Kenso reads at most the newest 20,000 replies, contacts or visits and groups them by company domain: the contact's company domain, else the domain of their email address. A free email domain never becomes a seed. The list holds up to 200 rows in one page, sorted by count from high to low, then by domain. An empty list is normal. The call is free.
The lookalike filters need the lookalikes feature. Each takes seeds, negatives (up to 100 to steer away from), mode (precise or broad) and minGrade (1 to 5, default 2: precise drops rows graded below it). POST /v1/search/companies takes lookalike with 1 to 100 company seeds, each a companyId, domain, linkedInUrl or text (up to 4,000 characters), plus excludeDomains and includeNonB2b. POST /v1/search/people takes either companyLookalike, the same filter, or lookalike with 1 to 50 people seeds, each a personId or linkedInUrl, plus includeSeedCompanies. Kenso excludes the workspace's do-not-contact and customer domains. Rows come sorted by similarity, each with lookalike: a score from 0 to 100 and a grade from 1 to 5, 5 the closest. The page lists each seed's outcome in lookalikeSeeds. A lookalike search is a snapshot, so save or import its results by id, not by its filters.
Errors:
400 validation_failed:sourceis missing or unknown, or you sent a parameter the source does not take.403 permission_denied: you sentcampaignIdwithout Campaigns view.404 not_found: the campaign is not in this workspace or was deleted.
Requires Accounts view and Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
source | query | string | optional | Required: customers, crm, interested, replies, campaign or website_visitors. crm_won is still accepted, as crm with stage=won. |
stage | query | string | optional | The deal stage, with crm only: won (default), open (neither won nor lost) or any. |
campaignId | query | integer (int64) | optional | The campaign to read. Required with campaign, and an optional filter with interested and replies. |
since | query | string | optional | With interested, replies and website_visitors: a day as YYYY-MM-DD (UTC). Only replies or visits on or after it count. |
curl -X GET "https://api.ken.so/v1/search/lookalike-seeds" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of LookalikeSeed. Each item has these fields. The response also carries pagination.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a campaign's latest import
/v1/search/importssearch.list-imports- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Get the most recent Search import into one campaign, for example to show its progress when you open the campaign.
The answer is a list of zero or one import, in the shape GET /v1/search/imports/{importId} returns. It never has a next page.
Errors:
400 validation_failed:campaignIdis missing.401 unauthenticated: the API key belongs to no member.404 not_found: the campaign is not in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
campaignId | query | integer (int64) | optional | The campaign whose latest import you want. Required. |
curl -X GET "https://api.ken.so/v1/search/imports" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of object. Each item has these fields. The response also carries pagination.
Show an example response
The fields and an example are also on this endpoint's Markdown page.
Import people into a campaign
/v1/search/importssearch.create-import- Permission
- Campaigns edit and Search view and the
importpermission - Rate limit
- 480 requests a minute per API key
Add Search people to a campaign as contacts. Pick the people by id, or import every match of a people search.
Send campaignId and exactly one of personIds or searchFilters. personIds must not be empty. searchFilters is a people search body, and Kenso imports its matches up to limit. A lookalike search cannot be imported by its filters: send the people it found as personIds. With inLinkedInConnections: true in searchFilters, the import takes only the workspace's LinkedIn connections, and needs the linkedin_network or linkedin_connections_import feature. To see first how many of the people Kenso already holds an email for, call POST /v1/search/imports/preview.
The import runs in the background and fills the campaign in batches. The call answers 202 with the import job's jobId and status. Poll GET /v1/search/imports/{importId} with that jobId.
Errors:
400 validation_failed:campaignIdis missing, both or neither ofpersonIdsandsearchFiltersare sent,personIdsis empty,searchFiltersis not an object or itsinLinkedInConnectionsis not a boolean, orlimitis below 1.400 lookalike_not_storable:searchFilterscarries 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. Contacts you upload from a CSV file are still imported.401 unauthenticated: the API key belongs to no member. An import runs as a member.403 feature_disabled:inLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.404 not_found: the campaign is not in this workspace.503 service_unavailable: the workspace's LinkedIn connections could not be read. Try again.
Requires Campaigns edit and the import permission, plus Search view.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
campaignId | integer (int64) | optional | The campaign in this workspace that receives the people. |
personIds | array of integer (int64) | optional | The people to import, by the kenId of each people search result. |
searchFilters | object | optional | A people search body, as sent to POST /v1/search/people. Imports every match, up to limit. |
limit | integer (int32) | optional | The most people a searchFilters import adds. |
curl -X POST "https://api.ken.so/v1/search/imports" \
-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 '{
"campaignId": 812,
"personIds": [
812
],
"searchFilters": null,
"limit": 1
}'Response 202
data is a SearchImportJob.
Show the 2 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Preview an import
/v1/search/imports/previewsearch.preview-import- Permission
- Campaigns view and Search view
- Rate limit
- 200 requests a minute per API key
See how many people an import would take and how many of them Kenso already holds a verified email for. On a paid plan, a person whose email Kenso already holds costs no email find, so use this to estimate an import's cost.
Send the selection you would send to POST /v1/search/imports, without campaignId: exactly one of personIds or searchFilters, with limit (5,000 when omitted). The answer holds personCount, checkedCount and kenEmailCount. Kenso checks at most the first 500 people. inLinkedInConnections: true in searchFilters needs the linkedin_network or linkedin_connections_import feature, as on the import.
The preview imports nothing and does not count against searchBrowseRows.
Errors:
400 validation_failed: both or neither ofpersonIdsandsearchFiltersare sent,personIdsis empty,searchFiltersis not an object or itsinLinkedInConnectionsis not a boolean, orlimitis below 1.400 lookalike_not_storable:searchFilterscarries a lookalike filter.403 feature_disabled:inLinkedInConnectionsneedslinkedin_networkorlinkedin_connections_import.503 service_unavailable: Search could not return every person to check (Kenso fails the preview rather than return a lower count), or the workspace's LinkedIn connections could not be read. Try again.
Requires Campaigns view, plus Search view.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
personIds | array of integer (int64) | optional | The people the import would take, by the kenId of each people search result. |
searchFilters | object | optional | A people search body, as sent to POST /v1/search/people. Previews its matches up to limit. |
limit | integer (int32) | optional | The most people a searchFilters import would add. Default 5,000. |
curl -X POST "https://api.ken.so/v1/search/imports/preview" \
-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 '{
"personIds": [
812
],
"searchFilters": null,
"limit": 1
}'Response 200
data is a SearchImportPreview.
Show the 3 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get an import
/v1/search/imports/{importId}search.get-import- Permission
- Campaigns view
- Rate limit
- 12,000 requests a minute per API key
Get the progress of one import into a campaign. Poll it after POST /v1/search/imports until the import ends.
status is Queued or Processing while the import runs, then a final value such as Ready or Failed. The answer also holds the counts (totalRecords, processedRecords and importedCount), the people skipped by reason under skips, and errorMessage when the import failed.
Errors:
401 unauthenticated: the API key belongs to no member.404 not_found: no import has this id in this workspace.
Requires Campaigns view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
importId | path | integer (int64) | required | The import's id, the jobId that POST /v1/search/imports returned. |
curl -X GET "https://api.ken.so/v1/search/imports/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchImport.
Show the 17 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get the sample search
/v1/search/samplesearch.get-sample- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
Get a ready-made sample search for this workspace. Ken picks one search from the workspace's ideal customer profile (ICP) and runs it for people, companies, job posts and funding, so a new workspace sees real results before it builds its own search.
The call answers at once and never waits for a build. status is one of:
ready: the sample is in the answer.refreshingis true while Kenso rebuilds it because the ICP changed or the sample expired.pending: there is no sample yet and a build is queued or running. Poll again in about 5 seconds.unavailable: the workspace has no ICP context yet, the workspace used its 6 builds of the day with no sample to serve, or the last build for this ICP failed. Kenso retries a failed build after 10 minutes when a service was down, and after 6 hours when the search found nothing.off: thesearch_samplefeature is off for the workspace, and nothing runs.
A ready sample holds query, the filters Ken picked, and four tabs. profiles and companies hold the request sent and the page that POST /v1/search/people or POST /v1/search/companies returned for it. jobs holds the request (jobFilters and peopleFilters) and the companies and people pages the job post searches returned. funding holds the request (signalType and parameters) and the page that POST /v1/triggers/preview returned. A tab is absent when its search failed or found nothing.
Kenso keeps a sample for 7 days, or 10 minutes when a tab failed during an outage. It rebuilds the sample, at most 6 times a day, when the workspace's website, company context or ICP knowledge file changes. The sample is free: it costs no credits, does not count against searchBrowseRows, and never becomes a saved search or list.
Errors:
503 service_unavailable: Kenso could not read the sample. Try again.
Requires Search view.
curl -X GET "https://api.ken.so/v1/search/sample" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SearchSampleResource.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Prospecting data:Saved searchesSaved listsSaved list membersSaved list invitesEmail finderFunding roundsJob postingsJob post searchLinkedIn job searchLinkedIn jobsWeb scrapingSocial data lookupsSocial data searchesSocial profile resolutionSocial data recordsSignalsAll resources