Kenso MCP tools

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")).