Saved Searches saved_searches
Saved Kenso searches and their imports, plus company-data-get: any company's tech stack, brand and funding by its domain.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through saved_searches_read and changes through saved_searches_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: buyer-preview, email-finds-create, create, import_to_campaign, delete, company-data-get, email-finds-get, get, export_status, get-sample, list, list-technology-companies, list-web-technologies, place-photos, place-reviews, preview-import, run, contact-imports-scan, share, update
buyer-preview
Read. POST https://api.ken.so/v1/contact-imports/buyer-previews
Body (json): campaignId integer, companies array, perCompany integer
Preview the buyers at a list of companies, matched to a campaign's ICP. Up to 50 companies per call, 1 to 3 people each, with a one-line reason and the company's latest signal.
POST /api/v1/contact-imports/buyer-previews. Public. Sends Ken-Version 1.1. Needs the Campaigns page and the Import feature (Admin and Editor). Nothing is written. companies holds 1 to 50 objects with a name, a domain or both, and an optional key that comes back on the row. per_company is 1 to 3 (default 3). The ICP is the union of the filters on campaign_id's active segments (titles, seniority, functions, exclusions, decision maker); data.icp lists them as display labels and is empty when the campaign has none (people are then ranked by seniority). Each company comes back matched, unmatched (unmatchedReason, e.g. "acme.com is not in Kenso Search") or failed (Kenso Search did not answer for it; retry later). A matched company has company (kenCompanyId, name, domain, employeeCount, industry), an optional signal from the last 90 days (kind hiring, funding or leadership_hire, label, at) and people: kenPersonId, fullName, title, seniorityLevel, function, linkedInUrl, reason, weakMatch (true when nobody matched the ICP and Ken filled with the closest people) and contact. Pass the kept people's contact objects unchanged as contacts to contacts(operation="contact-imports-create") with source search to import them. Meters the Kenso Search browse-rows quota for companies times per_company (429 quota_exceeded with Retry-After when spent). A campaign outside the workspace is 404 not_found. Needs the csv_buyer_preview feature (404 while it is off).
email-finds-create
Write. Early access: needs email_finder on for the workspace. POST https://api.ken.so/v1/email-finds
Body (json): companyDomain string, companyName string, firstName string, fullName string, lastName string, linkedinUrl string
Find and verify one person's email by name and company, for any country. 1 credit when an email is found; nothing for a miss. Waits up to 45 seconds for the answer.
POST /api/v1/email-finds, then GET /api/v1/email-finds/{emailFindId} until it ends. Sends
Ken-Version 1.1 and X-Ken-Actor: agent. Behind the email_finder feature.
A name (full_name, or first_name and last_name) and company_domain (the company's website
domain, such as acme.fr) or linkedin_url, or both. company_name is optional. With only
linkedin_url, the domain is the person's current company in Kenso Search, and the find ends
not_found (free) when Kenso Search does not know it. Kenso asks its own
email database, then LeadMagic and Findymail, verifies each answer and keeps the first
safe or verified email. No people record is needed: the person is kept in the workspace. A
person is reused only when they have no email, their email is the one an earlier lookup at
company_domain found, or it is at company_domain; one who already has it gets it back found at
no charge (verification unverified). Parallel calls for the same name and domain are not
merged: send one and wait for it. A person whose lookup is still running gets that find back
(active_find conflict when it is for another company).
Out of credits it refuses with plan_limit_reached before any provider runs. 30 lookups a minute
and 500 a day per workspace; a refused call (validation, credits, scope, conflict) or one that
gets a running find back does not count.
wait (default true) polls until the find is found, not_found, failed or paused, for up to 45
seconds. With wait=false, or when it is still working, read it again with
saved_searches(operation="email-finds-get", email_find_id=...).
Returns data: id, personId, status (queued, running, paused, found, not_found, failed),
pausedReason (credits or member_limit), email, provider, verification {status: safe, verified or
unverified, verifiedBy}, companyDomain, costCredits, error, createdAt, completedAt.
create
Write. POST https://api.ken.so/v1/saved-searches
Create a saved search. client_id, name, search_type and filters_json are required.
POST /api/v1/saved-searches. Public. Sends Ken-Version 1.1, client_id as X-Ken-Workspace-Id.
Args:
name: Search name. Required.
search_type: "People", "Account" (a company search), "JobPosts" or "Places".
Required. Parsed case-insensitively by the backend; any other value is a 400.
filters_json: Search filters as a JSON object or JSON object string. Required.
Compact JSON strings that the MCP layer pre-parses into a dict are
accepted; the object is stringified onto Search filtersJson.
is_shared: Legacy org-wide read flag (default false).
client_id: Workspace id, sent as X-Ken-Workspace-Id. Required.
Returns the new SavedSearchResponseDTO (fields as in saved_searches(operation="get")).
import_to_campaign
Write. POST https://api.ken.so/v1/search/imports
Body (json): campaignId integer, limit integer, personIds array, searchFilters any JSON
Action: IMPORT (people search results -> Kenso campaign contacts).
Action: IMPORT (people search results -> Kenso campaign contacts).
Despite the legacy "export" in some backend path names, this tool IMPORTS
people from the Kenso Search index into a target campaign. Data flows
search -> campaign, not the other way around. There is currently no
companion CSV-export tool against the search index; use
``contacts(operation="export_contacts")`` for campaign CSVs instead.
Emails: a person whose search result carries hasKenEmail=true already has an
email Kenso holds, and on a paid plan that address costs no email find. Count
a selection first with saved_searches(operation="preview-import", ...),
which takes the same selection without the campaign and imports nothing.
Scope:
- People-only. Account-based imports are not supported by this endpoint;
there is no account_filters_json counterpart.
- The import lands in the campaign's default contact pool. There is no
segment_id or list_id parameter; segment/list assignment must be done
separately via the campaign segment/list management tools after import.
Duplicate handling:
- The backend de-duplicates against existing campaign contacts (skip on
existing match, typically by email/LinkedIn URL). New contacts are added;
existing ones are not overwritten.
- For filter-based imports (``select_all=True``), Kenso Search seeds a
skip-set of the people already in the campaign (under its de-duplication
scope) BEFORE selecting candidates, so each pagination round collects
genuinely net-new people. Importing into an already-populated campaign
therefore reliably adds net-new contacts instead of re-feeding the same
already-imported top results and landing ~0 net-new (the prior bug).
``campaignImport.totalSkippedAlreadyInCampaign`` reports how many
candidates were skipped this way.
- This call is NOT idempotent on retry: re-running with the same inputs
will not create duplicates of already-imported contacts, but any newly
matching person not yet in the campaign will be added on each retry.
Avoid blind retries; check the response counts first.
Args:
campaign_id: Target campaign ID in Kenso
select_all: Import all results matching the filters (mutually exclusive
with selected_person_ids in practice; prefer one or the other)
selected_person_ids: Specific Kenso person IDs to import
(List[int]) - note this is the Kenso person ID type. Required when
select_all is False. Ignored when select_all is True.
people_filters_json: PeopleSearchRequest filters as a JSON object or
JSON object string. Required when select_all is True, ignored
otherwise. Compact JSON strings that the MCP layer pre-parses into a
dict are accepted. A clientId inside it is dropped: the workspace is
the client_id argument. inLinkedInConnections: true imports only the
workspace's LinkedIn connections, read when the import starts (no
feature check; a workspace with none imports nobody).
import_limit: Target number of net-new campaign contacts to import.
Only for select_all=True imports; with selected_person_ids it is a
validation error (pass only the ids you want imported).
For filter-based imports, Kenso Search may attempt additional
candidates after backend duplicate skips until this target is met,
the search is exhausted, or a safety cap is reached. The backend
enforces its own server-side cap; values above that cap are clamped
server-side. Pass a conservative value (e.g. <=1000) for
predictable behavior.
await_ready: When True (the default) the tool blocks until the import
job reaches a terminal state (Ready/Failed/Expired) or a bounded
~60s timeout elapses, polling GET /v1/search/imports/{job_id} every
2s server-side. This makes the import a single, finished call - use
it when you need the imported contacts to have landed before the
next step (e.g. prompt-testing a sample). When False the tool
preserves the legacy behavior: it returns the enqueue receipt
immediately and you poll ``saved_searches(operation="export_status", job_id=...)`` yourself.
client_id: Optional workspace id, sent as X-Ken-Workspace-Id. The
campaign must belong to that workspace.
Returns:
With ``await_ready=False`` (legacy): the raw enqueue receipt from
POST /v1/search/imports, typically
``{"success": True, "data": {"jobId": ..., "status": "Queued", ...}}``.
With ``await_ready=True`` (default): a blocking result that reports the
final (or last-known, on timeout) job status and the record counts:
- success (bool): Always True when the import was accepted (the call
degrades gracefully on poll timeout rather than erroring).
- jobId: The import job id that was polled.
- status (str | None): Backend status string ("Ready", "Processing",
"Failed", "Expired", ...). None only if status could not be read.
- totalRecords / processedRecords (int | None): ``totalRecords`` is
the requested target; ``processedRecords`` is the cumulative net-new
contacts imported so far.
- campaignImport (dict | None): Fill-to-target progress from the
Search API when present, including requestedTarget, totalImported,
totalSkippedDuplicate, totalSkippedAlreadyInCampaign,
totalCandidatesAttempted, exhausted, stopReason, roundsCompleted,
and batches.
- timedOut (bool): True when the ~60s budget elapsed before a terminal
state; a ``warning`` is added and ``status`` is the last-known value.
- polling: The canonical polling envelope (download_url, progress, ...).
- enqueue: The original POST /v1/search/imports receipt.
If the enqueue receipt carries no job id (e.g. a synchronous backend
that returns inline counts), the receipt is returned unchanged - there
is nothing to await.
Routes: POST /api/v1/search/imports (search.create-import), then, with
await_ready, GET /api/v1/search/imports/{importId} until the job is
terminal. Public. Sends Ken-Version 1.1. Requires Campaigns edit and the
`import` permission, plus Search view.
delete
Write. DELETE https://api.ken.so/v1/saved-searches/{savedSearchId}
Path: savedSearchId
Delete a saved search. Only the owner may delete.
DELETE /api/v1/saved-searches/{savedSearchId}. Public. Sends Ken-Version 1.1.
Args:
search_id: The saved search id. Required.
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
company-data-get
Read. GET https://api.ken.so/v1/company-data
Query: domain string, kinds string
Get a company's brand, technologies and funding by its website domain. Free, except branding. domain is required (acme.com or a URL). kinds is any of brand, technologies, funding, branding (default brand, technologies and funding; branding only when named).
GET /api/v1/company-data. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Query keys domain and kinds
(comma-separated). The domain is looked up as its registrable domain (acme.com for
https://www.eu.acme.com/about); a free email domain such as gmail.com is refused.
Returns data.domain, data.isCompanyFound (whether Kenso has the domain's company; absent when
neither brand nor funding was asked for) and one object per kind Kenso has data for (a kind is
absent when it was not asked for or Kenso has nothing for it):
- brand: name, description, logoUrl.
- technologies: items [{name, categories, lastSeenAt}], most recently seen first, at most 200,
plus capturedAt (when Kenso's archived copy of the home page was captured). An empty items list
means Kenso has the site and detected no technologies.
- funding: totalFunding and each round's amount as money {amount in cents, currency usd},
lastRound {type, amount, announcedDate YYYY-MM-DD} and rounds newest first, at most 20.
lastRound carries only announcedDate when Kenso knows a raise newer than every listed round.
- branding (only when kinds names it, and only where Kenso turned it on; elsewhere 400 unknown
kind): logoUrl, faviconUrl, socialImageUrl, colors {primary, secondary, accent, background,
text, link} as #RRGGBB, fonts [{family, role}], colorScheme (light or dark), read from the
company's live home page.
Each kind carries source (ken_search; website for branding) and fetchedAt.
Use it during account research to cite a company's tech stack, funding and logo. For a
company's people or a company search use the search tool. Cost: free. An answer with a found
company or technologies counts one row of the workspace's daily Search browse quota
(429 quota_exceeded past it), and so does every request that names branding, also when it
finds none or ends in 402 (one row per request). branding costs credits as one web page
read when it finds a branding (free on the workspace's own Firecrawl key, free when it
finds none); a read is kept
30 days and shared, so a repeat lookup in that time is free. 402 plan_limit_reached when the
workspace has no credits for it.
email-finds-get
Read. Early access: needs email_finder on for the workspace. GET https://api.ken.so/v1/email-finds/{emailFindId}
Path: emailFindId
Read one email find: its status and, once found, the email and its verification.
GET /api/v1/email-finds/{emailFindId}. Sends Ken-Version 1.1. Behind the email_finder feature.
The find saved_searches(operation="email-finds-create") queued. status is queued, running or
paused while it works (pausedReason credits or member_limit), then found, not_found or failed
(error says why; a failed find may be asked again). Found, it carries email, provider and
verification {status: safe, verified or unverified, verifiedBy}, and costCredits is what it
charged. Another workspace's find is not found.
get
Read. GET https://api.ken.so/v1/saved-searches/{savedSearchId}
Path: savedSearchId
Get one saved search by id. 403 without read permission, 404 if missing.
GET /api/v1/saved-searches/{savedSearchId}. Public. Sends Ken-Version 1.1.
Args:
search_id: The saved search id. Required.
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
Returns a SavedSearchResponseDTO. Response fields: id, clientId, userId, ownerId,
ownerName, name, searchType, filtersJson, resultCount, currentCount, isShared,
sharedWithMe, orgWide, permissions (the caller's: read, edit, admin or none),
createdAt, cachedAt, lastExecutedAt.
export_status
Read. GET https://api.ken.so/v1/search/imports/{importId}
Path: importId
Check the status of a search import/export job.
Check the status of an export job, or recover the latest durable import
job for a campaign after the caller lost its job ID.
The original backend payload is preserved (PascalCase ``Status``,
``Progress``, ``DownloadUrl``, etc. when present). A canonical ``polling``
envelope is also attached so callers can branch on a stable contract:
{
"status": "pending"|"processing"|"completed"|"failed"|"unknown",
"progress_percentage": float | None,
"download_url": str | None,
"total_rows": int | None,
"processed_rows": int | None,
"error_message": str | None,
"export_id": str | None,
}
The same envelope shape is emitted by ``db(operation="status")``,
so a single polling helper works against both tools.
Routes: GET /api/v1/search/imports/{importId} (search.get-import) for
job_id, or GET /api/v1/search/imports?campaignId= to recover the latest job
of a campaign. Public. Sends Ken-Version 1.1.
Scope: search-result-scoped. Polls the status of a job created by
``saved_searches(operation="import_to_campaign")``. Does NOT track campaign exports started by
contacts(operation="export_contacts") (those return synchronous fileUrls instead) and does
NOT track DB exports started by db(operation="create") (use
db(operation="status") for those).
Args:
job_id: Export job ID (from the import_to_campaign response).
Mutually exclusive with campaign_id.
campaign_id: Campaign ID whose latest recoverable Search import should
be returned. Use this after a page reload, client restart, or lost
enqueue receipt. Mutually exclusive with job_id. Legacy imports
created before durable payload persistence may not be recoverable.
client_id: Workspace ID, sent as X-Ken-Workspace-Id. Required with
campaign_id so recovery cannot cross tenant boundaries. Optional with
job_id; when supplied, it permits another authorized member of the
same workspace to poll the import created by a teammate.
Returns:
Provider payload plus a canonical ``polling`` envelope. The provider
payload mirrors backend ``ExportStatusDTO`` (jobId, status,
totalRecords, processedRecords, downloadUrl, errorMessage, createdAt,
completedAt, campaignImport). For campaign import jobs,
``campaignImport`` is also promoted to the top level when present.
Branch on ``polling.status`` for a stable contract that is shared with
``db(operation="status")``.
get-sample
Read. GET https://api.ken.so/v1/search/sample
Get the workspace's sample search: people, companies, job posts and funding picked from its ICP. Public. Free, cached for the workspace, never saved. Off unless the search_sample flag is on.
GET /api/v1/search/sample. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Requires Search view.
Answers at once and never waits for a build. data.status is one of:
- ready: the sample. refreshing is true while a rebuild runs (the ICP changed or the sample expired).
- pending: nothing cached yet and a build is queued or running; call again in about 5 seconds.
- unavailable: no ICP context yet (website context or ICP Knowledge file), or the last build for this ICP
failed (retried after 10 minutes when the model or a search was down, after 6 hours when it found nothing),
or the workspace ran its 6 builds of the day with no sample to serve.
- off: the search_sample flag is off for the workspace; nothing runs.
A ready sample has generatedAt, expiresAt (7 days), query (the filters it searched: titles, seniorityLevels,
industries, headcountMin, headcountMax, countries, hiringTitles, fundingMinRaisedUsd, fundingRaisedWithinDays,
fundingIndustryGroups) and up to four tabs, each absent when its search failed or found nothing:
profiles and companies ({request, page}), jobs ({request: {jobFilters, peopleFilters}, companies, people})
and funding ({request: {signalType, parameters}, page}). Each request is the body the Search page sends,
so search(operation="search-people", ...) with profiles.request runs the full search.
list
Read. GET https://api.ken.so/v1/saved-searches
Query: cursor string, limit integer
List the saved searches the caller can see: own, shared and org. client_id is required. page_size (default 50, max 100) and cursor page the list.
GET /api/v1/saved-searches. Public. Sends Ken-Version 1.1, client_id as X-Ken-Workspace-Id.
Args:
client_id: Workspace id, sent as X-Ken-Workspace-Id. Required.
page: 1-based page number (default 1). Pages after the first walk the
earlier ones, so prefer cursor past page 3.
page_size: Page size (default 50, max 100).
cursor: pagination.nextCursor from the previous result. Replaces page.
Each row is a SavedSearchResponseDTO. Response fields: id, clientId, userId,
ownerId, ownerName, name, searchType, filtersJson, resultCount, currentCount,
isShared, sharedWithMe, orgWide, permissions (the caller's: read, edit, admin or
none), createdAt, cachedAt, lastExecutedAt.
list-technology-companies
Read. Early access: needs search_technologies on for the workspace. GET https://api.ken.so/v1/search/technologies/{technology}/companies
Path: technology
Query: cursor string, includeTotal boolean, limit integer
List companies whose website runs a technology (Shopify, HubSpot, WordPress, ...). No credits, but each row counts on the daily browse quota. Each company has its domain, the technology's name and categories and its Kenso Search company id.
Behind the workspace's search_technologies flag. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. It runs
POST /api/v1/search/companies with webTechAny [the technology key], the company technology filter. Until that
filter launches, company search answers 400 validation_failed, "Technology filters are not enabled.", and the
operation runs GET /api/v1/search/technologies/{technology}/companies instead (the web corpus's own list of the
domains that run it). It moves to company search by itself at launch. Any other error comes back as it is.
technology is a technology key (shopify, hubspot, google-analytics) or its name (HubSpot, Google Analytics); a
name becomes its key by the catalog key rule (lowercase, each run of other characters one dash), so both find the
same companies. saved_searches(operation="list-web-technologies") lists the keys. Detection comes from Kenso's web
corpus: the technologies found for each domain (its own site's pages, DNS records and job posts). No vendor is
called and no credits are spent, but every returned row counts on the workspace's daily searchBrowseRows quota,
like a company search page; past it the call answers 429 quota_exceeded. Page only as far as you need.
limit is 1-100 (default 50). cursor is pagination.nextCursor from the previous page, and it pages only the route
that returned it. When a later page ends exactly at the last company, hasMore can still be true and the next page
is empty: stop at an empty page. include_total=True adds pagination.totalCount, every company detected running it.
Returns data, a list, each with domain, technology {key, name, categories, sources, lastSeenAt}, description,
coverage, and company {kenId, name, website, linkedInUrl}. A technology nobody runs is an empty list.
- From company search: rows in company search's default order, every one a Kenso Search company. description is the
company's profile description. sources, lastSeenAt and coverage are null: company search does not carry them.
- Before launch, from the web corpus list: rows ordered by domain. technology.sources (commoncrawl, httparchive,
live, dns, jobs) and lastSeenAt say how and when it was seen on that domain, description is the domain's home
page description, coverage is pages (Kenso holds its pages) or evidence (technologies only), and company is null
when Kenso Search has no company with that domain. 503 service_unavailable while the web corpus read is off.
To narrow by country, size or industry as well, call search(operation="search-companies") with webTechAny and the
other company keys once the filter has launched.
To find people at these companies, pass the company.kenId values as account_ids to
search(operation="people_in_accounts", account_ids=[...]). The domains feed
accounts(operation="bulk-create") or a saved list upload the same way company search results do.
list-web-technologies
Read. Early access: needs search_web_tech on for the workspace.
List the technologies Kenso detects for companies (websites, DNS records, job posts), or their categories. Read-only, behind the search_web_tech flag. Use the keys it returns in the webTech* company search keys and the companyWebTech* people search keys.
GET /api/v1/search/metadata. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Behind the workspace's search_web_tech flag (off: not available). kind is "technology" (default) or "category". A technology item has value (the key to put in webTechAny, webTechAll, webTechExclude or the companyWebTech* people keys), label (display name), count (companies detected running it) and type (its first category). A category item has value (the key for webTechCategories and companyWebTechCategories), label and count. q filters by text (at most 100 characters). limit is 1-100 (default 25). cursor is pagination.nextCursor from the previous page. While the feature is off in Search, the call fails with 400 validation_failed, "Technology filters are not enabled." (Search's web_tech_filters_disabled), as the technology search keys do.
place-photos
Write. Early access: needs search_places on for the workspace. GET https://api.ken.so/v1/search/places/{placeId}/photos
Path: placeId
List a Google Maps place's photo URLs. An open: free up to 500 opens a day per workspace, then 0.1 credits.
GET /api/v1/search/places/{placeId}/photos. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
place_id is a plc_ id from a places search. Returns data.placeId, data.photos ([{url}], up
to 100) and data.charge. Cost: an open, priced like opening the place.
place-reviews
Write. Early access: needs search_places on for the workspace. GET https://api.ken.so/v1/search/places/{placeId}/reviews
Path: placeId
Query: cursor string, sort string
List a Google Maps place's reviews, one page at a time. Each page is an open: free up to 500 opens a day per workspace, then 0.1 credits.
GET /api/v1/search/places/{placeId}/reviews. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
place_id is a plc_ id from a places search. sort is relevant (default), newest,
highest_rating or lowest_rating. cursor is pagination.nextCursor from the previous page.
Returns data.placeId, data.reviews, data.charge and data.pagination {hasMore, nextCursor}.
Cost: each page is an open, priced like opening the place.
preview-import
Read. POST https://api.ken.so/v1/search/imports/preview
Body (json): limit integer, personIds array, searchFilters any JSON
Count how many people of an import selection Kenso already holds an email for. Imports nothing. Same selection as import_to_campaign, without campaign_id.
POST /api/v1/search/imports/preview. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Takes the selection saved_searches(operation="import_to_campaign", ...) would import: selected_person_ids, or select_all=True with people_filters_json (and import_limit, 5,000 when absent). Returns data: - personCount: the people the import would take. - checkedCount: the people checked, the first 500 in import order. Below personCount for a larger selection or when picked people left Search. - kenEmailCount: of the checked people, how many Kenso already holds a recently verified email for (hasKenEmail=true in search results). On a paid plan an email Kenso already holds costs no email find, so kenEmailCount is how many finds that import saves; on Free each is still a find. Needs the Search page. Counts no Search quota.
run
Write. POST https://api.ken.so/v1/saved-searches/{savedSearchId}/run
Path: savedSearchId
Re-run a saved search by id and return fresh results. Rows are compact. 403 without read permission, 404 if missing.
POST /api/v1/saved-searches/{savedSearchId}/run. Public. Sends Ken-Version 1.1.
Args:
search_id: The saved search id. Required.
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
Rows are compact, the same fields as search(operation="search-people") or
search(operation="search-companies"); search(operation="get-person") and
search(operation="get-company") return the full record.
contact-imports-scan
Read. POST https://api.ken.so/v1/contact-imports/scans
Body (json): campaignId integer, headers array, keys object, sampleRows array, savedListId integer, savedListKind string, source string, target string
Suggest the Kenso field of every column of an import file before importing it, and check the list. Send the header row and sample rows; returns each column's target field, confidence, reason, samples and cleanup. Send keys too for the List check: what the import skips, recently emailed rows, risky rows and a bounce estimate.
POST /api/v1/contact-imports/scans. Public. Sends Ken-Version 1.1. Needs campaigns view and the import feature;
target saved_list also needs Search view (else 403) and the saved_lists feature (not found while it is off).
source is csv, google_sheets or airtable. target is campaign (the
default: campaign_id, a campaign of the workspace, is then required),
people, or saved_list (then send exactly one of saved_list_id, one of the
workspace's own lists, where a shared or library list or another member's
private list is not found, or saved_list_kind, people or companies, for a
list not created yet). headers is the file's header row (1 to 200 names, each at most
500 characters); sample_rows are up to 200 data rows (a short row reads as
blanks, extra cells are ignored, each cell at most 2,000 characters).
keys runs the List check (target campaign or saved_list): rowCount (data rows in
the file), cleanup (each value first goes through the import's cleaner;
default true, and false with target saved_list, whose upload cleans
only with cleanup=true) and one list per mapped key field (email, profileUrl,
companyDomain, companyName, companyLinkedinUrl, firstName, lastName,
fullName, title, emailValidity; snake_case names are accepted), plus
otherEmails (a list per further column mapped to email, up to 10: the
import keeps every valid address of a row) and otherEmailValidity (the
validity column right after each, null where none). Every list has the
same length, 1 to 25,000, and rowCount is at least that length (else
400 on keys); a larger file sends its first 25,000 rows and its check
is truncated. A scan that sends keys skips the AI step. Nothing is stored;
Kenso's own data only, no paid lookup.
data.columns holds one entry per header, in order: index, csvColumn,
targetField (a contact field such as email, full_name, profile_url,
title, company_name or company_domain, custom_variable, or skip),
customVariableName (custom_variable only), confidence (high: the header
names the field or nearly every value is one; memory: this workspace
mapped the header before; check: likely, confirm it; skip: not
imported), reason, samples (up to 3 values) and cleanup (what the
import's cleanup changes in the samples, e.g. "Cleans 3 of 10 sample
values (casing, format)", else null). data.listKind is company when no
column is a person field and one is a company field, else people.
data.check (null without keys or with target people): rows,
scannedRows, truncated, cleanupApplied; always, the rows the import
skips anyway, first match wins: failedValidation, missingKey,
blocklist, duplicateInFile, duplicateInCampaign,
duplicateInOtherCampaign (each key, label, count, samples
[{row, value, reason}], rows); contacted (rows another campaign emailed
inside the campaign's recently-emailed window: count, days,
skipByDefault, samples, rows); checks, the optional fixes in order
invalidEmail, noMx, catchAll, personalEmail, roleAddress,
companyContacted, companyCap (key, label, fixLabel, count, defaultOn,
prior, note, samples); rowFlags ([rowIndex, mask]; bits 1 contacted,
2 invalidEmail, 4 noMx, 8 catchAll, 16 roleAddress, 32 personalEmail,
64 companyContacted, 128 companyCap); noEmailRows; baselinePrior;
bounce (expected and beforeFixes in percent, band green under 2, amber
2 to 5, red over 5; null with no email); willAdd;
companyContactedDays; companyCap; domainsChecked; domainsTotal;
titleMix and providerMix ([{label, share}], shares sum to 100). A
sample's row is the 1-based data row; rows and rowIndex are 0-based
into the key lists.
With target saved_list the check reads each row as the list's upload
does and checks it against the list. always holds missingKey (no
LinkedIn URL, email, or name and company domain; for a company list no
company domain or company page: the upload rejects the row),
duplicateInFile and duplicateInList (the row merges into an earlier
row's member or the list's member, and is not checked against the
fixes: its addresses join that member). checks holds blocklist (on by
default; rowFlags bit 256), invalidEmail, noMx, catchAll, personalEmail
and roleAddress; the campaign-only checks are left out, so contacted is
empty (count 0, days null) and companyContactedDays and companyCap are
0. emailValidity is not read: a list never trusts an uploaded verdict.
willAdd is the members the list gains with the defaults. Pass the fixes
left on as fixes to saved_lists(operation="create-upload"). With
saved_list_kind the rows are read and keyed as a new list of that kind
reads them and nothing is on it yet: duplicateInList is 0 and willAdd is
the rows the new list gets.
A field is suggested once, except
email, email_validity and custom_variable; target people suggests only
the fields a people import stores: email, first_name, last_name,
full_name, title, company_name, company_domain, phone_number and
profile_url. Pass the columns you keep (targetField not skip) as
column_mappings to contacts(operation="contact-imports-create").
Behind the csv_import_check feature (404 while it is off). Each call
counts on the workspace's contactImportScans quota (30 a minute, 600 an
hour, 5,000 a day; past it, 429 quota_exceeded).
share
Write. POST https://api.ken.so/v1/saved-searches/{savedSearchId}/share
Path: savedSearchId
Grant or revoke access to a saved search for a user or an org. Needs owner or admin permission. Grants need permission (read, edit or admin).
POST /api/v1/saved-searches/{savedSearchId}/share. Public. Sends Ken-Version 1.1.
Args:
search_id: The saved search id. Required.
share_action: "grant"/"share" or "revoke"/"unshare". Typed alias for action.
action: "grant"/"share" or "revoke"/"unshare". Defaults to grant, left to the
backend when omitted.
target_type: "user" or "org". Required.
target_id: The user id for user targets (required); for org targets it is a
client id and defaults to the saved search's clientId.
permission: For grants, "read", "edit" or "admin" (required for grants).
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
Returns the updated SavedSearchResponseDTO (fields as in saved_searches(operation="get")).
update
Write. PATCH https://api.ken.so/v1/saved-searches/{savedSearchId}
Path: savedSearchId
Update a saved search's name, filters_json or is_shared. Absent fields stay unchanged. Needs edit permission; is_shared needs owner or admin.
PATCH /api/v1/saved-searches/{savedSearchId}. Public. Sends Ken-Version 1.1.
Args:
search_id: The saved search id. Required.
name: New name (edit or admin permission).
filters_json: New filters as a JSON object or JSON object string (edit or
admin permission), stringified onto Search filtersJson.
is_shared: Legacy org-wide read flag. Only the owner or an admin may change it.
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
Returns the updated SavedSearchResponseDTO (fields as in saved_searches(operation="get")).