Skip to Content
Prospecting data

People and company search

Search Kenso's people and company index, look up profiles, read facets and filters, and import people into a campaign.

Prospecting data20 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.

Search people

POST/v1/search/peoplesearch.search-people
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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, behaviorTags or inLinkedInConnections is 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 the lookalikes feature, or inLinkedInConnections needs linkedin_network or linkedin_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

NameInTypeRequiredDescription
viewquerystringoptionalHow much of each person to return: full (default) or summary.
Request
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

GET/v1/search/people/{personId}search.get-person
Permission
Search view
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
personIdpathinteger (int64)requiredThe kenId of a people search result.
Request
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

GET/v1/search/people/lookupsearch.lookup-person
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

Get one person's full profile from their LinkedIn profile URL, when you do not have their Search id.

Errors:

  • 400 validation_failed: linkedInUrl is missing.
  • 404 not_found: Search holds no person with this URL.
  • 429 quota_exceeded: the daily quota is used up.

Requires Search view.

Parameters

NameInTypeRequiredDescription
linkedInUrlquerystringoptionalThe profile URL, such as https://www.linkedin.com/in/jane-doe.
Request
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

POST/v1/search/people/facetssearch.get-people-facets
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 the lookalikes feature, or inLinkedInConnections needs linkedin_network or linkedin_connections_import.
  • 503 service_unavailable: a lookup the search needs failed. Try again.

Requires Search view.

Request
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

POST/v1/search/companiessearch.search-companies
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 or inLinkedInConnections is not valid.
  • 400 too_many_seeds: lookalike has too many seeds or negatives.
  • 400 invalid_lookalike: lookalike is not valid.
  • 400 lookalikes_unavailable: lookalike search is not available right now.
  • 403 feature_disabled: a lookalike filter needs the lookalikes feature, or inLinkedInConnections needs linkedin_network or linkedin_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.

Request
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

GET/v1/search/companies/{companyId}search.get-company
Permission
Search view
Rate limit
240 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
companyIdpathinteger (int64)requiredThe kenId of a company search result.
Request
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

GET/v1/search/companies/lookupsearch.lookup-company
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

Get one company's full profile from its LinkedIn page URL, when you do not have its Search id.

Errors:

  • 400 validation_failed: linkedInUrl is missing.
  • 404 not_found: Search holds no company with this URL.
  • 429 quota_exceeded: the daily quota is used up.

Requires Search view.

Parameters

NameInTypeRequiredDescription
linkedInUrlquerystringoptionalThe page URL, such as https://www.linkedin.com/company/acme.
Request
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

POST/v1/search/companies/facetssearch.get-company-facets
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 the lookalikes feature, or inLinkedInConnections needs linkedin_network or linkedin_connections_import.
  • 503 service_unavailable: a lookup the search needs failed. Try again.

Requires Search view.

Request
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

GET/v1/search/filterssearch.get-filters
Permission
Search view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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.

Request
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

GET/v1/search/metadatasearch.get-metadata
Permission
Search view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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, or cursor is not valid.

Requires Search view.

Parameters

NameInTypeRequiredDescription
categoryquerystringoptionalA filter category, for example industries. Without it the whole catalog is returned.
qquerystringoptionalText the category's values must contain. Used only with category.
limitqueryinteger (int32)optionalPage size, from 1 to 100. Default 50. Used only with category.
cursorquerystringoptionalThe pagination.nextCursor of the previous page.
includeTotalquerybooleanoptionalAdds pagination.totalCount, the number of values in the category that match q.
Request
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

POST/v1/search/companies/peoplesearch.search-company-people
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 the lookalikes feature.
  • 422 no_usable_seeds: Kenso could not use any lookalike seed.
  • 429 quota_exceeded: the daily quota is used up.

Requires Search view.

Request
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

GET/v1/search/headcount-changessearch.list-headcount-changes
Permission
Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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: cursor is not valid.

Requires Search view.

Parameters

NameInTypeRequiredDescription
monthquerystringoptionalDetection month as yyyy-MM. Without it every month is returned, most recent first.
minGrowthPctquerynumber (double)optionalOnly companies that grew by at least this percentage, for example 20 for 20%.
limitqueryinteger (int32)optionalPage size, from 1 to 100. Default 50.
cursorquerystringoptionalThe pagination.nextCursor of the previous page.
Request
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

