Saved lists
Saved lists are reusable lists of people or companies that a workspace builds from Search, saved searches, campaigns, other lists and CSV uploads. Create and copy a list, add sources that fill it in the background and refresh them, and read or remove its members, or search members across every list at once. Share a list read-only with another workspace by email invite and revoke the grant later, or submit it to the Kenso library, where every workspace can read and copy the lists Kenso approves. A member never carries an email address or a phone number, only how many the list holds. A list the workspace cannot read answers 404 not_found, and a private list is visible only to the member who owns it.
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
savedListId | path | integer (int64) | required | The saved list's id. |
sourceId | path | integer (int64) | required | The source's id. |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List saved lists
/v1/saved-listssaved-lists.list- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Lists the saved lists the workspace can read, in id order. Use scope to pick which ones: own (the default) for the workspace's own lists, shared for lists other workspaces shared with it through an accepted invite, or library for the lists Kenso approved for the library.
kind (people or companies) and icpTag (one tag, exact match) filter the lists, and q matches part of the name, in any case. With scope=library, slug returns the one library list with that slug, or an empty page, and the other filters do not apply. limit is from 1 to 100 (default 50), and cursor takes the previous page's nextCursor. pagination.totalCount counts every list that matches.
Your own private lists appear under own, and another member's private list never appears. On a shared or library list, each source shows its type, status and counts, but its parameters is an empty object.
Errors:
400 validation_failed:scopeorkindhas an unknown value,slugcame withoutscope=library, orlimitis out of range.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
scope | query | string | optional | Which lists to return: own (this workspace's lists), shared (lists other workspaces shared with this one) or library (Kenso's approved library lists). Default own. |
kind | query | string | optional | Only lists of this kind: people or companies. Omit it to return both kinds. |
q | query | string | optional | Only lists whose name contains this text, ignoring case. |
icpTag | query | string | optional | Only lists that carry this ideal customer profile (ICP) tag. The tag must match exactly, case included. |
slug | query | string | optional | The slug of one library list. It works only with scope=library: Kenso returns that list or none, and ignores kind, q and icpTag. |
limit | query | integer (int32) | optional | Lists per page, from 1 to 100. Default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/saved-lists?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of SavedList. Each item has these fields. The response also carries pagination.
Show the 23 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a saved list
/v1/saved-listssaved-lists.create- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Creates an empty saved list. Fill it afterwards with a source or a CSV upload.
name (1 to 200 characters) and kind (people or companies) are required. description takes up to 2,000 characters. visibility is workspace (the default), which every member of the workspace can read, or private, which only you can read. icpTags takes up to 20 tags of up to 50 characters each. The calling user becomes the list's owner. The response is 201 with the new list.
Errors:
400 validation_failed: a field breaks the rules above, orvisibilityisprivateand the API key belongs to no user (detail codeuser_required).
Requires Search edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | The list's name, from 1 to 200 characters. Required. |
kind | string | required | What the list holds: people or companies. Required, and it cannot change later. |
description | string | optional | What the list is for, up to 2,000 characters. Omitted or blank leaves the list without one. |
visibility | string | optional | Who can read the list: workspace (the default) for every member of the workspace, or private for you alone. A private list needs a signed-in user or an API key that belongs to a user. |
icpTags | array of string | optional | Tags for the ideal customer profile the list fits, up to 20, each up to 50 characters. Kenso trims them and drops repeats. |
curl -X POST "https://api.ken.so/v1/saved-lists" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"kind": "people",
"description": "string",
"visibility": "workspace",
"icpTags": [
"string"
]
}'Response 201
data is a SavedList.
Show the 23 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a saved list
/v1/saved-lists/{savedListId}saved-lists.get- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Returns one saved list with its counts and sources. It can be a list of this workspace, a list shared with it through an accepted invite, or a library list.
On a shared or library list, each source's parameters is an empty object and its statusMessage is null.
Errors:
404 not_found: the list does not exist, the workspace cannot read it, or it is another member's private list.
Requires Search view.
curl -X GET "https://api.ken.so/v1/saved-lists/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SavedList.
Show the 23 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a saved list
/v1/saved-lists/{savedListId}saved-lists.update- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Changes the name, description, visibility or tags of one of the workspace's own lists. Send only the fields to change: an omitted field keeps its value.
name takes 1 to 200 characters. description takes up to 2,000 characters, and null clears it. visibility is workspace or private, and only the list's owner can make it private. icpTags replaces the tags (up to 20, each up to 50 characters), and [] clears them.
Errors:
400 validation_failed: a field breaks the rules above, a member who does not own the list setsvisibilitytoprivate(detail codeowner_only), or an API key that belongs to no user does (detail codeuser_required).404 not_found: the list does not exist, or it is a shared list, a library list or another member's private list.
Requires Search edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The new name, from 1 to 200 characters. |
description | string | optional | The new description, up to 2,000 characters. null or a blank string clears it. |
visibility | string | optional | Who can read the list: workspace or private. Only the list's owner can make it private. |
icpTags | array of string | optional | The new tags, which replace the old ones: up to 20, each up to 50 characters. An empty array clears them. |
curl -X PATCH "https://api.ken.so/v1/saved-lists/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"description": "string",
"visibility": "workspace",
"icpTags": [
"string"
]
}'Response 200
data is a SavedList.
Show the 23 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a saved list
/v1/saved-lists/{savedListId}saved-lists.delete- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Deletes one of the workspace's own lists. A library list that Kenso approved from it stays in the library. The response is 204 with no body.
Errors:
404 not_found: the list does not exist, or it is a shared list, a library list or another member's private list.
Requires Search edit.
curl -X DELETE "https://api.ken.so/v1/saved-lists/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentList a saved list's members
/v1/saved-lists/{savedListId}/memberssaved-lists.list-members- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Lists the members of a saved list in id order. It works on the workspace's own lists, on lists shared with it and on library lists.
A member never carries an email address or a phone number. emailCount and phoneCount say how many the list holds for the member, an identity key built from an email address shows as em: plus the member id, and Kenso leaves out any custom field that holds an email address or a phone number. Members who opted out never appear.
Filters:
q(up to 200 characters) matches part of the full name, the title or the company name, in any case. Kenso ignores it when it is shorter than 2 characters.country,seniority,industryandheadcountBandmatch the stored value exactly. Take the values from the list'scountsbreakdowns.titlematches part of the title, in any case.hasSendableEmailistrueorfalse.
limit is from 1 to 100 (default 50), and cursor takes the previous page's nextCursor with the same filters. includeTotal=true adds pagination.totalCount, the number of members that match. With no filter on a library list, that total is the list's counts.members. With q on a large list, counting reads every member of the list, so leave includeTotal off to page fast.
Each member returned counts as one row of the workspace's apiReadRows quota.
Errors:
400 validation_failed:limitis out of range,qis longer than 200 characters, orcursoris not anextCursorfrom this list.404 not_found: the workspace cannot read the list.429 quota_exceeded: the workspace used up itsapiReadRowsquota.
Requires Search view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | optional | Only members whose full name, title or company name contains this text, ignoring case. Up to 200 characters, and Kenso ignores text shorter than 2 characters. |
country | query | string | optional | Only members in this country. The value must match a key of the list's counts.byCountry exactly. |
seniority | query | string | optional | Only members with this seniority. The value must match a key of the list's counts.bySeniority exactly. |
title | query | string | optional | Only members whose title contains this text, ignoring case. |
industry | query | string | optional | Only members in this industry. The value must match a key of the list's counts.byIndustry exactly. |
headcountBand | query | string | optional | Only members whose company is in this headcount band. The value must match a key of the list's counts.byHeadcountBand exactly. |
hasSendableEmail | query | boolean | optional | Filters by email: true returns only members with an email a verifier confirmed in the last 90 days, and false only members without one. Omit it to return both. |
includeTotal | query | boolean | optional | Set to true to add pagination.totalCount, the number of members that match the filters (default false). With q on a large list the count is slow, so leave it off to page faster. |
limit | query | integer (int32) | optional | Members per page, from 1 to 100. Default 50. |
cursor | query | string | optional | The nextCursor from the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/saved-lists/812/members?limit=50" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of SavedListMember. Each item has these fields. The response also carries pagination.
Show the 20 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Remove a member from a saved list
/v1/saved-lists/{savedListId}/members/{memberId}saved-lists.remove-member- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Removes one member from one of the workspace's own lists, and Kenso recounts the list. The response is 204 with no body.
Errors:
404 not_found: the list is a shared list, a library list or another member's private list, or the member is not on this list.
Requires Search edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
memberId | path | integer (int64) | required | The member's id, as the member list returns it. |
curl -X DELETE "https://api.ken.so/v1/saved-lists/812/members/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentCopy a saved list
/v1/saved-lists/{savedListId}/copysaved-lists.copy- Permission
- Search edit
- Rate limit
- 480 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Copies a list the workspace can read into a new list of its own. The original can be one of the workspace's lists, a list shared with it or a library list, so this is how you take a shared or library list and edit it.
The body is optional. name names the new list; without it the new list takes the original's name followed by " (copy)". memberFilters copies only the members that match every filter you send. Kenso never copies a member who opted out. The new list keeps the original's description and ICP tags, and has workspace visibility, the calling user as its owner and one list source. Kenso copies the members during the request and answers 201 with the new list.
Errors:
400 validation_failed:nameis blank or longer than 200 characters, a filter value is longer than 200 characters, or more than 500,000 members match (detail codetoo_many_members: narrowmemberFilters).404 not_found: the workspace cannot read the list.
Requires Search edit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
savedListId | path | integer (int64) | required | The id of the saved list to copy. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The new list's name, from 1 to 200 characters. Omitted uses the original's name followed by " (copy)". |
memberFilters | SavedListMemberFiltersBody | optional | Copies only the members that match every filter you send. Omitted copies every member. |
curl -X POST "https://api.ken.so/v1/saved-lists/812/copy" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"memberFilters": {
"country": "string",
"seniority": "string",
"title": "string",
"industry": "string",
"headcountBand": "string",
"hasSendableEmail": true
}
}'Response 201
data is a SavedList.
Show the 23 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Share a saved list by email
/v1/saved-lists/{savedListId}/invitessaved-lists.create-invite- Permission
- Search edit and the
sharepermission - Rate limit
- 30 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Shares one of the workspace's own lists, read-only, with an email address. Kenso creates a grant with status pending and emails the address a link to https://app.ken.so/lists/accept/{token}. The person who accepts picks which of their workspaces receives the list.
email is required. A list with members from a CSV upload needs POST /v1/saved-lists/{savedListId}/rights-confirmation first. Kenso keeps the grant even when the email cannot be sent, so you can revoke it and invite again. The response is 201 with the grant, which never shows the invite token.
Errors:
400 validation_failed:emailis missing or is not an email address.404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.409 invalid_state: the list is private. Set itsvisibilitytoworkspacefirst.409 rights_confirmation_required: the list has members from a CSV upload, and nobody confirmed the right to share them.409 conflict: this address already has a pending invite to the list.
Requires Search edit and the share permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | required | The address Kenso sends the invite link to. Only a person signed in with this address can accept. Required. |
curl -X POST "https://api.ken.so/v1/saved-lists/812/invites" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]"
}'Response 201
data is a SavedListGrant.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
List a saved list's grants
/v1/saved-lists/{savedListId}/grantssaved-lists.list-grants- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Lists every grant of one of the workspace's own lists, in id order. A grant is one email invite to the list and, once someone accepts it, the read access of the workspace that accepted. Use it to see who has the list.
The list holds pending, accepted and revoked grants. Every grant comes in one page, so hasMore is always false. A grant that someone accepted names the receiving workspace, also after a revoke.
Errors:
404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.
Requires Search view.
curl -X GET "https://api.ken.so/v1/saved-lists/812/grants" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of SavedListGrant. Each item has these fields. The response also carries pagination.
Show the 10 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Revoke a saved list grant
/v1/saved-lists/{savedListId}/grants/{grantId}saved-lists.revoke-grant- Permission
- Search edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Revokes a pending or accepted grant of one of the workspace's own lists. The grant's status becomes revoked: the receiving workspace can no longer read the list, and nobody can accept the invite link any more. Contacts the receiving workspace already copied into its campaigns stay there.
Revoking a revoked grant succeeds and changes nothing. The response is 204 with no body.
Errors:
404 not_found: the list or the grant does not exist in this workspace, or the list is another member's private list.
Requires Search edit and the share permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
grantId | path | integer (int64) | required | The grant's id. |
curl -X DELETE "https://api.ken.so/v1/saved-lists/812/grants/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentConfirm the right to share a list
/v1/saved-lists/{savedListId}/rights-confirmationsaved-lists.confirm-rights- Permission
- Search edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Records that you have the right to share the data in a list with members from a CSV upload. Sharing that list by email and submitting it to the library both need this confirmation first.
Kenso records who confirmed and when, and a later confirmation replaces the earlier one. The call needs a user: a signed-in session or an API key that belongs to a user. The response is the list, with rightsConfirmedAt set.
Errors:
403 forbidden: the API key belongs to no user.404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.
Requires Search edit and the share permission.
curl -X POST "https://api.ken.so/v1/saved-lists/812/rights-confirmation" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SavedListRights.
Show the 22 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Add a source to a saved list
/v1/saved-lists/{savedListId}/sourcessaved-lists.create-source- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Adds a source that fills one of the workspace's own lists with members. Kenso runs the source in the background and answers 202 with the source in pending. Poll GET /v1/saved-lists/{savedListId}/sources/{sourceId} until status is done or failed; on failed, statusMessage says why.
Send sourceType and the parameters it takes:
search_filters: a people search body with at least one filter. Kenso drops the paging keys (page,pageSizeandsearchAfter). A lookalike search cannot be a source: add its results as asearch_selection.search_selection:{"personIds": [101, 102]}, from 1 to 1,000 people picked in Search.saved_search:{"savedSearchId": 42}. Each run reads the saved search as the user who added the source.campaign:{"campaignId": 42}, a campaign of this workspace, whose contacts Kenso copies. The caller also needs Campaigns view.list:{"savedListId": 42}, another list the workspace can read that holds the same kind of member.
A company list takes only a list source, and a list holds at most 50 sources. One run reads at most 100,000 rows from its source; past that the source ends done and statusMessage says where it stopped.
Errors:
400 validation_failed: a field breaks the rules above, the campaign or list inparameterswas not found, alistsource names the list itself, or the list already has 50 sources.error.detailsnames the field and the reason.400 lookalike_not_storable:parametersis a lookalike search.403 permission_denied: acampaignsource, and the caller has no Campaigns view.404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.
Requires Search edit.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
sourceType | string | required | What the source reads: search_filters, search_selection, saved_search, campaign or list. Required. |
parameters | object | required | A JSON object that depends on sourceType: a people search body for search_filters, {"personIds": [101, 102]} for search_selection, {"savedSearchId": 42} for saved_search, {"campaignId": 42} for campaign and {"savedListId": 42} for list. Required. |
curl -X POST "https://api.ken.so/v1/saved-lists/812/sources" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"sourceType": "search_filters",
"parameters": null
}'Response 202
data is a SavedListSource.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get a saved list source
/v1/saved-lists/{savedListId}/sources/{sourceId}saved-lists.get-source- Permission
- Search view
- Rate limit
- 12,000 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Returns one source of one of the workspace's own lists. Poll it after you add, upload or refresh a source: status is pending, running, done or failed, and lastRefreshAdded counts the members the last run added.
Errors:
404 not_found: the list or the source does not exist in this workspace, or the list is another member's private list.
Requires Search view.
curl -X GET "https://api.ken.so/v1/saved-lists/812/sources/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a SavedListSource.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Refresh a saved list source
/v1/saved-lists/{savedListId}/sources/{sourceId}/refreshsaved-lists.refresh-source- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Runs one search_filters, search_selection or saved_search source again and adds the people who match now. Members who no longer match stay on the list. The response is 202 with the source. Poll GET /v1/saved-lists/{savedListId}/sources/{sourceId} until it is done or failed.
Errors:
400 validation_failed: the source is not a Search source (detail codenot_refreshable). To copy a campaign or another list again, add a new source for it.404 not_found: the list or the source does not exist in this workspace, or the list is another member's private list.
Requires Search edit.
curl -X POST "https://api.ken.so/v1/saved-lists/812/sources/812/refresh" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 202
data is a SavedListSource.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Refresh a saved list
/v1/saved-lists/{savedListId}/refreshsaved-lists.refresh- Permission
- Search edit
- Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Runs every Search source of one of the workspace's own lists again (search_filters, search_selection and saved_search) and adds the people who match now. Kenso does not run campaign, list or csv sources again, and no member leaves the list.
The response is 202 with the list's Search sources in their current status. Poll each one with GET /v1/saved-lists/{savedListId}/sources/{sourceId}.
Errors:
404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.
Requires Search edit.
curl -X POST "https://api.ken.so/v1/saved-lists/812/refresh" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 202
data is a list of SavedListSource. Each item has these fields.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Submit a saved list to the library
/v1/saved-lists/{savedListId}/submissionssaved-lists.submit- Permission
- Search edit and the
sharepermission - Rate limit
- 4,800 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Sends one of the workspace's own lists to Kenso for review for the library. The list's libraryState becomes submitted, credited to the workspace and the calling user.
Nothing reaches the library until Kenso approves the list. Approval copies the list into the library, where every workspace can read and copy it. Later edits change only your list, not the library copy: to send them for review, submit the list again. icpTags and description replace the list's own when you send them, and an empty body submits the list as it is. A new submission after a rejection clears the old reviewReason. The call needs a user: a signed-in session or an API key that belongs to a user.
Errors:
400 validation_failed: a tag or the description breaks the field rules.403 forbidden: the API key belongs to no user.404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.409 already_submitted: the list is already waiting for review.409 rights_confirmation_required: the list has members from a CSV upload, or a CSV upload is still running, and nobody confirmed the right to share the data.
Requires Search edit and the share permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
icpTags | array of string | optional | Tags that replace the list's ICP tags: up to 20, each up to 50 characters, none blank. An empty array clears them. Omitted keeps the current tags. |
description | string | optional | A description that replaces the list's own, up to 2,000 characters and not blank. Omitted keeps the current description. |
curl -X POST "https://api.ken.so/v1/saved-lists/812/submissions" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"icpTags": [
"string"
],
"description": "string"
}'Response 200
data is a SavedListSubmission.
Show the 22 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Upload a CSV to a saved list
/v1/saved-lists/{savedListId}/uploadssaved-lists.create-upload- Permission
- Search edit and the
importpermission - Rate limit
- 480 requests a minute per API key
saved_lists feature on your workspace. Until it is on, calls answer 404.Adds the rows of a CSV file to one of the workspace's own lists. Kenso checks the file, answers 202 with a new csv source in pending, and adds the rows in the background. Poll GET /v1/saved-lists/{savedListId}/sources/{sourceId} until it is done or failed.
Send multipart/form-data with these fields:
file: the CSV, at most 400 MB and 100,000 rows.columnMappings(optional): a JSON array that maps CSV columns to fields, the same array a contact import takes, for example[{"csvColumn":"Email","targetField":"email"},{"csvColumn":"Deal size","targetField":"custom_variable","customVariableName":"deal_size"}]. Without it, Kenso maps the columns by their headers.fixes(optional): a JSON array of List check fixes, for example["blocklist","invalidEmail","noMx"]. Kenso skips the rows the check flags for each fix. The keys areblocklist,invalidEmail,noMx,catchAll,personalEmailandroleAddress, as aPOST /v1/contact-imports/scanswith targetsaved_listreports them.missingKeyis accepted and changes nothing.cleanup(optional):truecleans every cell of a field with that field's cleaner before the rows are added.
fixes and cleanup need the csv_import_check feature on the workspace. A fix skips whole rows: a row that is already on the list, or that repeats a kept row, still merges into its member with all its addresses.
When the source is done, its parameters hold rowCount, inserted, merged and rejected, plus the fixes and cleanup you sent. rejected counts the rows a fix skipped and the rows that have no LinkedIn URL, no email and no name with a company domain (on a company list, no domain and no company page). skips counts the skipped rows by fix key. Uploaded emails start unverified, Kenso keeps every phone number, and it never stores personal columns such as birth date, gender, age or personal email.
Errors:
400 validation_failed: the body is not multipart,fileis missing, empty, not a.csv, larger than 400 MB or longer than 100,000 rows,columnMappingsorfixesis not valid JSON or names an unknown field or fix,cleanupis nottrueorfalse, orfixesorcleanupcame while thecsv_import_checkfeature is off.error.detailsnames the field.404 not_found: the list is not one of the workspace's own lists, or it is another member's private list.429 rate_limited: the workspace reached its daily import row quota. Retry after the seconds in theRetry-Afterheader.
Requires Search edit and the import permission.
Request body
multipart/form-data, required.
| Field | Type | Required | Description |
|---|---|---|---|
file | string (binary) | required | The CSV, with a .csv name: at most 400 MB and 100,000 rows. |
columnMappings | string | optional | A JSON array that maps CSV columns to fields, the same array a contact import takes. Without it, Kenso maps the columns by their headers. |
fixes | string | optional | A JSON array of List check fixes, such as ["blocklist","invalidEmail","noMx"]. Needs the csv_import_check feature. |
cleanup | boolean | optional | true cleans every cell of a field with that field's cleaner. Needs the csv_import_check feature. |
curl -X POST "https://api.ken.so/v1/saved-lists/812/uploads" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-F "file=@./file" \
-F 'columnMappings=string' \
-F 'fixes=string' \
-F 'cleanup=true'Response 202
data is a SavedListSource.
Show the 9 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Prospecting data:People and company searchSaved searchesSaved list membersSaved list invitesEmail finderFunding roundsJob postingsJob post searchLinkedIn job searchLinkedIn jobsWeb scrapingSocial data lookupsSocial data searchesSocial profile resolutionSocial data recordsSignalsAll resources