{"openapi":"3.0.4","info":{"title":"Kenso API: Blocklist rules","version":"1.1","description":"The Blocklist rules 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":"blocklist-rules","description":"Blocklist rules keep the blocklist in step with your accounts and your CRM. A rule blocks the domains of accounts\nwith an opportunity in chosen stages, in chosen account stages or with chosen account types, and, from a connected\nCRM, the records in chosen lifecycle stages or on one CRM list. Kenso adds and removes a rule's entries as its matches change, and those entries\nshow `source: rule` in `GET /v1/blocklist-entries`. A rule never changes an entry from another source, and\na workspace has at most 20 rules.","x-displayName":"Blocklist rules"}],"paths":{"/v1/blocklist-rules":{"get":{"tags":["blocklist-rules"],"summary":"List blocklist rules","description":"Lists every blocklist rule of the workspace in `position` order. A workspace has at most 20 rules, so the\nlist has one page.\n            \nEach rule has `matches`: the accounts, domains, people (emails) and CRM records it matches now, counted\nwhether the rule is enabled or not. A rule with a CRM list has `crmList`, with the member count and the time\nof Kenso's last read. When several enabled rules match the same domain or email, the first one by\n`position` gives the entry its reason.\n            \nOpen to any workspace member.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.","operationId":"blocklist-rules.list","parameters":[{"name":"limit","in":"query","description":"Items per page, from 1 to 200. Omit `limit` and `cursor` to get every item in one response, as before; with only `cursor`, 50 per page.","schema":{"maximum":200,"minimum":1,"type":"integer","format":"int32"}},{"name":"cursor","in":"query","description":"The `nextCursor` of 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/BlocklistRuleListResponse"}}}},"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":["blocklist_rules"],"x-ken-permission":{"kind":"workspace_member","summary":"Any workspace member except a Network member"},"x-ken-rate-limit":{"limit":12000,"windowSeconds":60,"per":"api_key"}},"post":{"tags":["blocklist-rules"],"summary":"Create a blocklist rule","description":"Creates a blocklist rule and applies it right away. The rule goes last in `position` order. When it is\nenabled, its domains and emails are on the blocklist when the call returns.\n            \n`name` (from 1 to 100 characters) and `reason` (from 1 to 200 characters) are required. Kenso puts the\nreason on every entry the rule adds. Send at least one criterion:\n            \n- `stages`: up to 20 opportunity stage keys from `GET /v1/opportunity-stages`, none archived. The rule\n  matches accounts with an opportunity in one of these stages.\n- `accountStages`: up to 16 account stages, any of `warming`, `engaged`, `meeting_booked`,\n  `in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`,\n  `network`, `not_a_fit`, `competitor` and `do_not_contact`. The rule matches accounts in one\n  of these stages. `new` and `researching` are not allowed, because every new account starts there.\n- `accountTypes`: any of `client`, `lost`, `churned`, `partner`, `competitor`,\n  `investor` and `do_not_contact`. `prospect` is not allowed, because every new account is a\n  prospect. Kept for older callers: use `accountStages`.\n- `crmLifecycles`: up to 5 CRM lifecycle stages, any of `lead`, `prospect`, `opportunity`,\n  `customer` and `churned`, holding at most 10,000 CRM records. A CRM company blocks its domain. A CRM\n  contact blocks its company domain, or its email when it has only a free email domain.\n- `crmListId`: a contact or company list from `GET /v1/crm-connections/{connectionId}/lists`, with at\n  most 10,000 members. A contact list blocks its people's emails, and a company list blocks its companies'\n  domains. Kenso reads the list right away and again about every 15 minutes.\n            \n`enabled` is true by default. `releaseAfterDays`, from 1 to 3650, lets an account matched by stage go\nthat many days after its deal in those stages closed. A deal with no close date, a match by account stage or\naccount type and a CRM match never release.\n            \nThe CRM criteria use the workspace's connected CRM, which the rule records as `crmConnectionId`. A domain or\nemail that another entry already lists keeps that entry, and Kenso never blocks a free email domain.\n            \nErrors:\n            \n- `400 validation_failed`: a field is missing or invalid, or no criterion is sent. `error.details` names\n  each field, with the same codes as `GET /v1/blocklist-rules/preview`.\n- `409 conflict`: the workspace already has 20 rules.\n- `429 rate_limited`: the CRM rate-limited Kenso. Retry after the number of seconds in the\n  `Retry-After` header.\n- `503 service_unavailable`: Kenso could not reach the CRM.\n            \nRequires the `workspace_settings` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.","operationId":"blocklist-rules.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/CreateBlocklistRuleBody"}}}},"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/BlocklistRuleResponse"}}}},"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"]},"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"]},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-features":["blocklist_rules"],"x-ken-permission":{"kind":"feature","features":["workspace_settings"],"summary":"The `workspace_settings` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/blocklist-rules/{ruleId}":{"patch":{"tags":["blocklist-rules"],"summary":"Update a blocklist rule","description":"Changes a blocklist rule. Fields you leave out keep their value, and the blocklist follows the change right away.\n            \nSend any of `name`, `reason`, `enabled`, `position`, `stages`, `accountStages`,\n`accountTypes`, `crmLifecycles`, `crmListId` and `releaseAfterDays`, with the rules of create.\n`position` is 0-based: Kenso moves the rule there and renumbers the rest, and a position past the last rule\nmoves it last. `stages`, `accountStages`, `accountTypes` and `crmLifecycles` can be `[]`\nto clear them, as long as the rule keeps one criterion. Only `releaseAfterDays` and `crmListId` can be `null`: a null\n`releaseAfterDays` means the rule never releases, and a null `crmListId` drops the list. Kenso reads a\nnew list right away.\n            \nSetting a CRM criterion uses the workspace's connected CRM, and clearing both CRM criteria clears\n`crmConnectionId`. A CRM list or lifecycle stages that the rule keeps from another CRM account than the one\nconnected now fail with detail code `invalid_state`: send them again or clear them.\n            \nAfter the change, entries that no enabled rule matches come off the blocklist, and entries whose first matching\nrule changed take that rule's reason.\n            \nErrors:\n            \n- `400 validation_failed`: a field is unknown or invalid, a field other than `releaseAfterDays` and\n  `crmListId` is `null`, `position` is negative, or the change leaves the rule with no criterion.\n  `error.details` names each field.\n- `404 not_found`: no rule of this workspace has the id.\n- `429 rate_limited`: the CRM rate-limited Kenso. Retry after the number of seconds in the\n  `Retry-After` header.\n- `503 service_unavailable`: Kenso could not reach the CRM.\n            \nRequires the `workspace_settings` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.","operationId":"blocklist-rules.update","parameters":[{"name":"ruleId","in":"path","description":"The rule's id, as `GET /v1/blocklist-rules` 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"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBlocklistRuleBody"}}}},"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/BlocklistRuleResponse"}}}},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-features":["blocklist_rules"],"x-ken-permission":{"kind":"feature","features":["workspace_settings"],"summary":"The `workspace_settings` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}},"delete":{"tags":["blocklist-rules"],"summary":"Delete a blocklist rule","description":"Deletes a blocklist rule, and Kenso renumbers the rules after it. Entries that only this rule matched come off the\nblocklist right away.\n            \nErrors:\n            \n- `404 not_found`: no rule of this workspace has the id.\n            \nRequires the `workspace_settings` permission.\n\nRate limit: 4,800 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.","operationId":"blocklist-rules.delete","parameters":[{"name":"ruleId","in":"path","description":"The rule'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":["blocklist_rules"],"x-ken-permission":{"kind":"feature","features":["workspace_settings"],"summary":"The `workspace_settings` permission"},"x-ken-rate-limit":{"limit":4800,"windowSeconds":60,"per":"api_key"}}},"/v1/blocklist-rules/preview":{"get":{"tags":["blocklist-rules"],"summary":"Preview a blocklist rule","description":"Shows what a rule with these criteria would block, without saving anything. Use it to check a rule before you\ncreate or change it.\n            \nSend at least one criterion: `stages`, `accountStages`, `accountTypes`, `crmLifecycles` or\n`crmListId`, with the rules of `POST /v1/blocklist-rules`. Lists are comma-separated. Kenso reads the CRM list live and does not\nstore it. `releaseAfterDays` previews a release window: an account matched by stage counts only while one of\nits deals in those stages closed less than that many days ago or has no close date.\n            \nThe answer counts the matched accounts, the domains and people (emails) the rule would block, the matched CRM\nrecords, and how many of those domains and people the blocklist already holds from any source\n(`alreadyBlocked`). It shows up to 10 accounts and up to 10 CRM records as samples, and counts in\n`skipped` what it leaves out.\n            \nErrors:\n            \n- `400 validation_failed`: no criterion is sent, or a criterion is invalid. Each entry in\n  `error.details` names the field and a code: `out_of_range` for an unknown or archived stage, an unknown\n  account stage, `new` or `researching`, an unknown account type or `prospect`, a list over its limit, a `releaseAfterDays` outside 1 to 3650, or an\n  unknown or too large CRM list; `not_enabled` when CRM criteria are not turned on for the workspace;\n  `invalid_state` when no CRM is connected; `unsupported` when Kenso cannot read lists or lifecycle\n  stages from the connected CRM, or the list is not a contact or company list.\n- `429 rate_limited`: the CRM rate-limited Kenso. Retry after the number of seconds in the\n  `Retry-After` header.\n- `503 service_unavailable`: Kenso could not reach the CRM.\n            \nRequires Accounts view.\n\nRate limit: 12,000 calls a minute per API key, on top of the workspace limits.\n\nNeeds the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.","operationId":"blocklist-rules.preview","parameters":[{"name":"stages","in":"query","description":"Comma-separated stage keys from `GET /v1/opportunity-stages`, up to 20. The preview matches accounts with a live\nopportunity in one of these stages.","schema":{"type":"string"}},{"name":"accountTypes","in":"query","description":"Comma-separated account types to match: `client`, `lost`, `churned`, `partner`,\n`competitor`, `investor` or `do_not_contact`. A rule cannot match `prospect`. Kept for older\ncallers: use `accountStages`.","schema":{"type":"string"}},{"name":"accountStages","in":"query","description":"Comma-separated account stages to match, up to 16: `warming`, `engaged`, `meeting_booked`,\n`in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`,\n`network`, `not_a_fit`, `competitor` or `do_not_contact`. A rule cannot match `new` or\n`researching`.","schema":{"type":"string"}},{"name":"releaseAfterDays","in":"query","description":"A release window to preview, in days from 1 to 3650. With it, an account matched by stage counts only while one of\nits deals in those stages closed fewer days ago than this or has no close date.","schema":{"type":"integer","format":"int32"}},{"name":"crmListId","in":"query","description":"The id of a contact or company list in the workspace's connected CRM, from\n`GET /v1/crm-connections/{connectionId}/lists`. Kenso reads the list live and does not store it.","schema":{"type":"string"}},{"name":"crmLifecycles","in":"query","description":"Comma-separated CRM lifecycle stages to match, up to 5: `lead`, `prospect`, `opportunity`,\n`customer` or `churned`.","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/BlocklistRulePreviewResponse"}}}},"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"]},"503":{"description":"Service Unavailable","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/ServiceUnavailableError"}}},"x-ken-error-codes":["service_unavailable"]}},"x-ken-features":["blocklist_rules"],"x-ken-permission":{"kind":"page","page":"accounts","access":"view","summary":"Accounts view"},"x-ken-rate-limit":{"limit":12000,"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."},"BlocklistRule":{"type":"object","properties":{"id":{"type":"integer","description":"The rule's id.","format":"int64"},"name":{"type":"string","description":"The rule's name, from 1 to 100 characters."},"stages":{"type":"array","items":{"type":"string"},"description":"Opportunity stage keys from `GET /v1/opportunity-stages`. The rule matches accounts with an opportunity in\none of them. Empty when the rule does not match by stage."},"accountTypes":{"type":"array","items":{"type":"string"},"description":"Account types the rule matches: any of `client`, `lost`, `churned`, `partner`,\n`competitor`, `investor` and `do_not_contact`. Empty when the rule does not match by type. Kept for\nolder callers: account stages replace account types."},"accountStages":{"type":"array","items":{"type":"string"},"description":"Account stages the rule matches: any of `warming`, `engaged`, `meeting_booked`, `in_deal`,\n`onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`, `network`,\n`not_a_fit`, `competitor` and `do_not_contact`. Empty when the rule does not match by account stage."},"reason":{"type":"string","description":"The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters."},"enabled":{"type":"boolean","description":"True when the rule adds entries to the blocklist. A disabled rule still shows its `matches`."},"position":{"type":"integer","description":"The rule's place in the list, starting at 0. When several enabled rules match a domain or email, the first one\ngives the entry its reason.","format":"int32"},"releaseAfterDays":{"type":"integer","description":"From 1 to 3650 days. An account matched by stage comes off the blocklist that many days after its deal in those\nstages closed. A deal with no close date, a match by account type or account stage and a CRM match never release.\nAbsent when the rule never releases.","format":"int32","nullable":true},"crmConnectionId":{"type":"integer","description":"The id of the CRM connection the rule's CRM criteria use. Absent when the rule has no CRM criterion.","format":"int64","nullable":true},"crmLifecycles":{"type":"array","items":{"type":"string"},"description":"CRM lifecycle stages the rule matches: any of `lead`, `prospect`, `opportunity`, `customer`\nand `churned`. A CRM company in one of them blocks its domain. A CRM contact blocks its company domain, or its\nemail when it has only a free email domain."},"crmList":{"allOf":[{"$ref":"#/components/schemas/BlocklistRuleCrmList"}],"description":"The CRM list the rule matches. A contact list blocks its people's emails, and a company list blocks its companies'\ndomains. Absent when the rule has no list."},"matches":{"allOf":[{"$ref":"#/components/schemas/BlocklistRuleMatches"}],"description":"What the rule matches now, counted whether the rule is enabled or not."},"createdAt":{"type":"string","description":"When the rule was created, in UTC.","format":"date-time"},"updatedAt":{"type":"string","description":"When the rule last changed, in UTC.","format":"date-time"}},"additionalProperties":false,"description":"A blocklist rule."},"BlocklistRuleCrmList":{"type":"object","properties":{"externalId":{"type":"string","description":"The list's id in the CRM, as `GET /v1/crm-connections/{connectionId}/lists` returns it."},"name":{"type":"string","description":"The list's name in the CRM when the rule was saved.","nullable":true},"objectType":{"type":"string","description":"What the list holds: `contact` or `company`."},"members":{"type":"integer","description":"The number of members at Kenso's last successful read. Absent before the first read. Kenso reads the list again\nabout every 15 minutes, and someone who has left the list comes off the blocklist then.","format":"int32","nullable":true},"readAt":{"type":"string","description":"When Kenso last read the list, in UTC. Absent before the first read.","format":"date-time","nullable":true}},"additionalProperties":false,"description":"The CRM list a blocklist rule matches."},"BlocklistRuleCrmSample":{"type":"object","properties":{"externalId":{"type":"string","description":"The record's id in the CRM."},"name":{"type":"string","description":"The record's name in the CRM. Absent when it has none.","nullable":true},"value":{"type":"string","description":"The email or domain the record would block."}},"additionalProperties":false,"description":"A CRM record a previewed rule would block."},"BlocklistRuleListResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"type":"array","items":{"$ref":"#/components/schemas/BlocklistRule"},"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."},"BlocklistRuleMatches":{"type":"object","properties":{"accounts":{"type":"integer","description":"Accounts with an opportunity in one of the rule's stages (inside the release window, if the rule has one), with\none of its account types or in one of its account stages, each counted once.","format":"int32"},"domains":{"type":"integer","description":"Distinct domains the rule blocks: those of the matched accounts and of the matched CRM companies and contacts.\nFree email domains are left out.","format":"int32"},"people":{"type":"integer","description":"Distinct emails the rule blocks: the people on a contact list, and CRM contacts that have only a free email domain.","format":"int32"},"crmRecords":{"type":"integer","description":"CRM records the rule matches: those in its lifecycle stages, plus its list's members as last read.","format":"int32"}},"additionalProperties":false,"description":"What a blocklist rule matches now."},"BlocklistRulePreview":{"type":"object","properties":{"accounts":{"type":"integer","description":"Accounts with an opportunity in one of the stages (inside the release window, if you sent one), with one of the\naccount types or in one of the account stages, each counted once.","format":"int32"},"domains":{"type":"integer","description":"Distinct domains the rule would block: those of the matched accounts and of the matched CRM companies and\ncontacts. Free email domains are left out.","format":"int32"},"people":{"type":"integer","description":"Distinct emails the rule would block: the people on a contact list, and CRM contacts that have only a free email\ndomain.","format":"int32"},"crmRecords":{"type":"integer","description":"CRM records matched: those in the lifecycle stages, plus the list's members as read now.","format":"int32"},"alreadyBlocked":{"type":"integer","description":"How many of the `domains` and `people` the blocklist already holds, from any source.","format":"int32"},"sample":{"type":"array","items":{"$ref":"#/components/schemas/BlocklistRuleSample"},"description":"Up to 10 matched accounts, each with one of its domains, in account id order."},"crmSample":{"type":"array","items":{"$ref":"#/components/schemas/BlocklistRuleCrmSample"},"description":"Up to 10 matched CRM records, each with the email or domain it would block. List members come first."},"skipped":{"allOf":[{"$ref":"#/components/schemas/BlocklistRuleSkipped"}],"description":"What the rule matched but would not block, counted by reason."}},"additionalProperties":false,"description":"What a blocklist rule with the previewed criteria would block now."},"BlocklistRulePreviewResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/BlocklistRulePreview"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"BlocklistRuleResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on a success."},"data":{"allOf":[{"$ref":"#/components/schemas/BlocklistRule"}],"description":"The result of the operation."}},"additionalProperties":false,"description":"The body of a successful operation that returns one result. The result is in `data`."},"BlocklistRuleSample":{"type":"object","properties":{"accountId":{"type":"integer","description":"The account's id.","format":"int64"},"name":{"type":"string","description":"The account's name."},"domain":{"type":"string","description":"One of the account's domains that the rule would block."}},"additionalProperties":false,"description":"An account a previewed rule would block."},"BlocklistRuleSkipped":{"type":"object","properties":{"noDomain":{"type":"integer","description":"Matched accounts and CRM companies that have no domain.","format":"int32"},"noEmail":{"type":"integer","description":"Matched CRM contacts that have neither a company domain nor a valid email.","format":"int32"},"freeMail":{"type":"integer","description":"Matched domains that are free or shared email providers. Kenso never blocks those as a domain.","format":"int32"},"released":{"type":"integer","description":"Accounts in one of the stages that the release window already let go, because every such deal closed at least\n`releaseAfterDays` ago. 0 without a release window.","format":"int32"}},"additionalProperties":false,"description":"What a previewed rule matched but would not block."},"CreateBlocklistRuleBody":{"required":["name","reason"],"type":"object","properties":{"name":{"type":"string","description":"The rule's name, from 1 to 100 characters. Required."},"stages":{"type":"array","items":{"type":"string"},"description":"Up to 20 opportunity stage keys from `GET /v1/opportunity-stages`, none archived. The rule matches accounts\nwith an opportunity in one of them.","nullable":true},"accountTypes":{"type":"array","items":{"type":"string"},"description":"Account types to match: any of `client`, `lost`, `churned`, `partner`, `competitor`,\n`investor` and `do_not_contact`. `prospect` is not allowed. Omitted means none. Kept for older\ncallers: use `accountStages`.","nullable":true},"accountStages":{"type":"array","items":{"type":"string"},"description":"Account stages to match, at most 16: any of `warming`, `engaged`, `meeting_booked`,\n`in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`,\n`network`, `not_a_fit`, `competitor` and `do_not_contact`. `new` and\n`researching` are not allowed. Omitted means none.","nullable":true},"reason":{"type":"string","description":"The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. Required."},"enabled":{"type":"boolean","description":"Whether the rule adds entries to the blocklist. `true` by default.","nullable":true},"releaseAfterDays":{"type":"integer","description":"From 1 to 3650 days: an account matched by stage comes off the blocklist that many days after its deal closed.\nOmitted or `null` means the rule never releases.","format":"int32","nullable":true},"crmListId":{"type":"string","description":"A contact or company list of the workspace's connected CRM, from\n`GET /v1/crm-connections/{connectionId}/lists`, with at most 10,000 members. The CRM must be one Kenso reads\nlists from.","nullable":true},"crmLifecycles":{"type":"array","items":{"type":"string"},"description":"CRM lifecycle stages to match, at most 5: any of `lead`, `prospect`, `opportunity`,\n`customer` and `churned`. The CRM must be one Kenso reads lifecycle stages from, such as HubSpot or\nSalesforce.","nullable":true}},"additionalProperties":false,"description":"The fields of a new blocklist rule. A rule needs at least one stage, account type, account stage, CRM lifecycle stage\nor CRM 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."},"ServiceUnavailableError":{"oneOf":[{"$ref":"#/components/schemas/Failure"},{"$ref":"#/components/schemas/ApiKeyError"}],"description":"The body of a `503`: the error body (`Failure`). When Kenso cannot check the API key, its code is `auth_unavailable`, with `Retry-After: 5`. Until November 2026 the API key check in front of the operations answered `{ \"error\": \"Authentication is temporarily unavailable\" }` (`ApiKeyError`) there instead, so handle both shapes. Retry after the `Retry-After` seconds."},"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."},"UpdateBlocklistRuleBody":{"type":"object","properties":{"name":{"type":"string","description":"The rule's name, from 1 to 100 characters.","nullable":true},"stages":{"type":"array","items":{"type":"string"},"description":"Up to 20 opportunity stage keys from `GET /v1/opportunity-stages`, none archived. `[]` clears them, as\nlong as the rule keeps another criterion.","nullable":true},"accountTypes":{"type":"array","items":{"type":"string"},"description":"Account types to match, with the values of create. `[]` clears them, as long as the rule keeps another\ncriterion.","nullable":true},"accountStages":{"type":"array","items":{"type":"string"},"description":"Account stages to match, with the values of create. `[]` clears them, as long as the rule keeps another\ncriterion.","nullable":true},"reason":{"type":"string","description":"The reason on every blocklist entry the rule adds, from 1 to 200 characters.","nullable":true},"enabled":{"type":"boolean","description":"Whether the rule adds entries to the blocklist.","nullable":true},"position":{"type":"integer","description":"The rule's new place, starting at 0. A position past the last rule moves it last.","format":"int32","nullable":true},"releaseAfterDays":{"type":"integer","description":"From 1 to 3650 days: an account matched by stage comes off the blocklist that many days after its deal closed.\n`null` means the rule never releases.","format":"int32","nullable":true},"crmListId":{"type":"string","description":"A contact or company list of the connected CRM. `null` drops the list.","nullable":true},"crmLifecycles":{"type":"array","items":{"type":"string"},"description":"CRM lifecycle stages to match, with the values of create. `[]` clears them, as long as the rule keeps another\ncriterion.","nullable":true}},"additionalProperties":false,"description":"The fields to change on a blocklist rule. Fields you leave out keep their value. Only `releaseAfterDays` and\n`crmListId` can be `null`."}}}}