POST/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)

Try it on developer.ken.so

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: titles is not valid, for example more than 50 titles.
  • 429 quota_exceeded: the workspace used its aiSearchExpand quota. Retry after the Retry-After header.

Requires Search view.

Request
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

POST/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)

Try it on developer.ken.so

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: industries is not valid, for example more than 50 industries.
  • 429 quota_exceeded: the workspace used its aiSearchExpand quota. Retry after the Retry-After header.

Requires Search view.

Request
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

GET/v1/search/lookalike-seedssearch.list-lookalike-seeds
Permission
Accounts view and Search view
Rate limit
12,000 requests a minute per API key
Needs the lookalikes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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. count is the number of accounts with the domain, normally 1.
  • crm: companies on your opportunities and synced CRM deals. count is the number of deals. stage picks won (the default), open (neither won nor lost) or any. crm_won still works and means crm with stage=won.
  • interested: companies whose people replied with interest. count is the number of contacts.
  • replies: companies whose people sent a real reply, which leaves out automated replies, bounces and out-of-office replies. count is the number of contacts.
  • campaign: the companies of one campaign's live contacts. count is the number of contacts.
  • website_visitors: companies behind human visits to the workspace's tracked website. count is 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: source is missing or unknown, or you sent a parameter the source does not take.
  • 403 permission_denied: you sent campaignId without Campaigns view.
  • 404 not_found: the campaign is not in this workspace or was deleted.

Requires Accounts view and Search view.

Parameters

NameInTypeRequiredDescription
sourcequerystringoptionalRequired: customers, crm, interested, replies, campaign or website_visitors. crm_won is still accepted, as crm with stage=won.
stagequerystringoptionalThe deal stage, with crm only: won (default), open (neither won nor lost) or any.
campaignIdqueryinteger (int64)optionalThe campaign to read. Required with campaign, and an optional filter with interested and replies.
sincequerystringoptionalWith interested, replies and website_visitors: a day as YYYY-MM-DD (UTC). Only replies or visits on or after it count.
Request
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

GET/v1/search/importssearch.list-imports
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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: campaignId is missing.
  • 401 unauthenticated: the API key belongs to no member.
  • 404 not_found: the campaign is not in this workspace.

Requires Campaigns view.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalThe campaign whose latest import you want. Required.
Request
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

POST/v1/search/importssearch.create-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 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: campaignId is missing, both or neither of personIds and searchFilters are sent, personIds is empty, searchFilters is not an object or its inLinkedInConnections is not a boolean, or limit is below 1.
  • 400 lookalike_not_storable: searchFilters 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. 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: inLinkedInConnections needs linkedin_network or linkedin_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.

FieldTypeRequiredDescription
campaignIdinteger (int64)optionalThe campaign in this workspace that receives the people.
personIdsarray of integer (int64)optionalThe people to import, by the kenId of each people search result.
searchFiltersobjectoptionalA people search body, as sent to POST /v1/search/people. Imports every match, up to limit.
limitinteger (int32)optionalThe most people a searchFilters import adds.
Request
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

POST/v1/search/imports/previewsearch.preview-import
Permission
Campaigns view and Search view
Rate limit
200 requests a minute per API key

Try it on developer.ken.so

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 of personIds and searchFilters are sent, personIds is empty, searchFilters is not an object or its inLinkedInConnections is not a boolean, or limit is below 1.
  • 400 lookalike_not_storable: searchFilters carries a lookalike filter.
  • 403 feature_disabled: inLinkedInConnections needs linkedin_network or linkedin_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.

FieldTypeRequiredDescription
personIdsarray of integer (int64)optionalThe people the import would take, by the kenId of each people search result.
searchFiltersobjectoptionalA people search body, as sent to POST /v1/search/people. Previews its matches up to limit.
limitinteger (int32)optionalThe most people a searchFilters import would add. Default 5,000.
Request
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

GET/v1/search/imports/{importId}search.get-import
Permission
Campaigns view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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

NameInTypeRequiredDescription
importIdpathinteger (int64)requiredThe import's id, the jobId that POST /v1/search/imports returned.
Request
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

GET/v1/search/samplesearch.get-sample
Permission
Search view
Rate limit
12,000 requests a minute per API key

Try it on developer.ken.so

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. refreshing is 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: the search_sample feature 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.

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


On this page