Blocklist rules
Rules that block contacts by pattern.
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List blocklist rules
/v1/blocklist-rulesblocklist-rules.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
blocklist_rules feature on your workspace. Until it is on, calls answer 404.Lists every blocklist rule of the workspace in position order. A workspace has at most 20 rules, so the list has one page.
Each rule has matches: the accounts, domains, people (emails) and CRM records it matches now, counted whether the rule is enabled or not. A rule with a CRM list has crmList, with the member count and the time of Kenso's last read. When several enabled rules match the same domain or email, the first one by position gives the entry its reason.
Open to any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | 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. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/blocklist-rules?limit=1" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of BlocklistRule. Each item has these fields. The response also carries pagination.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create a blocklist rule
/v1/blocklist-rulesblocklist-rules.create- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
blocklist_rules feature on your workspace. Until it is on, calls answer 404.Creates a blocklist rule and applies it right away. The rule goes last in position order. When it is enabled, its domains and emails are on the blocklist when the call returns.
name (from 1 to 100 characters) and reason (from 1 to 200 characters) are required. Kenso puts the reason on every entry the rule adds. Send at least one criterion:
stages: up to 20 opportunity stage keys fromGET /v1/opportunity-stages, none archived. The rule matches accounts with an opportunity in one of these stages.accountStages: up to 16 account stages, any ofwarming,engaged,meeting_booked,in_deal,onboarding,client,churned,nurture,paused,lost,network,not_a_fit,competitoranddo_not_contact. The rule matches accounts in one of these stages.newandresearchingare not allowed, because every new account starts there.accountTypes: any ofclient,lost,churned,partner,competitor,investoranddo_not_contact.prospectis not allowed, because every new account is a prospect. Kept for older callers: useaccountStages.crmLifecycles: up to 5 CRM lifecycle stages, any oflead,prospect,opportunity,customerandchurned, holding at most 10,000 CRM records. A CRM company blocks its domain. A CRM contact blocks its company domain, or its email when it has only a free email domain.crmListId: a contact or company list fromGET /v1/crm-connections/{connectionId}/lists, with at most 10,000 members. A contact list blocks its people's emails, and a company list blocks its companies' domains. Kenso reads the list right away and again about every 15 minutes.
enabled is true by default. releaseAfterDays, from 1 to 3650, lets an account matched by stage go that many days after its deal in those stages closed. A deal with no close date, a match by account stage or account type and a CRM match never release.
The CRM criteria use the workspace's connected CRM, which the rule records as crmConnectionId. A domain or email that another entry already lists keeps that entry, and Kenso never blocks a free email domain.
Errors:
400 validation_failed: a field is missing or invalid, or no criterion is sent.error.detailsnames each field, with the same codes asGET /v1/blocklist-rules/preview.409 conflict: the workspace already has 20 rules.429 rate_limited: the CRM rate-limited Kenso. Retry after the number of seconds in theRetry-Afterheader.503 service_unavailable: Kenso could not reach the CRM.
Requires the workspace_settings permission.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | The rule's name, from 1 to 100 characters. Required. |
stages | array of string | optional | Up to 20 opportunity stage keys from GET /v1/opportunity-stages, none archived. The rule matches accounts with an opportunity in one of them. |
accountTypes | array of string | optional | Account types to match: any of client, lost, churned, partner, competitor, investor and do_not_contact. prospect is not allowed. Omitted means none. Kept for older callers: use accountStages. |
accountStages | array of string | optional | Account stages to match, at most 16: any of warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor and do_not_contact. new and researching are not allowed. Omitted means none. |
reason | string | required | The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. Required. |
enabled | boolean | optional | Whether the rule adds entries to the blocklist. true by default. |
releaseAfterDays | integer (int32) | optional | From 1 to 3650 days: an account matched by stage comes off the blocklist that many days after its deal closed. Omitted or null means the rule never releases. |
crmListId | string | optional | A contact or company list of the workspace's connected CRM, from GET /v1/crm-connections/{connectionId}/lists, with at most 10,000 members. The CRM must be one Kenso reads lists from. |
crmLifecycles | array of string | optional | CRM lifecycle stages to match, at most 5: any of lead, prospect, opportunity, customer and churned. The CRM must be one Kenso reads lifecycle stages from, such as HubSpot or Salesforce. |
curl -X POST "https://api.ken.so/v1/blocklist-rules" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"stages": [
"string"
],
"accountTypes": [
"string"
],
"accountStages": [
"string"
],
"reason": "string",
"enabled": true,
"releaseAfterDays": 1,
"crmListId": "string",
"crmLifecycles": [
"string"
]
}'Response 201
data is a BlocklistRule.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Update a blocklist rule
/v1/blocklist-rules/{ruleId}blocklist-rules.update- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
blocklist_rules feature on your workspace. Until it is on, calls answer 404.Changes a blocklist rule. Fields you leave out keep their value, and the blocklist follows the change right away.
Send any of name, reason, enabled, position, stages, accountStages, accountTypes, crmLifecycles, crmListId and releaseAfterDays, with the rules of create. position is 0-based: Kenso moves the rule there and renumbers the rest, and a position past the last rule moves it last. stages, accountStages, accountTypes and crmLifecycles can be [] to clear them, as long as the rule keeps one criterion. Only releaseAfterDays and crmListId can be null: a null releaseAfterDays means the rule never releases, and a null crmListId drops the list. Kenso reads a new list right away.
Setting a CRM criterion uses the workspace's connected CRM, and clearing both CRM criteria clears crmConnectionId. A CRM list or lifecycle stages that the rule keeps from another CRM account than the one connected now fail with detail code invalid_state: send them again or clear them.
After the change, entries that no enabled rule matches come off the blocklist, and entries whose first matching rule changed take that rule's reason.
Errors:
400 validation_failed: a field is unknown or invalid, a field other thanreleaseAfterDaysandcrmListIdisnull,positionis negative, or the change leaves the rule with no criterion.error.detailsnames each field.404 not_found: no rule of this workspace has the id.429 rate_limited: the CRM rate-limited Kenso. Retry after the number of seconds in theRetry-Afterheader.503 service_unavailable: Kenso could not reach the CRM.
Requires the workspace_settings permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ruleId | path | integer (int64) | required | The rule's id, as GET /v1/blocklist-rules returns it. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | optional | The rule's name, from 1 to 100 characters. |
stages | array of string | optional | Up to 20 opportunity stage keys from GET /v1/opportunity-stages, none archived. [] clears them, as long as the rule keeps another criterion. |
accountTypes | array of string | optional | Account types to match, with the values of create. [] clears them, as long as the rule keeps another criterion. |
accountStages | array of string | optional | Account stages to match, with the values of create. [] clears them, as long as the rule keeps another criterion. |
reason | string | optional | The reason on every blocklist entry the rule adds, from 1 to 200 characters. |
enabled | boolean | optional | Whether the rule adds entries to the blocklist. |
position | integer (int32) | optional | The rule's new place, starting at 0. A position past the last rule moves it last. |
releaseAfterDays | integer (int32) | optional | From 1 to 3650 days: an account matched by stage comes off the blocklist that many days after its deal closed. null means the rule never releases. |
crmListId | string | optional | A contact or company list of the connected CRM. null drops the list. |
crmLifecycles | array of string | optional | CRM lifecycle stages to match, with the values of create. [] clears them, as long as the rule keeps another criterion. |
curl -X PATCH "https://api.ken.so/v1/blocklist-rules/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"stages": [
"string"
],
"accountTypes": [
"string"
],
"accountStages": [
"string"
],
"reason": "string",
"enabled": true,
"position": 1,
"releaseAfterDays": 1,
"crmListId": "string",
"crmLifecycles": [
"string"
]
}'Response 200
data is a BlocklistRule.
Show the 15 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete a blocklist rule
/v1/blocklist-rules/{ruleId}blocklist-rules.delete- Permission
- The
workspace_settingspermission - Rate limit
- 4,800 requests a minute per API key
blocklist_rules feature on your workspace. Until it is on, calls answer 404.Deletes a blocklist rule, and Kenso renumbers the rules after it. Entries that only this rule matched come off the blocklist right away.
Errors:
404 not_found: no rule of this workspace has the id.
Requires the workspace_settings permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ruleId | path | integer (int64) | required | The rule's id. |
curl -X DELETE "https://api.ken.so/v1/blocklist-rules/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentPreview a blocklist rule
/v1/blocklist-rules/previewblocklist-rules.preview- Permission
- Accounts view
- Rate limit
- 12,000 requests a minute per API key
blocklist_rules feature on your workspace. Until it is on, calls answer 404.Shows what a rule with these criteria would block, without saving anything. Use it to check a rule before you create or change it.
Send at least one criterion: stages, accountStages, accountTypes, crmLifecycles or crmListId, with the rules of POST /v1/blocklist-rules. Lists are comma-separated. Kenso reads the CRM list live and does not store it. releaseAfterDays previews a release window: an account matched by stage counts only while one of its deals in those stages closed less than that many days ago or has no close date.
The answer counts the matched accounts, the domains and people (emails) the rule would block, the matched CRM records, and how many of those domains and people the blocklist already holds from any source (alreadyBlocked). It shows up to 10 accounts and up to 10 CRM records as samples, and counts in skipped what it leaves out.
Errors:
400 validation_failed: no criterion is sent, or a criterion is invalid. Each entry inerror.detailsnames the field and a code:out_of_rangefor an unknown or archived stage, an unknown account stage,neworresearching, an unknown account type orprospect, a list over its limit, areleaseAfterDaysoutside 1 to 3650, or an unknown or too large CRM list;not_enabledwhen CRM criteria are not turned on for the workspace;invalid_statewhen no CRM is connected;unsupportedwhen Kenso cannot read lists or lifecycle stages from the connected CRM, or the list is not a contact or company list.429 rate_limited: the CRM rate-limited Kenso. Retry after the number of seconds in theRetry-Afterheader.503 service_unavailable: Kenso could not reach the CRM.
Requires Accounts view.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
stages | query | string | optional | Comma-separated stage keys from GET /v1/opportunity-stages, up to 20. The preview matches accounts with a live opportunity in one of these stages. |
accountTypes | query | string | optional | Comma-separated account types to match: client, lost, churned, partner, competitor, investor or do_not_contact. A rule cannot match prospect. Kept for older callers: use accountStages. |
accountStages | query | string | optional | Comma-separated account stages to match, up to 16: warming, engaged, meeting_booked, in_deal, onboarding, client, churned, nurture, paused, lost, network, not_a_fit, competitor or do_not_contact. A rule cannot match new or researching. |
releaseAfterDays | query | integer (int32) | optional | A release window to preview, in days from 1 to 3650. With it, an account matched by stage counts only while one of its deals in those stages closed fewer days ago than this or has no close date. |
crmListId | query | string | optional | The id of a contact or company list in the workspace's connected CRM, from GET /v1/crm-connections/{connectionId}/lists. Kenso reads the list live and does not store it. |
crmLifecycles | query | string | optional | Comma-separated CRM lifecycle stages to match, up to 5: lead, prospect, opportunity, customer or churned. |
curl -X GET "https://api.ken.so/v1/blocklist-rules/preview" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a BlocklistRulePreview.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Contacts and companies:ContactsContact importsContact exportsTagsBlocklistContact fieldsCompaniesCompany dataContact behaviorAll resources