Saved Lists saved_lists
People lists: saved lists of people or companies (saved_list_id), the workspace's own, lists other workspaces shared with it, and Kenso's approved library. Build, copy, share and submit them; members and sources are operations here too. A receiving workspace reads and accepts an invite with invites-get and invites-accept. Not a campaign's contact import lists: those are the lists tool, with their own ids, and delete here never takes a list_id from it.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through saved_lists_read and changes through saved_lists_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: invites-accept, confirm-rights, copy, create, create-invite, create-source, create-upload, delete, invites-get, get, get-source, list, list-grants, list-members, refresh, refresh-source, remove-member, revoke-grant, submit, update
invites-accept
Write. POST https://api.ken.so/v1/saved-list-invites/{token}/accept
Path: token
Accept a saved-list invite into a workspace; the list becomes readable there, read-only. The signed-in person must be the invited address. An invite is accepted once.
POST /api/v1/saved-list-invites/{token}/accept. No body. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id, the workspace that receives the list. Public. Needs the saved_lists
feature. Requires the Search page at edit in that workspace.
Returns the grant with status accepted, receivingWorkspaceId, receivingWorkspaceName and
acceptedAt. A caller whose email is not the invited address is forbidden. An invite already
accepted, or one accepted into the workspace that owns the list, is invalid_state. A
workspace that already holds the list is conflict. A revoked or unknown invite is not_found.
confirm-rights
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/rights-confirmation
Path: savedListId
Record that this workspace may share the people it uploaded by CSV to one of its saved lists. Needed once before inviting anyone to such a list. Ask the person first: it is their statement.
POST /api/v1/saved-lists/{savedListId}/rights-confirmation. No body. Sends Ken-Version 1.1.
Public. Needs the saved_lists feature. Requires the Search page at edit and the share
feature.
Records the calling member and the time (a later confirmation replaces both). An API key
that belongs to no member is forbidden, because the confirmation must name a person. Returns
the list: id, kind, visibility, access (owner), name, icpTags, libraryState,
publicPageEnabled, ownerUserId, createdByUserId, rightsConfirmedAt, hasCsvMembers, counts,
sources, createdAt, updatedAt. Another workspace's list, or another member's private list,
is not_found.
copy
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/copy
Path: savedListId
Body (json): memberFilters object, name string
Copy a saved list you can read into a new list of this workspace, owned by you. Returns 201. Works on your own lists, lists shared with you and library lists; member_filters copies a subset.
POST /api/v1/saved-lists/{savedListId}/copy. Public. Sends Ken-Version 1.1. Needs
the saved_lists feature. Requires the Search page (edit).
name defaults to "<name> (copy)". member_filters (all optional): country,
seniority, industry, headcount_band (exact stored values), title (contains) and
has_sendable_email (true or false); each text value at most 200 characters.
Opted-out members are never copied. More than 500,000 matching members is
validation_failed too_many_members. The new list is visibility workspace with one
list source; members copied from a library list stay library data.
create
Write. POST https://api.ken.so/v1/saved-lists
Body (json): description string, icpTags array, kind string, name string, visibility string
Create an empty saved list of people or companies, owned by you. Returns 201. visibility workspace (default) or private (only you see it).
POST /api/v1/saved-lists. Public. Sends Ken-Version 1.1. Needs the saved_lists feature. Requires the Search page (edit). name 1-200 characters. kind people or companies. description up to 2000 characters. visibility workspace (everyone in the workspace sees it, the default) or private (only the owner user sees it; a caller with no user, such as an API key, gets validation_failed user_required). icp_tags up to 20 tags of at most 50 characters each; a repeat counts once. The list starts empty: add members with saved_lists(operation="create-source") or a CSV upload.
create-invite
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/invites
Path: savedListId
Body (json): email string
Invite an email address to read one of this workspace's saved lists. Returns 201 and the pending grant. The invitee gets an email link and picks the workspace that receives the list, read-only.
POST /api/v1/saved-lists/{savedListId}/invites. Sends Ken-Version 1.1. Public. Needs the
saved_lists feature. Requires the Search page at edit and the share feature.
email: the invitee's address. A grant: id, savedListId, inviteeEmail, status (pending,
accepted, revoked), receivingWorkspaceId and receivingWorkspaceName once accepted,
invitedByUserId, acceptedAt, revokedAt, createdAt. The response carries no token: only the
invitee's email has the link. Only this workspace's own lists can be shared: a library list,
another workspace's list or another member's private list is not_found, and your own private
list is invalid_state (make it visible to the workspace first). A list with CSV-uploaded
members, or a CSV upload still running, needs the confirm-rights operation first, else
rights_confirmation_required (409). A second invite to an address with a pending invite on
the list is conflict. The grant is created even when the email cannot be sent; revoke it and
invite again to resend.
create-source
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/sources
Path: savedListId
Body (json): parameters any JSON, sourceType string
Add a source to a saved list: Kenso Search filters, picked people, a saved search, a campaign or another list. Answers 202 with the source in pending; poll it with the get-source operation until done or failed.
POST /api/v1/saved-lists/{savedListId}/sources. Public. Sends Ken-Version 1.1. Needs the
saved_lists feature. Requires the Search page (edit); a campaign source also needs the
Campaigns page (view). Works on your workspace's own lists only.
source_type and its parameters (camelCase keys, as the Kenso API takes them):
- search_filters: a Kenso Search people-search body, for example
{"currentTitles": ["vp sales"], "countries": ["US"]}. page, pageSize and searchAfter
are dropped; at least one filter is required (no_criteria otherwise).
- search_selection: {"personIds": [...]}, 1 to 1,000 Kenso Search person ids.
- saved_search: {"savedSearchId": N}, one of your people saved searches. It runs as you
every time the source runs.
- campaign: {"campaignId": N}, a campaign of this workspace; copies its contacts once.
- list: {"savedListId": N}, another list you can read (your own, one shared with this
workspace, or a library list), not this one; copies its members once.
A company list takes only a list source of another company list. A list holds at most
50 sources. Search sources (search_filters, search_selection, saved_search) refresh;
campaign and list sources copy once, so add them again to copy again.
Returns the source: id, sourceType, parameters, status (pending, running, done,
failed), statusMessage, addedByUserId, lastRefreshedAt, lastRefreshAdded, createdAt.
Errors: 404 not_found for a list you cannot see (another workspace's, or another
user's private list). 400 validation_failed with error.details[] of {field, code,
message}: sourceType required, invalid or kind_mismatch; parameters required;
parameters.<field> required, invalid, out_of_range, no_criteria, not_found, self or
kind_mismatch; sources limit_reached.
create-upload
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/uploads
Path: savedListId
Add a CSV's rows to one of the workspace's saved lists; Kenso adds them in the background.
Uploads the CSV and returns the new ``csv`` source in ``pending`` (HTTP 202). Kenso adds the
rows in the background: read the source with the saved-lists get-source operation until
``status`` is ``done`` or ``failed``. Its ``parameters`` then carry ``rowCount``,
``inserted``, ``merged`` (rows that matched a member already on the list) and ``rejected``
(rows with no LinkedIn URL, email, or name plus company domain; for a company list, no
domain or company LinkedIn page; and rows a chosen fix skipped, counted by fix key in
``skips``).
Uploaded emails enter unverified. Every phone is kept. Columns that hold personal data
(birth date, gender, age, personal email and the like) are never stored. At most 100,000
rows and 400 MB per upload.
Args:
saved_list_id: The list to add to. Only the workspace's own lists; a list shared with
the workspace or a library list is not found.
csv_content: The CSV text, header row first. The hosted MCP cannot read files from
your machine, so send the text.
file_path: Names the upload when it ends in .csv; read from disk only when
csv_content is not given.
column_mappings: Optional list of {csv_column, target_field, custom_variable_name?},
the contact-import mapping shape. target_field is one of first_name, last_name,
full_name, title, seniority_level, company_name, company_domain,
company_industry, company_employee_count_range, company_linkedin_url, country,
state, city, profile_url, email, phone_number, or custom_variable with
custom_variable_name. Omit it to map the columns by their headers.
client_id: The workspace that owns the list.
fixes: Optional List check fixes to apply: the checks left on after
saved_searches(operation="contact-imports-scan") with target saved_list. Keys:
blocklist, invalidEmail, noMx, catchAll, personalEmail, roleAddress (missingKey is
accepted and changes nothing). The rows the check flags for them are skipped; a row
already on the list, or a repeat of a kept row, still merges into its member with
all its addresses (a fix skips rows, never one address). Behind the csv_import_check
feature (the API answers 400 on the field while it is off).
cleanup: True runs every cell of a field with its own cleaner (names, titles,
companies, domains, emails, LinkedIn URLs, phones) through the import cleaner first.
Behind csv_import_check too. Omitted or false: today's upload. A saved_list scan
without keys.cleanup checks the rows the same way, uncleaned.
delete
Write. DELETE https://api.ken.so/v1/saved-lists/{savedListId}
Path: savedListId
Delete one of the workspace's saved lists (people or company lists; soft delete). Returns 204. A shared or library list is not_found here. Not a campaign import list: those are lists(operation="delete").
DELETE /api/v1/saved-lists/{savedListId}. Public. Sends Ken-Version 1.1. Needs the
saved_lists feature. Requires the Search page (edit).
A library copy approved from the list is a separate list and stays.
Campaign lists and saved lists number their ids separately: an id that is
not a saved list of this workspace but is a campaign import list is refused,
naming that list and pointing at lists(operation="delete") (DEV-8724).
invites-get
Read. GET https://api.ken.so/v1/saved-list-invites/{token}
Path: token
Read a saved-list invite from its link token: list name, kind, size and who shared it. Needs no workspace. Read it before accepting.
GET /api/v1/saved-list-invites/{token}. Sends Ken-Version 1.1 and no workspace. Public.
Needs the saved_lists feature. Any signed-in caller.
token: the 43 characters after /lists/accept/ in the invite link. Returns token, listName,
kind (people or companies), memberCount, ownerWorkspaceName and status (pending, accepted,
revoked; only a pending invite can be accepted). An unknown token or a deleted list is
not_found. The members stay unreadable until the invite is accepted.
get
Read. GET https://api.ken.so/v1/saved-lists/{savedListId}
Path: savedListId
Get one saved list with its counts and sources. Own, shared with the workspace, or an approved library list; anything else is not_found.
GET /api/v1/saved-lists/{savedListId}. Public. Sends Ken-Version 1.1. Needs the
saved_lists feature. Requires the Search page (view).
Returns the list as saved_lists(operation="list") describes it. Another user's
private list, a list of another workspace without an accepted invite and a library
list that is not approved are all not_found.
get-source
Read. GET https://api.ken.so/v1/saved-lists/{savedListId}/sources/{sourceId}
Path: savedListId, sourceId
Read one source of a saved list: its status and what its last run added. Poll it after create-source, refresh-source or refresh until status is done or failed.
GET /api/v1/saved-lists/{savedListId}/sources/{sourceId}. Public. Sends Ken-Version 1.1.
Needs the saved_lists feature. Requires the Search page (view). Works on your
workspace's own lists only.
status pending or running: the run has not finished, poll again in a few seconds.
done: lastRefreshAdded counts the people the last run added; statusMessage notes rows
it skipped (no LinkedIn URL, email, or name with company domain) or the row cap it hit.
failed: statusMessage says why. A source that is not on that list, or a list you
cannot see, is 404 not_found.
list
Read. GET https://api.ken.so/v1/saved-lists
Query: cursor string, icpTag string, kind string, limit integer, q string, scope string, slug string
List saved lists: the workspace's own, the ones shared with it, or Kenso's library. Filter by kind, name (q), ICP tag or a library slug; pagination.total counts every match.
GET /api/v1/saved-lists. Public. Sends Ken-Version 1.1. Needs the saved_lists
feature. Requires the Search page (view).
scope: own (default; a private list only for its owner user), shared (lists other
workspaces shared with this one through an accepted invite) or library (approved
library lists). kind: people or companies. q: name contains, any case. icp_tag: one
tag, matched exactly. slug: with scope library only, the one library list with that
slug (or none). limit 1-100 (default 50); cursor is the previous page's
pagination.nextCursor.
A list: id, kind, visibility (private, workspace, library), access (owner, shared,
library), name, description, slug, icpTags, libraryState, publicPageEnabled,
ownerUserId, createdByUserId, rightsConfirmedAt, hasCsvMembers, counts {members,
sendableEmails, byCountry, bySeniority, byIndustry, byHeadcountBand}, sources [{id,
sourceType, parameters, status, statusMessage, addedByUserId, lastRefreshedAt,
lastRefreshAdded, createdAt}], lastRefreshedAt, submittedAt, reviewedAt,
reviewReason, createdAt, updatedAt; a library list adds submittedByWorkspaceName.
On a shared or library list each source's parameters are {} and statusMessage,
addedByUserId and reviewReason are null; a library list also hides ownerUserId and
createdByUserId. hasCsvMembers is checked on the workspace's own lists only: a shared
or library list reports false.
list-grants
Read. GET https://api.ken.so/v1/saved-lists/{savedListId}/grants
Path: savedListId
List every invite and grant on one of this workspace's saved lists, oldest first. Shows who was invited, which workspace accepted, and what was revoked.
GET /api/v1/saved-lists/{savedListId}/grants. Sends Ken-Version 1.1. Public. Needs the
saved_lists feature. Requires the Search page at view.
Returns every grant in one page (pagination.hasMore is false). A grant: id, savedListId,
inviteeEmail, status (pending, accepted, revoked), receivingWorkspaceId and
receivingWorkspaceName once accepted, invitedByUserId, acceptedAt, revokedAt, createdAt.
Another workspace's list, or another member's private list, is not_found.
list-members
Read. GET https://api.ken.so/v1/saved-lists/{savedListId}/members
Path: savedListId
Query: country string, cursor string, hasSendableEmail boolean, headcountBand string, includeTotal boolean, industry string, limit integer, q string, seniority string, title string
List a saved list's members, filtered, 1-100 per page. Never emails or phones. Each member has emailCount and phoneCount instead; page on with pagination.nextCursor.
GET /api/v1/saved-lists/{savedListId}/members. Public. Sends Ken-Version 1.1. Needs
the saved_lists feature.
Requires the Search page (view).
Readable lists: the workspace's own (a private one only by its owner), one shared with
it through an accepted invite, or an approved library list; anything else is
not_found. Members come in id order; opted-out members never show.
Filters: q (2-200 characters) matches a part of the full name, the title or the company
name, any case; country, seniority, industry and headcount_band match the stored value
exactly (the list's counts breakdowns name them); title matches a part of the title,
any case; has_sendable_email true or false. include_total adds pagination.total, the
filtered count; with no filter (and no q) on a library list it is the stored member
count, the list's counts.members. With q on a large library list that count is slow:
leave it off to page fast. limit 1-100 (default 50); cursor is the previous page's
nextCursor. To find people across all the workspace's own and shared lists at once,
use contacts(operation="saved-list-members-list", q=...).
A member: id, identityKey (an email key shows as em:<id>), firstName, lastName, title,
seniority, companyName, companyDomain, industry, headcountBand, country, state, city,
linkedinUrl, hasSendableEmail, emailCount, phoneCount, sources (label types such as
search_filters, csv, registry, library), custom (CSV fields; a field holding an email
or a phone is left out). A missing field is null. Each member
returned counts one row of the workspace's apiReadRows quota; past it, quota_exceeded.
refresh
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/refresh
Path: savedListId
Run every Search source of a saved list again: adds new matches, never removes a member. Answers 202 with the list's Search sources; poll each with the get-source operation.
POST /api/v1/saved-lists/{savedListId}/refresh. Public. Sends Ken-Version 1.1. Needs the
saved_lists feature. Requires the Search page (edit). Works on your workspace's own
lists only.
Every done or failed search_filters, search_selection and saved_search source goes back
to pending and runs; campaign and list sources are not touched. Returns the list's
Search sources as they stand (an empty list when it has none). A list you cannot see
is 404 not_found.
refresh-source
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/sources/{sourceId}/refresh
Path: savedListId, sourceId
Run one Search source of a saved list again: adds new matches, never removes a member. Answers 202 with the source; poll it with the get-source operation.
POST /api/v1/saved-lists/{savedListId}/sources/{sourceId}/refresh. Public. Sends
Ken-Version 1.1. Needs the saved_lists feature. Requires the Search page (edit).
Only search_filters, search_selection and saved_search sources refresh; any other is
400 validation_failed with sourceId not_refreshable. A done or failed source goes back
to pending and runs; a pending or running one is returned as it is. A source that is
not on that list, or a list you cannot see, is 404 not_found.
remove-member
Write. DELETE https://api.ken.so/v1/saved-lists/{savedListId}/members/{memberId}
Path: savedListId, memberId
Remove one member from one of the workspace's own saved lists. Recounts the list. A shared or library list, or a member of another list, is not_found.
DELETE /api/v1/saved-lists/{savedListId}/members/{memberId}. Public. Sends
Ken-Version 1.1. Needs the saved_lists feature. Requires the Search page (edit). Own lists only: a list shared with the
workspace, a library list or another user's private list is not_found. 204 on success.
revoke-grant
Write. DELETE https://api.ken.so/v1/saved-lists/{savedListId}/grants/{grantId}
Path: savedListId, grantId
Revoke an invite or an accepted grant on one of this workspace's saved lists. Returns 204. The receiving workspace loses read access at once. Revoking twice is fine.
DELETE /api/v1/saved-lists/{savedListId}/grants/{grantId}. Sends Ken-Version 1.1. Public.
Needs the saved_lists feature. Requires the Search page at edit and the share
feature.
A pending invite's link stops working (accepting it is not_found). An unknown grant, or a
grant on another list, is not_found. The grant keeps its receiving workspace so the history
shows who had the list; send a new invite to share again.
submit
Write. POST https://api.ken.so/v1/saved-lists/{savedListId}/submissions
Path: savedListId
Body (json): description string, icpTags array
Submit one of the workspace's own saved lists to the Kenso library for review. The list stays out of the library until Kenso staff approve it.
POST /api/v1/saved-lists/{savedListId}/submissions. Public, behind the saved_lists flag. Sends Ken-Version 1.1.
Body, both optional: icpTags replaces the list's ICP tags (up to 20, each up to 50 characters; [] clears them),
description replaces its description (up to 2000 characters, not blank). Returns the list with access owner,
libraryState submitted and submittedAt. conflict already_submitted while a submission waits for review.
conflict rights_confirmation_required when the list holds uploaded CSV data, or a CSV upload is still running,
and nobody confirmed the right to share it: confirm rights first, then submit again. not_found for a list of
another workspace, a list shared with this workspace, a library list or another member's private list.
Needs the share permission (Admin and Editor) and a person's token: a workspace API key gets forbidden.
update
Write. PATCH https://api.ken.so/v1/saved-lists/{savedListId}
Path: savedListId
Body (json): description string, icpTags array, name string, visibility string
Update one of the workspace's saved lists. Fields left out stay. A shared or library list is not_found here; only the owner can make a list private.
PATCH /api/v1/saved-lists/{savedListId}. Public. Sends Ken-Version 1.1. Needs the
saved_lists feature. Requires the Search page (edit).
Send at least one of name (1-200), description (up to 2000), clear_description
(sends null), visibility (workspace or private) and icp_tags (up to 20; [] clears
them). Making a list private needs a signed-in user (validation_failed
user_required) who owns the list (validation_failed owner_only).