Skip to Content
Prospecting data

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.

Prospecting data18 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

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.

NameInTypeRequiredDescription
savedListIdpathinteger (int64)requiredThe saved list's id.
sourceIdpathinteger (int64)requiredThe source's id.

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

List saved lists

GET/v1/saved-listssaved-lists.list
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: scope or kind has an unknown value, slug came without scope=library, or limit is out of range.

Requires Search view.

Parameters

NameInTypeRequiredDescription
scopequerystringoptionalWhich 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.
kindquerystringoptionalOnly lists of this kind: people or companies. Omit it to return both kinds.
qquerystringoptionalOnly lists whose name contains this text, ignoring case.
icpTagquerystringoptionalOnly lists that carry this ideal customer profile (ICP) tag. The tag must match exactly, case included.
slugquerystringoptionalThe slug of one library list. It works only with scope=library: Kenso returns that list or none, and ignores kind, q and icpTag.
limitqueryinteger (int32)optionalLists per page, from 1 to 100. Default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

POST/v1/saved-listssaved-lists.create
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, or visibility is private and the API key belongs to no user (detail code user_required).

Requires Search edit.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringrequiredThe list's name, from 1 to 200 characters. Required.
kindstringrequiredWhat the list holds: people or companies. Required, and it cannot change later.
descriptionstringoptionalWhat the list is for, up to 2,000 characters. Omitted or blank leaves the list without one.
visibilitystringoptionalWho 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.
icpTagsarray of stringoptionalTags for the ideal customer profile the list fits, up to 20, each up to 50 characters. Kenso trims them and drops repeats.
Request
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

GET/v1/saved-lists/{savedListId}saved-lists.get
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

PATCH/v1/saved-lists/{savedListId}saved-lists.update
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 sets visibility to private (detail code owner_only), or an API key that belongs to no user does (detail code user_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.

FieldTypeRequiredDescription
namestringoptionalThe new name, from 1 to 200 characters.
descriptionstringoptionalThe new description, up to 2,000 characters. null or a blank string clears it.
visibilitystringoptionalWho can read the list: workspace or private. Only the list's owner can make it private.
icpTagsarray of stringoptionalThe new tags, which replace the old ones: up to 20, each up to 50 characters. An empty array clears them.
Request
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

DELETE/v1/saved-lists/{savedListId}saved-lists.delete
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

Response 204
HTTP/1.1 204 No Content

List a saved list's members

GET/v1/saved-lists/{savedListId}/memberssaved-lists.list-members
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, industry and headcountBand match the stored value exactly. Take the values from the list's counts breakdowns.
  • title matches part of the title, in any case.
  • hasSendableEmail is true or false.

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: limit is out of range, q is longer than 200 characters, or cursor is not a nextCursor from this list.
  • 404 not_found: the workspace cannot read the list.
  • 429 quota_exceeded: the workspace used up its apiReadRows quota.

Requires Search view.

Parameters

NameInTypeRequiredDescription
qquerystringoptionalOnly 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.
countryquerystringoptionalOnly members in this country. The value must match a key of the list's counts.byCountry exactly.
seniorityquerystringoptionalOnly members with this seniority. The value must match a key of the list's counts.bySeniority exactly.
titlequerystringoptionalOnly members whose title contains this text, ignoring case.
industryquerystringoptionalOnly members in this industry. The value must match a key of the list's counts.byIndustry exactly.
headcountBandquerystringoptionalOnly members whose company is in this headcount band. The value must match a key of the list's counts.byHeadcountBand exactly.
hasSendableEmailquerybooleanoptionalFilters 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.
includeTotalquerybooleanoptionalSet 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.
limitqueryinteger (int32)optionalMembers per page, from 1 to 100. Default 50.
cursorquerystringoptionalThe nextCursor from the previous page. Omit it for the first page.
Request
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

DELETE/v1/saved-lists/{savedListId}/members/{memberId}saved-lists.remove-member
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
memberIdpathinteger (int64)requiredThe member's id, as the member list returns it.
Request
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

Response 204
HTTP/1.1 204 No Content

Copy a saved list

POST/v1/saved-lists/{savedListId}/copysaved-lists.copy
Permission
Search edit
Rate limit
480 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: name is blank or longer than 200 characters, a filter value is longer than 200 characters, or more than 500,000 members match (detail code too_many_members: narrow memberFilters).
  • 404 not_found: the workspace cannot read the list.

Requires Search edit.

Parameters

NameInTypeRequiredDescription
savedListIdpathinteger (int64)requiredThe id of the saved list to copy.

Request body

application/json, optional.

FieldTypeRequiredDescription
namestringoptionalThe new list's name, from 1 to 200 characters. Omitted uses the original's name followed by " (copy)".
memberFiltersSavedListMemberFiltersBodyoptionalCopies only the members that match every filter you send. Omitted copies every member.
Request
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

POST/v1/saved-lists/{savedListId}/invitessaved-lists.create-invite
Permission
Search edit and the share permission
Rate limit
30 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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: email is 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 its visibility to workspace first.
  • 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.

FieldTypeRequiredDescription
emailstringrequiredThe address Kenso sends the invite link to. Only a person signed in with this address can accept. Required.
Request
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

GET/v1/saved-lists/{savedListId}/grantssaved-lists.list-grants
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

DELETE/v1/saved-lists/{savedListId}/grants/{grantId}saved-lists.revoke-grant
Permission
Search edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
grantIdpathinteger (int64)requiredThe grant's id.
Request
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

Response 204
HTTP/1.1 204 No Content

Confirm the right to share a list

POST/v1/saved-lists/{savedListId}/rights-confirmationsaved-lists.confirm-rights
Permission
Search edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

POST/v1/saved-lists/{savedListId}/sourcessaved-lists.create-source
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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, pageSize and searchAfter). A lookalike search cannot be a source: add its results as a search_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 in parameters was not found, a list source names the list itself, or the list already has 50 sources. error.details names the field and the reason.
  • 400 lookalike_not_storable: parameters is a lookalike search.
  • 403 permission_denied: a campaign source, 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.

