{"openapi":"3.0.4","info":{"title":"Kenso API: Saved lists","version":"1.1","description":"The Saved lists endpoints of the Kenso API, with every component they use. The full spec is https://api.ken.so/v1/docs/openapi.json. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`."},"servers":[{"url":"https://api.ken.so"}],"security":[{"Bearer":[]}],"tags":[{"name":"saved-lists","description":"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.","x-displayName":"Saved lists"}],"paths":{"/v1/saved-lists":{"get":{"tags":["saved-lists"],"summary":"List saved lists","description":"Lists the saved lists the workspace can read, in id order. Use `scope` to pick which ones: `own` (the\ndefault) for the workspace's own lists, `shared` for lists other workspaces shared with it through an accepted\ninvite, or `library` for the lists Kenso approved for the library.\n            \n`kind` (`people` or `companies`) and `icpTag` (one tag, exact match) filter the lists, and\n`q` matches part of the name, in any case. With `scope=library`, `slug` returns the one library list\nwith that slug, or an empty page, and the other filters do not apply. `limit` is from 1 to 100 (default 50),\nand `cursor` takes the previous page's `nextCursor`. `pagination.totalCount` counts every list that\nmatches.\n            \nYour own private lists appear under `own`, and another member's private list never appears. On a shared or\nlibrary list, each source shows its type, status and counts, but its `parameters` is an empty object.\n            \nErrors:\n            \n- `400 validation_failed`: `scope` or `kind` has an unknown value, `slug` came without\n`scope=library`, or `limit` is out of range.\n            \nRequires Search view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.list","parameters":[{"name":"scope","in":"query","description":"Which lists to return: `own` (this workspace's lists), `shared` (lists other workspaces shared with this\none) or `library` (Kenso's approved library lists). Default `own`.","schema":{"type":"string"}},{"name":"kind","in":"query","description":"Only lists of this kind: `people` or `companies`. Omit it to return both kinds.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Only lists whose name contains this text, ignoring case.","schema":{"type":"string"}},{"name":"icpTag","in":"query","description":"Only lists that carry this ideal customer profile (ICP) tag. The tag must match exactly, case included.","schema":{"type":"string"}},{"name":"slug","in":"query","description":"The slug of one library list. It works only with `scope=library`: Kenso returns that list or none, and ignores\n`kind`, `q` and `icpTag`.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Lists per page, from 1 to 100. Default 50.","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"view","summary":"Search view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"post":{"tags":["saved-lists"],"summary":"Create a saved list","description":"Creates an empty saved list. Fill it afterwards with a source or a CSV upload.\n            \n`name` (1 to 200 characters) and `kind` (`people` or `companies`) are required.\n`description` takes up to 2,000 characters. `visibility` is `workspace` (the default), which every\nmember of the workspace can read, or `private`, which only you can read. `icpTags` takes up to 20 tags of\nup to 50 characters each. The calling user becomes the list's owner. The response is `201` with the new list.\n            \nErrors:\n            \n- `400 validation_failed`: a field breaks the rules above, or `visibility` is `private` and the\nAPI key belongs to no user (detail code `user_required`).\n- `403 forbidden`: the caller is a workspace key. A list is created and owned by a member, and a workspace\n  key is not a person.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.create","parameters":[{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedListBody"}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}":{"get":{"tags":["saved-lists"],"summary":"Get a saved list","description":"Returns one saved list with its counts and sources. It can be a list of this workspace, a list shared with it\nthrough an accepted invite, or a library list.\n            \nOn a shared or library list, each source's `parameters` is an empty object and its `statusMessage` is\nnull.\n            \nErrors:\n            \n- `404 not_found`: the list does not exist, the workspace cannot read it, or it is another member's private\nlist.\n            \nRequires Search view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.get","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"view","summary":"Search view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"patch":{"tags":["saved-lists"],"summary":"Update a saved list","description":"Changes the name, description, visibility or tags of one of the workspace's own lists. Send only the fields to\nchange: an omitted field keeps its value.\n            \n`name` takes 1 to 200 characters. `description` takes up to 2,000 characters, and `null` clears it.\n`visibility` is `workspace` or `private`, and only the list's owner can make it private.\n`icpTags` replaces the tags (up to 20, each up to 50 characters), and `[]` clears them.\n            \nErrors:\n            \n- `400 validation_failed`: a field breaks the rules above, a member who does not own the list sets\n`visibility` to `private` (detail code `owner_only`), or an API key that belongs to no user does\n(detail code `user_required`).\n- `404 not_found`: the list does not exist, or it is a shared list, a library list or another member's\nprivate list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.update","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSavedListBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["saved-lists"],"summary":"Delete a saved list","description":"Deletes one of the workspace's own lists. A library list that Kenso approved from it stays in the library. The\nresponse is `204` with no body.\n            \nErrors:\n            \n- `404 not_found`: the list does not exist, or it is a shared list, a library list or another member's\nprivate list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.delete","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/members":{"get":{"tags":["saved-lists"],"summary":"List a saved list's members","description":"Lists the members of a saved list in id order. It works on the workspace's own lists, on lists shared with it and\non library lists.\n            \nA member never carries an email address or a phone number. `emailCount` and `phoneCount` say how many\nthe list holds for the member, an identity key built from an email address shows as `em:` plus the member id,\nand Kenso leaves out any custom field that holds an email address or a phone number. Members who opted out never\nappear.\n            \nFilters:\n            \n- `q` (up to 200 characters) matches part of the full name, the title or the company name, in any case.\nKenso ignores it when it is shorter than 2 characters.\n- `country`, `seniority`, `industry` and `headcountBand` match the stored value exactly. Take\nthe values from the list's `counts` breakdowns.\n- `title` matches part of the title, in any case.\n- `hasSendableEmail` is `true` or `false`.\n            \n`limit` is from 1 to 100 (default 50), and `cursor` takes the previous page's `nextCursor` with the\nsame filters. `includeTotal=true` adds `pagination.totalCount`, the number of members that match. With no\nfilter on a library list, that total is the list's `counts.members`. With `q` on a large list, counting\nreads every member of the list, so leave `includeTotal` off to page fast.\n            \nEach member returned counts as one row of the workspace's `apiReadRows` quota.\n            \nErrors:\n            \n- `400 validation_failed`: `limit` is out of range, `q` is longer than 200 characters, or\n`cursor` is not a `nextCursor` from this list.\n- `404 not_found`: the workspace cannot read the list.\n- `429 quota_exceeded`: the workspace used up its `apiReadRows` quota.\n            \nRequires Search view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.list-members","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"q","in":"query","description":"Only members whose full name, title or company name contains this text, ignoring case. Up to 200 characters, and\nKenso ignores text shorter than 2 characters.","schema":{"type":"string"}},{"name":"country","in":"query","description":"Only members in this country. The value must match a key of the list's `counts.byCountry` exactly.","schema":{"type":"string"}},{"name":"seniority","in":"query","description":"Only members with this seniority. The value must match a key of the list's `counts.bySeniority` exactly.","schema":{"type":"string"}},{"name":"title","in":"query","description":"Only members whose title contains this text, ignoring case.","schema":{"type":"string"}},{"name":"industry","in":"query","description":"Only members in this industry. The value must match a key of the list's `counts.byIndustry` exactly.","schema":{"type":"string"}},{"name":"headcountBand","in":"query","description":"Only members whose company is in this headcount band. The value must match a key of the list's\n`counts.byHeadcountBand` exactly.","schema":{"type":"string"}},{"name":"hasSendableEmail","in":"query","description":"Filters by email: `true` returns only members with an email a verifier confirmed in the last 90 days, and\n`false` only members without one. Omit it to return both.","schema":{"type":"boolean"}},{"name":"includeTotal","in":"query","description":"Set to `true` to add `pagination.totalCount`, the number of members that match the filters (default\n`false`). With `q` on a large list the count is slow, so leave it off to page faster.","schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Members per page, from 1 to 100. Default 50.","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListMemberListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["quota_exceeded","rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"view","summary":"Search view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/members/{memberId}":{"delete":{"tags":["saved-lists"],"summary":"Remove a member from a saved list","description":"Removes one member from one of the workspace's own lists, and Kenso recounts the list. The response is\n`204` with no body.\n            \nErrors:\n            \n- `404 not_found`: the list is a shared list, a library list or another member's private list, or the member\nis not on this list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.remove-member","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"memberId","in":"path","description":"The member's id, as the member list returns it.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/copy":{"post":{"tags":["saved-lists"],"summary":"Copy a saved list","description":"Copies a list the workspace can read into a new list of its own. The original can be one of the workspace's lists,\na list shared with it or a library list, so this is how you take a shared or library list and edit it.\n            \nThe body is optional. `name` names the new list; without it the new list takes the original's name followed\nby \" (copy)\". `memberFilters` copies only the members that match every filter you send. Kenso never copies a\nmember who opted out. The new list keeps the original's description and ICP tags, and has `workspace`\nvisibility, the calling user as its owner and one `list` source. Kenso copies the members during the request and answers `201` with the new list.\n            \nErrors:\n            \n- `400 validation_failed`: `name` is blank or longer than 200 characters, a filter value is longer than\n200 characters, or more than 500,000 members match (detail code `too_many_members`: narrow\n`memberFilters`).\n- `403 forbidden`: the caller is a workspace key. The copy is created and owned by a member, and a\n  workspace key is not a person.\n- `404 not_found`: the workspace cannot read the list.\n            \nRequires Search edit.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.copy","parameters":[{"name":"savedListId","in":"path","description":"The id of the saved list to copy.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopySavedListBody"}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/invites":{"post":{"tags":["saved-lists"],"summary":"Share a saved list by email","description":"Shares one of the workspace's own lists, read-only, with an email address. Kenso creates a grant with status\n`pending` and emails the address a link to `https://app.ken.so/lists/accept/{token}`. The person who\naccepts picks which of their workspaces receives the list.\n            \n`email` is required. A list with members from a CSV upload needs\n`POST /v1/saved-lists/{savedListId}/rights-confirmation` first. Kenso keeps the grant even when the email\ncannot be sent, so you can revoke it and invite again. The response is `201` with the grant, which never\nshows the invite token.\n            \nErrors:\n            \n- `400 validation_failed`: `email` is missing or is not an email address.\n- `403 forbidden`: the caller is a workspace key. The invite records the member who sent it, and a\n  workspace key is not a person.\n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n- `409 invalid_state`: the list is private. Set its `visibility` to `workspace` first.\n- `409 rights_confirmation_required`: the list has members from a CSV upload, and nobody confirmed the right\nto share them.\n- `409 conflict`: this address already has a pending invite to the list.\n            \nRequires Search edit and the `share` permission.\n\nRate limit: 30 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.create-invite","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedListInviteBody"}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListGrantResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["conflict","invalid_state","rights_confirmation_required"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","features":["share"],"summary":"Search edit and the `share` permission"},"x-ken-rate-limit":{"limit":30,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/grants":{"get":{"tags":["saved-lists"],"summary":"List a saved list's grants","description":"Lists every grant of one of the workspace's own lists, in id order. A grant is one email invite to the list and,\nonce someone accepts it, the read access of the workspace that accepted. Use it to see who has the list.\n            \nThe list holds pending, accepted and revoked grants. Every grant comes in one page, so `hasMore` is always\nfalse. A grant that someone accepted names the receiving workspace, also after a revoke.\n            \nErrors:\n            \n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n            \nRequires Search view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.list-grants","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListGrantListResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"view","summary":"Search view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/grants/{grantId}":{"delete":{"tags":["saved-lists"],"summary":"Revoke a saved list grant","description":"Revokes a pending or accepted grant of one of the workspace's own lists. The grant's status becomes\n`revoked`: the receiving workspace can no longer read the list, and nobody can accept the invite link any\nmore. Contacts the receiving workspace already copied into its campaigns stay there.\n            \nRevoking a revoked grant succeeds and changes nothing. The response is `204` with no body.\n            \nErrors:\n            \n- `404 not_found`: the list or the grant does not exist in this workspace, or the list is another member's\nprivate list.\n            \nRequires Search edit and the `share` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.revoke-grant","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"grantId","in":"path","description":"The grant's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"No Content","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","features":["share"],"summary":"Search edit and the `share` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/rights-confirmation":{"post":{"tags":["saved-lists"],"summary":"Confirm the right to share a list","description":"Records that you have the right to share the data in a list with members from a CSV upload. Sharing that list by\nemail and submitting it to the library both need this confirmation first.\n            \nKenso records who confirmed and when, and a later confirmation replaces the earlier one. The call needs a user: a\nsigned-in session or an API key that belongs to a user. The response is the list, with\n`rightsConfirmedAt` set.\n            \nErrors:\n            \n- `403 forbidden`: the API key belongs to no user.\n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n            \nRequires Search edit and the `share` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.confirm-rights","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListRightsResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","features":["share"],"summary":"Search edit and the `share` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/sources":{"post":{"tags":["saved-lists"],"summary":"Add a source to a saved list","description":"Adds a source that fills one of the workspace's own lists with members. Kenso runs the source in the background\nand answers `202` with the source in `pending`. Poll\n`GET /v1/saved-lists/{savedListId}/sources/{sourceId}` until `status` is `done` or `failed`;\non `failed`, `statusMessage` says why.\n            \nSend `sourceType` and the `parameters` it takes:\n            \n- `search_filters`: a people search body with at least one filter. Kenso drops the paging keys\n(`page`, `pageSize` and `searchAfter`). A lookalike search cannot be a source: add its results as a\n`search_selection`.\n- `search_selection`: `{\"personIds\": [101, 102]}`, from 1 to 1,000 people picked in Search.\n- `saved_search`: `{\"savedSearchId\": 42}`. Each run reads the saved search as the user who added the\nsource.\n- `campaign`: `{\"campaignId\": 42}`, a campaign of this workspace, whose contacts Kenso copies. The\ncaller also needs Campaigns view.\n- `list`: `{\"savedListId\": 42}`, another list the workspace can read that holds the same kind of member.\n            \nA company list takes only a `list` source, and a list holds at most 50 sources. One run reads at most\n100,000 rows from its source; past that the source ends `done` and `statusMessage` says where it\nstopped.\n            \nErrors:\n            \n- `400 validation_failed`: a field breaks the rules above, the campaign or list in `parameters` was not\nfound, a `list` source names the list itself, or the list already has 50 sources. `error.details` names\nthe field and the reason.\n- `400 lookalike_not_storable`: `parameters` is a lookalike search.\n- `402 plan_required`: a `search_filters` source needs funding signals for a funding filter, which the plan\nlacks (`error.refusal`).\n- `402 plan_limit_reached`: on Kenso Lifetime, a `search_filters`, `search_selection` or\n`saved_search` source when the day's people results are already used up (`error.refusal` code\n`LIFETIME_PEOPLE_RESULT_LIMIT_REACHED`; they come back at 00:00 UTC). A license that is no longer active\nrefuses these sources with `402 workspace_read_only` (refusal code `WORKSPACE_READ_ONLY`).\n- `403 permission_denied`: a `campaign` source, and the caller has no Campaigns view.\n- `403 forbidden`: the caller is a workspace key. A source records the member who adds it, and each run\nreads as them, so a workspace key, which is not a person, cannot add one.\n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.create-source","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedListSourceBody"}}}},"responses":{"202":{"description":"Accepted","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSourceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["lookalike_not_storable","unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"402":{"description":"Payment Required","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["plan_limit_reached","plan_required","workspace_read_only"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden","permission_denied"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/sources/{sourceId}":{"get":{"tags":["saved-lists"],"summary":"Get a saved list source","description":"Returns one source of one of the workspace's own lists. Poll it after you add, upload or refresh a source:\n`status` is `pending`, `running`, `done` or `failed`, and `lastRefreshAdded` counts\nthe members the last run added.\n            \nErrors:\n            \n- `404 not_found`: the list or the source does not exist in this workspace, or the list is another member's\nprivate list.\n            \nRequires Search view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.get-source","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"sourceId","in":"path","description":"The source's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSourceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"view","summary":"Search view"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/sources/{sourceId}/refresh":{"post":{"tags":["saved-lists"],"summary":"Refresh a saved list source","description":"Runs one `search_filters`, `search_selection` or `saved_search` source again and adds the people\nwho match now. Members who no longer match stay on the list. The response is `202` with the source. Poll\n`GET /v1/saved-lists/{savedListId}/sources/{sourceId}` until it is `done` or `failed`.\n            \nErrors:\n            \n- `400 validation_failed`: the source is not a Search source (detail code `not_refreshable`). To copy a\ncampaign or another list again, add a new source for it.\n- `404 not_found`: the list or the source does not exist in this workspace, or the list is another member's\nprivate list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.refresh-source","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"sourceId","in":"path","description":"The source's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"202":{"description":"Accepted","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSourceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/refresh":{"post":{"tags":["saved-lists"],"summary":"Refresh a saved list","description":"Runs every Search source of one of the workspace's own lists again (`search_filters`,\n`search_selection` and `saved_search`) and adds the people who match now. Kenso does not run\n`campaign`, `list` or `csv` sources again, and no member leaves the list.\n            \nThe response is `202` with the list's Search sources in their current status. Poll each one with\n`GET /v1/saved-lists/{savedListId}/sources/{sourceId}`.\n            \nErrors:\n            \n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n            \nRequires Search edit.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.refresh","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"minimum":1,"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"responses":{"202":{"description":"Accepted","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSourceArrayResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","summary":"Search edit"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/submissions":{"post":{"tags":["saved-lists"],"summary":"Submit a saved list to the library","description":"Sends one of the workspace's own lists to Kenso for review for the library. The list's `libraryState`\nbecomes `submitted`, credited to the workspace and the calling user.\n            \nNothing reaches the library until Kenso approves the list. Approval copies the list into the library, where every\nworkspace can read and copy it. Later edits change only your list, not the library copy: to send them for review,\nsubmit the list again. `icpTags` and `description` replace\nthe list's own when you send them, and an empty body submits the list as it is. A new submission after a rejection\nclears the old `reviewReason`. The call needs a user: a signed-in session or an API key that belongs to a\nuser.\n            \nErrors:\n            \n- `400 validation_failed`: a tag or the description breaks the field rules.\n- `403 forbidden`: the API key belongs to no user.\n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n- `409 already_submitted`: the list is already waiting for review.\n- `409 rights_confirmation_required`: the list has members from a CSV upload, or a CSV upload is still\nrunning, and nobody confirmed the right to share the data.\n            \nRequires Search edit and the `share` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.submit","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitSavedListBody"}}}},"responses":{"200":{"description":"OK","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSubmissionResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"409":{"description":"Conflict","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["already_submitted","rights_confirmation_required"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","features":["share"],"summary":"Search edit and the `share` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/saved-lists/{savedListId}/uploads":{"post":{"tags":["saved-lists"],"summary":"Upload a CSV to a saved list","description":"Adds the rows of a CSV file to one of the workspace's own lists. Kenso checks the file, answers `202` with a\nnew `csv` source in `pending`, and adds the rows in the background. Poll\n`GET /v1/saved-lists/{savedListId}/sources/{sourceId}` until it is `done` or `failed`.\n            \nSend `multipart/form-data` with these fields:\n            \n- `file`: the CSV, at most 400 MB and 100,000 rows.\n- `columnMappings` (optional): a JSON array that maps CSV columns to fields, the same array a contact import\ntakes, for example\n`[{\"csvColumn\":\"Email\",\"targetField\":\"email\"},{\"csvColumn\":\"Deal size\",\"targetField\":\"custom_variable\",\"customVariableName\":\"deal_size\"}]`.\nWithout it, Kenso maps the columns by their headers.\n- `fixes` (optional): a JSON array of List check fixes, for example `[\"blocklist\",\"invalidEmail\",\"noMx\"]`.\nKenso skips the rows the check flags for each fix. The keys are `blocklist`, `invalidEmail`,\n`noMx`, `catchAll`, `personalEmail` and `roleAddress`, as a\n`POST /v1/contact-imports/scans` with target `saved_list` reports them. `missingKey` is accepted\nand changes nothing.\n- `cleanup` (optional): `true` cleans every cell of a field with that field's cleaner before the rows\nare added.\n            \n`fixes` and `cleanup` need the `csv_import_check` feature on the workspace. A fix skips whole rows:\na row that is already on the list, or that repeats a kept row, still merges into its member with all its\naddresses.\n            \nWhen the source is `done`, its `parameters` hold `rowCount`, `inserted`, `merged` and\n`rejected`, plus the `fixes` and `cleanup` you sent. `rejected` counts the rows a fix skipped\nand the rows that have no LinkedIn URL, no email and no name with a company domain (on a company list, no domain\nand no company page). `skips` counts the skipped rows by fix key. Uploaded emails start unverified, Kenso\nkeeps every phone number, and it never stores personal columns such as birth date, gender, age or personal email.\n            \nErrors:\n            \n- `400 validation_failed`: the body is not multipart, `file` is missing, empty, not a `.csv`,\nlarger than 400 MB or longer than 100,000 rows, `columnMappings` or `fixes` is not valid JSON or names an\nunknown field or fix, `cleanup` is not `true` or `false`, or `fixes` or `cleanup` came while the\n`csv_import_check` feature is off. `error.details` names the field.\n- `403 forbidden`: the caller is a workspace key. The upload records the member who added it, and a\n  workspace key is not a person.\n- `404 not_found`: the list is not one of the workspace's own lists, or it is another member's private list.\n- `429 rate_limited`: the workspace reached its daily import row quota. Retry after the seconds in the\n`Retry-After` header.\n            \nRequires Search edit and the `import` permission.\n\nRate limit: 480 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `saved_lists` feature on your workspace. Until it is on, calls answer 404.","operationId":"saved-lists.create-upload","parameters":[{"name":"savedListId","in":"path","description":"The saved list's id.","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"Ken-Version","in":"header","description":"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 value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions.","schema":{"enum":["2026-11-02","1.1"],"type":"string"},"examples":{"default":{"value":"2026-11-02","x-disabled":false}}},{"name":"X-Ken-Workspace-Id","in":"header","description":"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`.","schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateSavedListUploadFormBody"}}},"required":true},"responses":{"202":{"description":"Accepted","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedListSourceResponse"}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["unsupported_version","validation_failed","workspace_required"]},"401":{"description":"Unauthorized","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"x-ken-error-codes":["unauthenticated"]},"403":{"description":"Forbidden","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["forbidden"]},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}},"x-ken-error-codes":["not_found"]},"429":{"description":"Too Many Requests","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsError"}},"text/plain":{"schema":{"$ref":"#/components/schemas/RateLimitedText"}}},"x-ken-error-codes":["rate_limited"]}},"x-ken-features":["saved_lists"],"x-ken-permission":{"kind":"page","page":"search","access":"edit","features":["import"],"summary":"Search edit and the `import` permission"},"x-ken-rate-limit":{"limit":480,"windowSeconds":60,"per":"api_key"}}}},"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Enter: Bearer {your Kenso API key}. Create one in the Kenso app under Settings > Integrations > API Keys.","scheme":"bearer","bearerFormat":"Opaque API key"}},"headers":{"RateLimit-Limit":{"description":"The request limit of the rate limit this request is closest to reaching: your plan's limit for this kind of call, your API key's own limit, or the operation's own limit, whichever has the fewest requests left.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The requests left under that limit. `0` on a `429`.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The seconds until that limit resets.","schema":{"type":"integer"}}},"schemas":{"ApiKeyError":{"required":["error"],"type":"object","properties":{"error":{"type":"string","description":"A sentence for people that says what went wrong. It can change, so do not parse it."}},"additionalProperties":false,"description":"The body the API key check in front of the operations answered until November 2026, instead of the error body (`Failure`): `{ \"error\": \"Invalid or revoked API key\" }` on a `401`, `{ \"error\": \"Rate limit exceeded\" }` on a `429` and `{ \"error\": \"Authentication is temporarily unavailable\" }` on a `503`. It has no `code`, so branch on the HTTP status."},"CopySavedListBody":{"type":"object","properties":{"name":{"type":"string","description":"The new list's name, from 1 to 200 characters. Omitted uses the original's name followed by \" (copy)\".","nullable":true},"memberFilters":{"allOf":[{"$ref":"#/components/schemas/SavedListMemberFiltersBody"}],"description":"Copies only the members that match every filter you send. Omitted copies every member."}},"additionalProperties":false,"description":"Options for a copy of a saved list. An empty body copies every member who has not opted out, under the original's\nname followed by \" (copy)\"."},"CreateSavedListBody":{"required":["name","kind"],"type":"object","properties":{"name":{"type":"string","description":"The list's name, from 1 to 200 characters. Required."},"kind":{"type":"string","description":"What the list holds: `people` or `companies`. Required, and it cannot change later."},"description":{"type":"string","description":"What the list is for, up to 2,000 characters. Omitted or blank leaves the list without one.","nullable":true},"visibility":{"type":"string","description":"Who can read the list: `workspace` (the default) for every member of the workspace, or `private` for you\nalone. A private list needs a signed-in user or an API key that belongs to a user.","nullable":true},"icpTags":{"type":"array","items":{"type":"string"},"description":"Tags for the ideal customer profile the list fits, up to 20, each up to 50 characters. Kenso trims them and drops\nrepeats.","nullable":true}},"additionalProperties":false,"description":"The fields of a new saved list."},"CreateSavedListInviteBody":{"required":["email"],"type":"object","properties":{"email":{"type":"string","description":"The address Kenso sends the invite link to. Only a person signed in with this address can accept. Required."}},"additionalProperties":false,"description":"The email address to share a saved list with."},"CreateSavedListSourceBody":{"required":["sourceType","parameters"],"type":"object","properties":{"sourceType":{"type":"string","description":"What the source reads: `search_filters`, `search_selection`, `saved_search`, `campaign` or\n`list`. Required."},"parameters":{"description":"A JSON object that depends on `sourceType`: a people search body for `search_filters`,\n`{\"personIds\": [101, 102]}` for `search_selection`, `{\"savedSearchId\": 42}` for\n`saved_search`, `{\"campaignId\": 42}` for `campaign` and `{\"savedListId\": 42}` for\n`list`. Required."}},"additionalProperties":false,"description":"A source to add to a saved list: what it reads and its settings."},"CreateSavedListUploadFormBody":{"required":["file"],"type":"object","properties":{"file":{"type":"string","description":"The CSV, with a `.csv` name: at most 400 MB and 100,000 rows.","format":"binary"},"columnMappings":{"type":"string","description":"A JSON array that maps CSV columns to fields, the same array a contact import takes. Without it, Kenso maps the\ncolumns by their headers.","nullable":true},"fixes":{"type":"string","description":"A JSON array of List check fixes, such as `[\"blocklist\",\"invalidEmail\",\"noMx\"]`. Needs the\n`csv_import_check` feature.","nullable":true},"cleanup":{"type":"boolean","description":"`true` cleans every cell of a field with that field's cleaner. Needs the `csv_import_check` feature.","nullable":true}},"additionalProperties":false,"description":"The multipart body that adds a CSV of people or companies to a saved list."},"ErrorAccount":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"stakeholderId":{"type":"integer","description":"The person's stakeholder id on this account.","format":"int64"}},"additionalProperties":false,"description":"An account named in an error detail."},"ErrorBody":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code, such as `validation_failed` or `not_found`. Branch on this value."},"message":{"type":"string","description":"A sentence for people that explains the error. It can change, so do not parse it."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"description":"One entry per problem, naming the field or limit it is about. Omitted when there are none.","nullable":true},"requestId":{"type":"string","description":"The id of this request: the same value as the `X-Correlation-Id` response header. Quote it when you write\nto contact@ken.so."},"docUrl":{"type":"string","description":"The page on this code in the developer docs, which says what it means and how to fix it. The errors guide for a\ncode that has no page of its own.","readOnly":true},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"On a `402`, the plan rule or usage limit that refused the request and how to lift it. Omitted otherwise."},"impact":{"allOf":[{"$ref":"#/components/schemas/InvalidationImpact"}],"description":"On a `409` that refuses a change because it would clear stored AI output (a prompt edit, a restore or a\nreset), how much the change would clear. Omitted otherwise."},"surface":{"type":"string","description":"Set only by the voice ticket's `409` (code `voice_conversation_active`): the chat the person's other\nvoice conversation runs in, `support`, `ken` or `onboarding`. Omitted on every other error.","nullable":true}},"additionalProperties":false,"description":"What went wrong in a request."},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","description":"The request field, header or limit the problem is about, such as `name` or `Ken-Version`."},"code":{"type":"string","description":"Stable code for this problem, such as `required` or `invalid`."},"message":{"type":"string","description":"A sentence for people that explains this problem."},"count":{"type":"integer","description":"On `export_limit_exceeded`, how many rows match the export. Omitted otherwise.","format":"int32","nullable":true},"index":{"type":"integer","description":"The position of the refused item in the request's list. Omitted otherwise.","format":"int32","nullable":true},"limit":{"type":"integer","description":"On `export_limit_exceeded`, the row limit the export ran with. On a `quota_exceeded` detail whose\n`field` names a quota, that quota's limit. On a `rate_limited` detail from your workspace's rate\nlimits, the limit that was hit. Omitted otherwise.","format":"int32","nullable":true},"resetAt":{"type":"string","description":"On some `quota_exceeded` details, when the quota frees up, in UTC. It is the same instant as the top-level\n`quotaResetAt`. On a `rate_limited` detail from your workspace's rate limits, when that limit resets.\nOmitted otherwise.","format":"date-time","nullable":true},"retryAfterSeconds":{"type":"integer","description":"On those `quota_exceeded` details and on most `rate_limited` details, the seconds to wait. It is the\nsame value as the `Retry-After` header. Omitted otherwise.","format":"int32","nullable":true},"inboxId":{"type":"integer","description":"The inbox the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainId":{"type":"integer","description":"The domain the problem is about. Omitted otherwise.","format":"int64","nullable":true},"domainName":{"type":"string","description":"The name of that domain, or the domain name the request gave. Omitted otherwise.","nullable":true},"accountId":{"type":"integer","description":"On `domain_taken`, `already_stakeholder` and `previously_removed`, the existing account to use\ninstead. Omitted otherwise.","format":"int64","nullable":true},"personId":{"type":"integer","description":"On `email_taken` and `linkedin_url_taken`, the existing person to use instead. Omitted otherwise.","format":"int64","nullable":true},"stakeholderId":{"type":"integer","description":"The account stakeholder the problem is about. Omitted otherwise.","format":"int64","nullable":true},"championId":{"type":"integer","description":"Not used. Always omitted.","format":"int64","nullable":true},"callTaskId":{"type":"integer","description":"On `call_task_exists`, the open call task that already holds the person's slot. Omitted otherwise.","format":"int64","nullable":true},"status":{"type":"string","description":"On `invalid_transition`, the current status. Omitted otherwise.","nullable":true},"allowed":{"type":"array","items":{"type":"string"},"description":"On `out_of_range`, the allowed values. On `invalid_transition`, the statuses the change is allowed\nfrom. Omitted otherwise.","nullable":true},"scope":{"type":"string","description":"On a `permission_denied` for an account owner change, the account scope the call needs (`all`). On\n`sending_paused`, what the pause covers: `inbox`, `domain` or `workspace`. Omitted otherwise.","nullable":true},"removedAt":{"type":"string","description":"On `previously_removed`, when a person removed the stakeholder, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"page":{"type":"string","description":"On `permission_denied`, the page the call needs, such as `campaigns`. Omitted otherwise.","nullable":true},"required":{"type":"string","description":"On `permission_denied`, the access `page` needs: `view` or `edit`. Omitted otherwise.","nullable":true},"feature":{"type":"string","description":"On `permission_denied`, the permission the call needs, such as `launch`. Omitted otherwise.","nullable":true},"runId":{"type":"integer","description":"On `committee_run_active` and `run_not_finding`, the committee run the problem is about. Omitted\notherwise.","format":"int64","nullable":true},"mergedIntoId":{"type":"integer","description":"On `person_merged`, the person the merged person now lives on. On `account_merged`, the account the\nmerged account now lives on. Omitted otherwise.","format":"int64","nullable":true},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ErrorAccount"},"description":"On `person_on_accounts`, the accounts that block the change. Omitted otherwise.","nullable":true},"stage":{"type":"string","description":"On `stage_in_use` and `system_stage`, the opportunity stage key the problem is about. Omitted otherwise.","nullable":true},"opportunityCount":{"type":"integer","description":"On `stage_in_use`, how many opportunities are in that stage. Omitted otherwise.","format":"int32","nullable":true},"rule":{"type":"string","description":"On `guardrail_violation`, the contact limit rule the change breaks. Omitted otherwise.","nullable":true},"nextAllowedAt":{"type":"string","description":"On `guardrail_violation`, the first `dueAt` that passes every contact limit, in UTC. On a refused\nsend, when to retry. Omitted otherwise, and when waiting does not clear it.","format":"date-time","nullable":true},"fix":{"type":"string","description":"On a refused send, what to do next, in plain words. Omitted otherwise.","nullable":true},"opensAt":{"type":"string","description":"On `outside_calling_hours`, when the person's calling window opens, in UTC. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"On a knowledge file's `version_conflict`, the file's current version. Omitted otherwise.","format":"int32","nullable":true},"provider":{"type":"string","description":"On a CRM connection error (`provider_error`, `exchange_failed`, `already_connected`,\n`account_mismatch` or `provider_unavailable`), the CRM it is about. Omitted otherwise.","nullable":true},"sharedWithMaster":{"type":"boolean","description":"True on a `quota_exceeded` detail when the shared limit of the white-label master workspace was hit, so\n`limit` is the limit of the whole white-label account. Omitted otherwise. The master's id is never sent.","nullable":true},"stepId":{"type":"integer","description":"On `link_reputation_blocked`, the saved sequence step that holds the blocked link. Omitted otherwise, and\nfor a step the save would have created.","format":"int64","nullable":true},"stepOrder":{"type":"integer","description":"On `link_reputation_blocked`, the `stepOrder` of that step. Omitted otherwise.","format":"int32","nullable":true},"url":{"type":"string","description":"On `link_reputation_blocked`, the blocked link as the step's copy writes it. Omitted otherwise.","nullable":true},"key":{"type":"string","description":"On `unfilled_template_key`, the template key the text still holds, such as `first_name` for\n`{first_name}`. Omitted otherwise.","nullable":true},"marker":{"type":"string","description":"On `unfilled_template_key`, that key as the text writes it, such as `{first_name}` or `[company]`.\nOmitted otherwise.","nullable":true},"retryAt":{"type":"string","description":"On a warm path Start's `guardrail_connector_monthly`, `guardrail_account_monthly`,\n`guardrail_connector_cooldown` and `guardrail_handoff_weekly`, when the limit frees up, in UTC. Omitted\notherwise.","format":"date-time","nullable":true},"workspaceId":{"type":"integer","description":"On `last_admin`, a workspace that needs a new admin before the account can be deleted. On\n`new_admin_not_found`, the workspace of the refused choice. Omitted otherwise.","format":"int64","nullable":true},"workspaceName":{"type":"string","description":"On `last_admin`, the name of that workspace. Omitted otherwise.","nullable":true},"class":{"type":"string","description":"On a `rate_limited` detail from your workspace's rate limits, the class of call that hit its limit:\n`read`, `write`, `bulk`, `heavy` or `sensitive`. Omitted otherwise.","nullable":true},"window":{"type":"string","description":"On that detail, the window whose limit was hit: `minute`, `day` or `bulkItemsDay`. Omitted\notherwise.","nullable":true}},"additionalProperties":false,"description":"One problem in an error: the field or limit it is about, a stable `code` and a `message`. The other fields\nappear only with the codes their descriptions name."},"Failure":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false on an error."},"error":{"allOf":[{"$ref":"#/components/schemas/ErrorBody"}],"description":"What went wrong."},"quotaResetAt":{"type":"string","description":"When the quota that refused the request frees up, in UTC. Set on some quota refusals. Omitted otherwise.","format":"date-time","nullable":true},"currentVersion":{"type":"integer","description":"The current revision of a workflow draft, on a draft save's `409 version_conflict`. Read the workflow\nagain, then send this value as `baseVersion`. Omitted otherwise.","format":"int32","nullable":true},"current":{"allOf":[{"$ref":"#/components/schemas/MeetingRepNotesCurrent"}],"description":"Your meeting notes and their version as stored now, on a meeting notes save's `409 version_conflict`.\nMerge your change, then save again with `baseVersion` set to `current.repNotesVersion`. Omitted\notherwise."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"A copy of `error.refusal`, set on some billing refusals. Omitted otherwise."},"message":{"type":"string","description":"A copy of `error.message`, set together with `refusal`. Omitted otherwise.","nullable":true},"lookalikeSeeds":{"description":"How Kenso read each seed of a lookalike search, on its `422 no_usable_seeds`:\n`{resolved: [{input, companyId, personId, name, domain}], unresolved: [{input, reason}]}`. Use it to show\nwhy no seed was usable. Omitted otherwise."}},"additionalProperties":false,"description":"The body of every error, with a 4xx or 5xx status. Branch on `error.code`."},"InvalidationImpact":{"type":"object","properties":{"qualificationResponses":{"type":"integer","description":"Stored qualification answers the change would clear.","format":"int32"},"qualifiedFlags":{"type":"integer","description":"Contacts whose qualified result the change would clear.","format":"int32"},"segmentationReasoning":{"type":"integer","description":"Stored segmentation explanations the change would clear.","format":"int32"},"segmentationAssignmentsKept":{"type":"integer","description":"Contacts that keep their segment.","format":"int32"},"segmentationAssignmentsReset":{"type":"integer","description":"Contacts that go back to the default segment.","format":"int32"},"personalizationLines":{"type":"integer","description":"Personalized lines the change would clear.","format":"int32"},"personalizationLeads":{"type":"integer","description":"Contacts that would lose their personalized lines.","format":"int32"},"rewritingLines":{"type":"integer","description":"Rewritten lines the change would clear.","format":"int32"},"rewritingLeads":{"type":"integer","description":"Contacts that would lose their rewritten lines.","format":"int32"}},"additionalProperties":false,"description":"How much stored AI output a change would clear in each AI step of a campaign, and how many segment assignments it\nkeeps or resets."},"MeetingRepNotesCurrent":{"type":"object","properties":{"repNotes":{"type":"string","description":"Your notes as stored now. Empty before your first save."},"repNotesVersion":{"type":"integer","description":"The stored notes' version. Send it as `baseVersion` when you save again.","format":"int32"}},"additionalProperties":false,"description":"Your meeting notes as Kenso stores them now, sent with a `409 version_conflict` on a notes save."},"Pagination":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Send this value as `cursor` to get the next page. Omitted on the last page.","nullable":true},"hasMore":{"type":"boolean","description":"True when more items follow this page. Stop paging when it is false."},"total":{"type":"integer","description":"Deprecated: the same number as `totalCount`. Read `totalCount`.","format":"int32","nullable":true,"deprecated":true},"totalCount":{"type":"integer","description":"The number of items that match the list's filters, across all pages. Omitted when the list does not count them.","format":"int32","nullable":true},"isTotalCapped":{"type":"boolean","description":"True when `totalCount` stopped counting at its cap, so more items match than it says. Keep paging with\n`hasMore`. Omitted when `totalCount` is exact. Only `GET /v1/threads` with `q` caps its total.","nullable":true}},"additionalProperties":false,"description":"Where a list page ends and how to get the next page."},"RateLimitedText":{"type":"string","description":"The gateway's plain-text body of a `429` over the operation's own limit, until November 2026: `Number of requests exceeded. Please try again later.`","example":"Number of requests exceeded. Please try again later."},"Refusal":{"type":"object","properties":{"code":{"type":"string","description":"Stable refusal code in upper case, such as `CAMPAIGN_LIMIT_REACHED` or `INSUFFICIENT_CREDITS`."},"metric":{"type":"string","description":"What the limit counts: `Campaigns`, `Leads`, `Emails`, `LinkedInSeats` or `AiCredits`,\n`jobs_export_rows` or `funding_export_rows` for an export allowance, `credit_pack_credits`,\n`credit_spend_usd_7d`, `domains` or `mailboxes` for a limit on a new paying workspace, or for a\nKenso Lifetime cap its key: `workspaces`, `inboxes`, `contacts`, `email_verifications_day`,\n`email_verifications_month`, `people_results_day`, `company_results_day`,\n`funding_results_day`, `job_post_results_day`, `website_visits_month` or\n`visitor_lookups_day`. Omitted when a plan rule, not a count, refused the request.","nullable":true},"used":{"type":"integer","description":"How much of the limit is used, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"limit":{"type":"integer","description":"The limit, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"remaining":{"type":"integer","description":"How much of the limit is left, in the unit of `metric`. Omitted when the refusal has no count.","format":"int32","nullable":true},"planType":{"type":"string","description":"The workspace's plan as its snake plan id, for example `free`, `legacy_core` or `growth`."},"remedy":{"type":"string","description":"What lifts the refusal: `Upgrade`, `BuyAddOn`, `UpdatePaymentMethod` or `ContactSupport`.\n`None` means no action of yours lifts it."},"unlocksAt":{"type":"string","description":"When the limit lifts by itself, in UTC: for a limit on a new paying workspace once it has paid an invoice, and for\na Kenso Lifetime daily or monthly cap its reset (00:00 UTC, or the 1st of the month). Omitted on every other\nrefusal.","format":"date-time","nullable":true},"requiredMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits the action needed. 1,000 millicredits are one credit. Omitted on every\nother refusal.","format":"int64","nullable":true},"availableMillicredits":{"type":"integer","description":"On a credit refusal, the millicredits available. On `FREE_CREDITS_NOT_ELIGIBLE`, only the credits that may\npay for inboxes and domains. Omitted on every other refusal.","format":"int64","nullable":true},"restrictedMillicredits":{"type":"integer","description":"On `FREE_CREDITS_NOT_ELIGIBLE`, the free and bonus millicredits in the balance that cannot pay for inboxes\nand domains. Omitted on every other refusal.","format":"int64","nullable":true},"feature":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the plan feature the plan does not include, in snake case (for example\n`website_visitor_id`). Omitted on every other refusal.","nullable":true},"requiredPlan":{"type":"string","description":"On `PLAN_FEATURE_NOT_AVAILABLE`, the cheapest plan that includes `feature`, in snake case (for example\n`growth`). For a feature the self-serve trial locks (`browser_runs`), the trial's own plan,\nwhich paying for unlocks it. Omitted on every other refusal.","nullable":true},"requiredTier":{"type":"integer","description":"On a Kenso Lifetime refusal, the lowest tier that lifts it: the next tier with a higher cap, or the lowest tier\nthat includes `feature`. Omitted at the top tier, when no tier includes the feature, and on every other\nrefusal.","format":"int32","nullable":true},"upgradeUrl":{"type":"string","description":"On a Kenso Lifetime refusal that a higher tier lifts, the AppSumo page where the buyer upgrades their license.\nOmitted until Kenso has read that page from AppSumo, when no tier lifts the refusal, and on every other refusal.","nullable":true}},"additionalProperties":false,"description":"Why a plan rule or usage limit refused the request, and how to lift it."},"SavedList":{"type":"object","properties":{"id":{"type":"integer","description":"The saved list's id.","format":"int64"},"kind":{"allOf":[{"$ref":"#/components/schemas/SavedListKind"}],"description":"What the list holds: `people` or `companies`."},"visibility":{"allOf":[{"$ref":"#/components/schemas/SavedListVisibility"}],"description":"Who can read the list: `private` (its owner only), `workspace` (every member of the workspace) or\n`library` (every workspace, for a library list)."},"access":{"allOf":[{"$ref":"#/components/schemas/SavedListAccess"}],"description":"How this workspace reaches the list: `owner` (its own list), `shared` (shared with it through an\naccepted invite) or `library` (a library list)."},"name":{"type":"string","description":"The list's name."},"description":{"type":"string","description":"What the list is for. Null when the list has none.","nullable":true},"slug":{"type":"string","description":"The library list's slug, the value `GET /v1/saved-lists` takes in `slug`. Null on a list that is not\nin the library.","nullable":true},"icpTags":{"type":"array","items":{"type":"string"},"description":"Tags for the ideal customer profile the list fits. Empty when the list has none."},"libraryState":{"allOf":[{"$ref":"#/components/schemas/SavedListLibraryState"}],"description":"Where the list stands in the library review: `none`, `submitted`, `approved`, `rejected` or\n`retired`."},"publicPageEnabled":{"type":"boolean","description":"True when Kenso shows this library list on a public page of its website. Only a library list can have one."},"ownerUserId":{"type":"integer","description":"The user who owns the list. Null when an API key that belongs to no user created it, and on a library list.","format":"int64","nullable":true},"createdByUserId":{"type":"integer","description":"The user who created the list. Null when an API key that belongs to no user created it, and on a library list.","format":"int64","nullable":true},"rightsConfirmedAt":{"type":"string","description":"When a member last confirmed the right to share the list's uploaded data, in UTC. Null until someone confirms.","format":"date-time","nullable":true},"hasCsvMembers":{"type":"boolean","description":"True when the list holds members from a CSV upload. Always false on a shared or library list."},"counts":{"allOf":[{"$ref":"#/components/schemas/SavedListCounts"}],"description":"The list's member totals and breakdowns."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SavedListSource"},"description":"The sources that fill the list. On a shared or library list, each source's `parameters` is an empty object\nand its `statusMessage` and `addedByUserId` are null."},"lastRefreshedAt":{"type":"string","description":"When a source run last finished on the list, in UTC. Null until one has.","format":"date-time","nullable":true},"submittedAt":{"type":"string","description":"When the list was last submitted to the library, in UTC. Null if it never was.","format":"date-time","nullable":true},"reviewedAt":{"type":"string","description":"When Kenso last approved or rejected the list's submission, in UTC. Null before a review.","format":"date-time","nullable":true},"reviewReason":{"type":"string","description":"Why Kenso rejected the list's submission. Null otherwise, and on a list the workspace does not own.","nullable":true},"submittedByWorkspaceName":{"type":"string","description":"On a library list, the name of the workspace that submitted it. Omitted on every other list.","nullable":true},"createdAt":{"type":"string","description":"When the list was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the list last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"A saved list of people or companies, with its counts and sources."},"SavedListAccess":{"enum":["owner","shared","library"],"type":"string","description":"How the calling workspace reaches a saved list: `owner` for its own list, `shared` for a list another\nworkspace shared with it through an accepted invite, or `library` for a library list."},"SavedListCounts":{"type":"object","properties":{"members":{"type":"integer","description":"Number of members on the list.","format":"int32"},"sendableEmails":{"type":"integer","description":"Number of members with a sendable email address.","format":"int32"},"byCountry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per country, keyed by the stored country value."},"bySeniority":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per seniority, keyed by the stored seniority value."},"byIndustry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per industry, keyed by the stored industry value."},"byHeadcountBand":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per company headcount band, keyed by the stored band."}},"additionalProperties":false,"description":"A saved list's member counts. Each breakdown maps a stored value, such as a country, to the number of members that\nhave it. Use those values as the exact-match filters of the member list."},"SavedListGrant":{"type":"object","properties":{"id":{"type":"integer","description":"The grant's id.","format":"int64"},"savedListId":{"type":"integer","description":"The id of the shared saved list.","format":"int64"},"inviteeEmail":{"type":"string","description":"The email address the invite went to."},"status":{"allOf":[{"$ref":"#/components/schemas/SavedListGrantStatus"}],"description":"The grant's state: `pending` until someone accepts the invite, then `accepted`, or `revoked` once\nthe list's workspace revokes it."},"receivingWorkspaceId":{"type":"integer","description":"The workspace that accepted the invite. It stays after a revoke, so you can see who had the list. Omitted when\nnobody accepted.","format":"int64","nullable":true},"receivingWorkspaceName":{"type":"string","description":"The name of the workspace that accepted the invite. Omitted when nobody accepted.","nullable":true},"invitedByUserId":{"type":"integer","description":"The user who sent the invite. Omitted when an API key that belongs to no user sent it.","format":"int64","nullable":true},"acceptedAt":{"type":"string","description":"When the invite was accepted, in UTC. Omitted when nobody accepted.","format":"date-time","nullable":true},"revokedAt":{"type":"string","description":"When the grant was revoked, in UTC. Omitted unless the grant is revoked.","format":"date-time","nullable":true},"createdAt":{"type":"string","description":"When the invite was created, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"A grant: one email invite to read a saved list and, once someone accepts it, the read access of the workspace that\naccepted. The invite token never appears here: only the invite email carries it."},"SavedListGrantListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedListGrant"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"SavedListGrantResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/SavedListGrant"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListGrantStatus":{"enum":["pending","accepted","revoked"],"type":"string","description":"State of a saved list grant: `pending` until someone accepts the invite, `accepted` once a workspace reads\nthe list, or `revoked` once the list's workspace takes the access back."},"SavedListKind":{"enum":["people","companies"],"type":"string","description":"What a saved list holds: `people` or `companies`."},"SavedListLibraryState":{"enum":["none","submitted","approved","rejected","retired"],"type":"string","description":"Where a saved list stands in the library review: `none` (never submitted), `submitted` (waiting for\nKenso's review), `approved` (Kenso copied it into the library), `rejected` (Kenso declined it; the list's\n`reviewReason` says why) or `retired` (Kenso took the list out of the library)."},"SavedListListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedList"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"SavedListMember":{"type":"object","properties":{"id":{"type":"integer","description":"The member's id in this list.","format":"int64"},"identityKey":{"type":"string","description":"The key that makes the member unique in the list, prefixed by its type, for example `li:` for a LinkedIn\nprofile or `dom:` for a company domain. A key built from an email address shows as `em:` plus the\nmember id, so the address never appears."},"firstName":{"type":"string","description":"The person's first name.","nullable":true},"lastName":{"type":"string","description":"The person's last name.","nullable":true},"title":{"type":"string","description":"The person's job title.","nullable":true},"seniority":{"type":"string","description":"The person's seniority, as stored. The list's `counts.bySeniority` uses the same values.","nullable":true},"companyName":{"type":"string","description":"The company's name.","nullable":true},"companyDomain":{"type":"string","description":"The company's website domain, such as `example.com`.","nullable":true},"industry":{"type":"string","description":"The company's industry, as stored. The list's `counts.byIndustry` uses the same values.","nullable":true},"headcountBand":{"type":"string","description":"The company's headcount band, as stored. The list's `counts.byHeadcountBand` uses the same values.","nullable":true},"country":{"type":"string","description":"Country, as stored. The list's `counts.byCountry` uses the same values.","nullable":true},"state":{"type":"string","description":"State or region.","nullable":true},"city":{"type":"string","description":"City.","nullable":true},"linkedinUrl":{"type":"string","description":"LinkedIn URL of the person, or of the company on a company list.","nullable":true},"photoUrl":{"type":"string","description":"URL of the member's profile photo, as the source gave it when the member was added or last refreshed. Omitted when\nthere is none, or when the link has expired.","nullable":true},"hasSendableEmail":{"type":"boolean","description":"True when the member has at least one email address Kenso can send to."},"emailCount":{"type":"integer","description":"Number of email addresses the list holds for the member.","format":"int32"},"phoneCount":{"type":"integer","description":"Number of phone numbers the list holds for the member.","format":"int32"},"sources":{"type":"array","items":{"type":"string"},"description":"The types of source that added the member, such as `csv` or `library`, each listed once, in the order\nthey first added it."},"custom":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom fields from the source, keyed by field name in lowercase snake_case. Kenso leaves out any field whose name\npoints to an email address or a phone number, or whose value is one."}},"additionalProperties":false,"description":"One member of a saved list: a person on a people list or a company on a company list. A member never carries an email\naddress or a phone number, only how many the list holds. A field with no value is omitted."},"SavedListMemberFiltersBody":{"type":"object","properties":{"country":{"type":"string","description":"Country, matched exactly against the stored value. The list's `counts.byCountry` names the values.","nullable":true},"seniority":{"type":"string","description":"Seniority, matched exactly against the stored value. The list's `counts.bySeniority` names the values.","nullable":true},"title":{"type":"string","description":"Part of the member's job title, matched in any case.","nullable":true},"industry":{"type":"string","description":"Industry, matched exactly against the stored value. The list's `counts.byIndustry` names the values.","nullable":true},"headcountBand":{"type":"string","description":"Company headcount band, matched exactly against the stored value. The list's `counts.byHeadcountBand` names\nthe values.","nullable":true},"hasSendableEmail":{"type":"boolean","description":"Set to `true` to copy only members with a sendable email address, or `false` for only members without one.","nullable":true}},"additionalProperties":false,"description":"Filters that pick which members a copy takes. A member must match every filter you send, and an omitted filter\nmatches every member. Each text value takes up to 200 characters."},"SavedListMemberListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedListMember"},"description":"The items on this page."},"pagination":{"allOf":[{"$ref":"#/components/schemas/Pagination"}],"description":"Where this page ends and how to get the next one."}},"additionalProperties":false,"description":"The body of a successful list operation: one page of results in `data`, and `pagination` to get the next\npage."},"SavedListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/SavedList"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListRights":{"type":"object","properties":{"id":{"type":"integer","description":"The saved list's id.","format":"int64"},"kind":{"allOf":[{"$ref":"#/components/schemas/SavedListKind"}],"description":"What the list holds: `people` or `companies`."},"visibility":{"allOf":[{"$ref":"#/components/schemas/SavedListVisibility"}],"description":"Who can read the list: `private` (its owner only) or `workspace` (every member of the workspace)."},"access":{"type":"string","description":"How this workspace reaches the list. Always `owner`: only the list's own workspace confirms rights."},"name":{"type":"string","description":"The list's name."},"description":{"type":"string","description":"What the list is for. Null when the list has none.","nullable":true},"slug":{"type":"string","description":"The library list's slug. Null on a list that is not in the library.","nullable":true},"icpTags":{"type":"array","items":{"type":"string"},"description":"Tags for the ideal customer profile the list fits. Empty when the list has none."},"libraryState":{"allOf":[{"$ref":"#/components/schemas/SavedListLibraryState"}],"description":"Where the list stands in the library review: `none`, `submitted`, `approved`, `rejected` or\n`retired`."},"publicPageEnabled":{"type":"boolean","description":"True when Kenso shows this library list on a public page of its website. Only a library list can have one."},"ownerUserId":{"type":"integer","description":"The user who owns the list. Null when an API key that belongs to no user created it.","format":"int64","nullable":true},"createdByUserId":{"type":"integer","description":"The user who created the list. Null when an API key that belongs to no user created it.","format":"int64","nullable":true},"rightsConfirmedAt":{"type":"string","description":"When a member last confirmed the right to share the list's uploaded data, in UTC.","format":"date-time","nullable":true},"hasCsvMembers":{"type":"boolean","description":"True when the list holds members from a CSV upload."},"counts":{"allOf":[{"$ref":"#/components/schemas/SavedListRightsCounts"}],"description":"The list's member totals and breakdowns."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SavedListSource"},"description":"The sources that fill the list."},"lastRefreshedAt":{"type":"string","description":"When a source run last finished on the list, in UTC. Null until one has.","format":"date-time","nullable":true},"submittedAt":{"type":"string","description":"When the list was last submitted to the library, in UTC. Null if it never was.","format":"date-time","nullable":true},"reviewedAt":{"type":"string","description":"When Kenso last approved or rejected the list's submission, in UTC. Null before a review.","format":"date-time","nullable":true},"reviewReason":{"type":"string","description":"Why Kenso rejected the list's submission. Null otherwise.","nullable":true},"createdAt":{"type":"string","description":"When the list was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the list last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"The saved list after a rights confirmation, with its counts and sources. It has the same fields as\n`GET /v1/saved-lists/{savedListId}` returns for the workspace's own list."},"SavedListRightsCounts":{"type":"object","properties":{"members":{"type":"integer","description":"Number of members on the list.","format":"int32"},"sendableEmails":{"type":"integer","description":"Number of members with a sendable email address.","format":"int32"},"byCountry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per country, keyed by the stored country value."},"bySeniority":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per seniority, keyed by the stored seniority value."},"byIndustry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per industry, keyed by the stored industry value."},"byHeadcountBand":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per company headcount band, keyed by the stored band."}},"additionalProperties":false,"description":"A saved list's member counts. Each breakdown maps a stored value, such as a country, to the number of members that\nhave it."},"SavedListRightsResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/SavedListRights"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListSource":{"type":"object","properties":{"id":{"type":"integer","description":"The source's id.","format":"int64"},"sourceType":{"allOf":[{"$ref":"#/components/schemas/SavedListSourceType"}],"description":"What the source reads."},"parameters":{"description":"The source's settings, for example `{\"campaignId\": 42}`. A `csv` source holds the upload's details and,\nonce its run is done, `rowCount`, `inserted`, `merged` and `rejected`. An empty object on a\nshared or library list."},"status":{"allOf":[{"$ref":"#/components/schemas/SavedListSourceStatus"}],"description":"Progress of the source's last run: `pending`, `running`, `done` or `failed`."},"statusMessage":{"type":"string","description":"Why the run failed, or a note on a finished run, such as the row limit it stopped at. Null otherwise, and on a\nshared or library list.","nullable":true},"addedByUserId":{"type":"integer","description":"The user who added the source. Null when an API key that belongs to no user added it, and on a shared or library\nlist.","format":"int64","nullable":true},"lastRefreshedAt":{"type":"string","description":"When the source's last run finished, in UTC. Null before the first run finishes.","format":"date-time","nullable":true},"lastRefreshAdded":{"type":"integer","description":"Number of members the source's last run added to the list.","format":"int32"},"createdAt":{"type":"string","description":"When the source was added, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"One source of a saved list: a search, a selection, a saved search, a campaign, another list or a CSV upload that adds\nmembers to it, with the state of its last run."},"SavedListSourceArrayResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedListSource"},"description":"The result of the operation.","nullable":true}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListSourceResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/SavedListSource"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListSourceStatus":{"enum":["pending","running","done","failed"],"type":"string","description":"Progress of a saved list source's run: `pending` (waiting to run), `running`, `done` or `failed`\n(the source's `statusMessage` says why)."},"SavedListSourceType":{"enum":["search_filters","search_selection","saved_search","csv","campaign","list","vendor_import","registry","job_posts"],"type":"string","description":"What a saved list source reads: `search_filters` (a people search), `search_selection` (people picked in\nSearch), `saved_search`, `campaign` (a campaign's contacts), `list` (another saved list) or\n`csv` (an uploaded file). Library lists can also show `vendor_import`, `registry` and\n`job_posts`, which Kenso uses to build them."},"SavedListSubmission":{"type":"object","properties":{"id":{"type":"integer","description":"The saved list's id.","format":"int64"},"kind":{"allOf":[{"$ref":"#/components/schemas/SavedListKind"}],"description":"What the list holds: `people` or `companies`."},"visibility":{"allOf":[{"$ref":"#/components/schemas/SavedListVisibility"}],"description":"Who can read the list: `private` (its owner only) or `workspace` (every member of the workspace)."},"access":{"type":"string","description":"How this workspace reaches the list. Always `owner`: a workspace submits only its own lists."},"name":{"type":"string","description":"The list's name."},"description":{"type":"string","description":"What the list is for. Null when the list has none.","nullable":true},"slug":{"type":"string","description":"The library list's slug. Null on a list that is not in the library.","nullable":true},"icpTags":{"type":"array","items":{"type":"string"},"description":"Tags for the ideal customer profile the list fits. Empty when the list has none."},"libraryState":{"allOf":[{"$ref":"#/components/schemas/SavedListLibraryState"}],"description":"Where the list stands in the library review. After a submission it is `submitted`; the other values are\n`none`, `approved`, `rejected` and `retired`."},"publicPageEnabled":{"type":"boolean","description":"True when Kenso shows this library list on a public page of its website. Only a library list can have one."},"ownerUserId":{"type":"integer","description":"The user who owns the list. Null when an API key that belongs to no user created it.","format":"int64","nullable":true},"createdByUserId":{"type":"integer","description":"The user who created the list. Null when an API key that belongs to no user created it.","format":"int64","nullable":true},"rightsConfirmedAt":{"type":"string","description":"When a member last confirmed the right to share the list's uploaded data, in UTC. Null until someone confirms.","format":"date-time","nullable":true},"hasCsvMembers":{"type":"boolean","description":"True when the list holds members from a CSV upload."},"counts":{"allOf":[{"$ref":"#/components/schemas/SavedListSubmissionCounts"}],"description":"The list's member totals and breakdowns."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SavedListSource"},"description":"The sources that fill the list."},"lastRefreshedAt":{"type":"string","description":"When a source run last finished on the list, in UTC. Null until one has.","format":"date-time","nullable":true},"submittedAt":{"type":"string","description":"When the list was submitted to the library, in UTC.","format":"date-time","nullable":true},"reviewedAt":{"type":"string","description":"When Kenso last reviewed the list's submission, in UTC. Null after a new submission.","format":"date-time","nullable":true},"reviewReason":{"type":"string","description":"Why Kenso rejected the list's submission. Null after a new submission.","nullable":true},"createdAt":{"type":"string","description":"When the list was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the list last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"The saved list after a library submission, with its counts and sources. It has the same fields as\n`GET /v1/saved-lists/{savedListId}` returns for the workspace's own list."},"SavedListSubmissionCounts":{"type":"object","properties":{"members":{"type":"integer","description":"Number of members on the list.","format":"int32"},"sendableEmails":{"type":"integer","description":"Number of members with a sendable email address.","format":"int32"},"byCountry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per country, keyed by the stored country value."},"bySeniority":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per seniority, keyed by the stored seniority value."},"byIndustry":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per industry, keyed by the stored industry value."},"byHeadcountBand":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"Members per company headcount band, keyed by the stored band."}},"additionalProperties":false,"description":"A saved list's member counts. Each breakdown maps a stored value, such as a country, to the number of members that\nhave it."},"SavedListSubmissionResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/SavedListSubmission"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"SavedListVisibility":{"enum":["private","workspace","library"],"type":"string","description":"Who can read a saved list: `private` (only the member who owns it), `workspace` (every member of the\nworkspace) or `library` (every workspace, for a list in the library)."},"SubmitSavedListBody":{"type":"object","properties":{"icpTags":{"type":"array","items":{"type":"string"},"description":"Tags that replace the list's ICP tags: up to 20, each up to 50 characters, none blank. An empty array clears them.\nOmitted keeps the current tags.","nullable":true},"description":{"type":"string","description":"A description that replaces the list's own, up to 2,000 characters and not blank. Omitted keeps the current\ndescription.","nullable":true}},"additionalProperties":false,"description":"Optional changes to the list that the submission makes. An empty body submits the list as it is."},"TooManyRequestsError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The JSON body of a `429`: the error body (`Failure`), with code `rate_limited` or `quota_exceeded`, over your workspace's rate limits, your API key's own limit, the operation's own limit or a usage quota. Until November 2026, over your API key's own limit the API key check answered `{ \"error\": \"Rate limit exceeded\" }` (`ApiKeyError`), and over the operation's own limit the gateway answered plain text (`RateLimitedText`): `Number of requests exceeded. Please try again later.` A client built against those answers keeps working: handle each shape. Wait the `Retry-After` seconds."},"UnauthorizedError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `401`: the error body (`Failure`), whose `code` says what is wrong with the credential. Until November 2026, when the API key was not valid (unknown, expired or revoked, or its member no longer active), the API key check in front of the operations answered `{ \"error\": \"Invalid or revoked API key\" }` (`ApiKeyError`), and a request with no API key got a `401` that has no body. A client built against those answers keeps working: handle both shapes and a `401` with no body."},"UpdateSavedListBody":{"type":"object","properties":{"name":{"type":"string","description":"The new name, from 1 to 200 characters.","nullable":true},"description":{"type":"string","description":"The new description, up to 2,000 characters. `null` or a blank string clears it.","nullable":true},"visibility":{"type":"string","description":"Who can read the list: `workspace` or `private`. Only the list's owner can make it private.","nullable":true},"icpTags":{"type":"array","items":{"type":"string"},"description":"The new tags, which replace the old ones: up to 20, each up to 50 characters. An empty array clears them.","nullable":true}},"additionalProperties":false,"description":"The fields to change on a saved list. An omitted field keeps its value."}}}}