FieldTypeRequiredDescription
sourceTypestringrequiredWhat the source reads: search_filters, search_selection, saved_search, campaign or list. Required.
parametersobjectrequiredA 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.
Request
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

GET/v1/saved-lists/{savedListId}/sources/{sourceId}saved-lists.get-source
Permission
Search view
Rate limit
12,000 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

POST/v1/saved-lists/{savedListId}/sources/{sourceId}/refreshsaved-lists.refresh-source
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 code not_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.

Request
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

POST/v1/saved-lists/{savedListId}/refreshsaved-lists.refresh
Permission
Search edit
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

Request
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

POST/v1/saved-lists/{savedListId}/submissionssaved-lists.submit
Permission
Search edit and the share permission
Rate limit
4,800 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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.

FieldTypeRequiredDescription
icpTagsarray of stringoptionalTags 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.
descriptionstringoptionalA description that replaces the list's own, up to 2,000 characters and not blank. Omitted keeps the current description.
Request
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

POST/v1/saved-lists/{savedListId}/uploadssaved-lists.create-upload
Permission
Search edit and the import permission
Rate limit
480 requests a minute per API key
Needs the saved_lists feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 are blocklist, invalidEmail, noMx, catchAll, personalEmail and roleAddress, as a POST /v1/contact-imports/scans with target saved_list reports them. missingKey is accepted and changes nothing.
  • cleanup (optional): true cleans 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, file is missing, empty, not a .csv, larger than 400 MB or longer than 100,000 rows, columnMappings or fixes is not valid JSON or names an unknown field or fix, cleanup is not true or false, or fixes or cleanup came while the csv_import_check feature is off. error.details names 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 the Retry-After header.

Requires Search edit and the import permission.

Request body

multipart/form-data, required.

FieldTypeRequiredDescription
filestring (binary)requiredThe CSV, with a .csv name: at most 400 MB and 100,000 rows.
columnMappingsstringoptionalA JSON array that maps CSV columns to fields, the same array a contact import takes. Without it, Kenso maps the columns by their headers.
fixesstringoptionalA JSON array of List check fixes, such as ["blocklist","invalidEmail","noMx"]. Needs the csv_import_check feature.
cleanupbooleanoptionaltrue cleans every cell of a field with that field's cleaner. Needs the csv_import_check feature.
Request
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.


On this page