> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/blocklist-rules/openapi.json](/docs/api/blocklist-rules/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Blocklist rules

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Rules that block contacts by pattern.

Contacts and companies. 5 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/blocklist-rules/openapi.json](/docs/api/blocklist-rules/openapi.json).

- `GET /v1/blocklist-rules` - List blocklist rules (`blocklist-rules.list`): [/docs/api/blocklist-rules/list.md](/docs/api/blocklist-rules/list.md)
- `POST /v1/blocklist-rules` - Create a blocklist rule (`blocklist-rules.create`): [/docs/api/blocklist-rules/create.md](/docs/api/blocklist-rules/create.md)
- `PATCH /v1/blocklist-rules/{ruleId}` - Update a blocklist rule (`blocklist-rules.update`): [/docs/api/blocklist-rules/update.md](/docs/api/blocklist-rules/update.md)
- `DELETE /v1/blocklist-rules/{ruleId}` - Delete a blocklist rule (`blocklist-rules.delete`): [/docs/api/blocklist-rules/delete.md](/docs/api/blocklist-rules/delete.md)
- `GET /v1/blocklist-rules/preview` - Preview a blocklist rule (`blocklist-rules.preview`): [/docs/api/blocklist-rules/preview.md](/docs/api/blocklist-rules/preview.md)

## List blocklist rules

`GET /v1/blocklist-rules` - operationId `blocklist-rules.list`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

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.

Needs the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-rules/GET/v1/blocklist-rules)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | 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 | no | The `nextCursor` of the previous page. Omit it for the first page. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a list of `BlocklistRule`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The rule's id. |
| `name` | string | The rule's name, from 1 to 100 characters. |
| `stages` | array of string | Opportunity stage keys from `GET /v1/opportunity-stages`. The rule matches accounts with an opportunity in one of them. Empty when the rule does not match by stage. |
| `accountTypes` | array of string | Account types the rule matches: any of `client`, `lost`, `churned`, `partner`, `competitor`, `investor` and `do_not_contact`. Empty when the rule does not match by type. Kept for older callers: account stages replace account types. |
| `accountStages` | array of string | Account stages the rule matches: any of `warming`, `engaged`, `meeting_booked`, `in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`, `network`, `not_a_fit`, `competitor` and `do_not_contact`. Empty when the rule does not match by account stage. |
| `reason` | string | The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. |
| `enabled` | boolean | True when the rule adds entries to the blocklist. A disabled rule still shows its `matches`. |
| `position` | integer (int32) | The rule's place in the list, starting at 0. When several enabled rules match a domain or email, the first one gives the entry its reason. |
| `releaseAfterDays` | integer (int32) | From 1 to 3650 days. An account matched by stage comes off the blocklist that many days after its deal in those stages closed. A deal with no close date, a match by account type or account stage and a CRM match never release. Absent when the rule never releases. |
| `crmConnectionId` | integer (int64) | The id of the CRM connection the rule's CRM criteria use. Absent when the rule has no CRM criterion. |
| `crmLifecycles` | array of string | CRM lifecycle stages the rule matches: any of `lead`, `prospect`, `opportunity`, `customer` and `churned`. A CRM company in one of them blocks its domain. A CRM contact blocks its company domain, or its email when it has only a free email domain. |
| `crmList` | BlocklistRuleCrmList | The CRM list the rule matches. A contact list blocks its people's emails, and a company list blocks its companies' domains. Absent when the rule has no list. |
| `matches` | BlocklistRuleMatches | What the rule matches now, counted whether the rule is enabled or not. |
| `createdAt` | string (date-time) | When the rule was created, in UTC. |
| `updatedAt` | string (date-time) | When the rule last changed, in UTC. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "name": "string",
      "stages": [
        "string"
      ],
      "accountTypes": [
        "string"
      ],
      "accountStages": [
        "string"
      ],
      "reason": "string",
      "enabled": true,
      "position": 1,
      "releaseAfterDays": 1,
      "crmConnectionId": 812,
      "crmLifecycles": [
        "string"
      ],
      "crmList": {
        "externalId": "string",
        "name": "string",
        "objectType": "contact",
        "members": 1,
        "readAt": "2026-09-23T15:02:11Z"
      },
      "matches": {
        "accounts": 1,
        "domains": 1,
        "people": 1,
        "crmRecords": 1
      },
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Create a blocklist rule

`POST /v1/blocklist-rules` - operationId `blocklist-rules.create`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

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 from `GET /v1/opportunity-stages`, none archived. The rule
matches accounts with an opportunity in one of these stages.
- `accountStages`: up to 16 account stages, any of `warming`, `engaged`, `meeting_booked`,
`in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`,
`network`, `not_a_fit`, `competitor` and `do_not_contact`. The rule matches accounts in one
of these stages. `new` and `researching` are not allowed, because every new account starts there.
- `accountTypes`: any of `client`, `lost`, `churned`, `partner`, `competitor`,
`investor` and `do_not_contact`. `prospect` is not allowed, because every new account is a
prospect. Kept for older callers: use `accountStages`.
- `crmLifecycles`: up to 5 CRM lifecycle stages, any of `lead`, `prospect`, `opportunity`,
`customer` and `churned`, 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 from `GET /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.details` names
each field, with the same codes as `GET /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 the
`Retry-After` header.
- `503 service_unavailable`: Kenso could not reach the CRM.

Requires the `workspace_settings` permission.

Needs the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-rules/POST/v1/blocklist-rules)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The rule's name, from 1 to 100 characters. Required. |
| `stages` | array of string | no | 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 | no | 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 | no | 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 | yes | The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. Required. |
| `enabled` | boolean | no | Whether the rule adds entries to the blocklist. `true` by default. |
| `releaseAfterDays` | integer (int32) | no | 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 | no | 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 | no | 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. |

### Response 201

`data` is a `BlocklistRule`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The rule's id. |
| `name` | string | The rule's name, from 1 to 100 characters. |
| `stages` | array of string | Opportunity stage keys from `GET /v1/opportunity-stages`. The rule matches accounts with an opportunity in one of them. Empty when the rule does not match by stage. |
| `accountTypes` | array of string | Account types the rule matches: any of `client`, `lost`, `churned`, `partner`, `competitor`, `investor` and `do_not_contact`. Empty when the rule does not match by type. Kept for older callers: account stages replace account types. |
| `accountStages` | array of string | Account stages the rule matches: any of `warming`, `engaged`, `meeting_booked`, `in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`, `network`, `not_a_fit`, `competitor` and `do_not_contact`. Empty when the rule does not match by account stage. |
| `reason` | string | The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. |
| `enabled` | boolean | True when the rule adds entries to the blocklist. A disabled rule still shows its `matches`. |
| `position` | integer (int32) | The rule's place in the list, starting at 0. When several enabled rules match a domain or email, the first one gives the entry its reason. |
| `releaseAfterDays` | integer (int32) | From 1 to 3650 days. An account matched by stage comes off the blocklist that many days after its deal in those stages closed. A deal with no close date, a match by account type or account stage and a CRM match never release. Absent when the rule never releases. |
| `crmConnectionId` | integer (int64) | The id of the CRM connection the rule's CRM criteria use. Absent when the rule has no CRM criterion. |
| `crmLifecycles` | array of string | CRM lifecycle stages the rule matches: any of `lead`, `prospect`, `opportunity`, `customer` and `churned`. A CRM company in one of them blocks its domain. A CRM contact blocks its company domain, or its email when it has only a free email domain. |
| `crmList` | BlocklistRuleCrmList | The CRM list the rule matches. A contact list blocks its people's emails, and a company list blocks its companies' domains. Absent when the rule has no list. |
| `matches` | BlocklistRuleMatches | What the rule matches now, counted whether the rule is enabled or not. |
| `createdAt` | string (date-time) | When the rule was created, in UTC. |
| `updatedAt` | string (date-time) | When the rule last changed, in UTC. |

### Request

```bash
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"
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "name": "string",
    "stages": [
      "string"
    ],
    "accountTypes": [
      "string"
    ],
    "accountStages": [
      "string"
    ],
    "reason": "string",
    "enabled": true,
    "position": 1,
    "releaseAfterDays": 1,
    "crmConnectionId": 812,
    "crmLifecycles": [
      "string"
    ],
    "crmList": {
      "externalId": "string",
      "name": "string",
      "objectType": "contact",
      "members": 1,
      "readAt": "2026-09-23T15:02:11Z"
    },
    "matches": {
      "accounts": 1,
      "domains": 1,
      "people": 1,
      "crmRecords": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Update a blocklist rule

`PATCH /v1/blocklist-rules/{ruleId}` - operationId `blocklist-rules.update`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

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 than `releaseAfterDays` and
`crmListId` is `null`, `position` is negative, or the change leaves the rule with no criterion.
`error.details` names 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 the
`Retry-After` header.
- `503 service_unavailable`: Kenso could not reach the CRM.

Requires the `workspace_settings` permission.

Needs the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-rules/PATCH/v1/blocklist-rules/%7BruleId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ruleId` | path | integer (int64) | yes | The rule's id, as `GET /v1/blocklist-rules` returns it. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The rule's name, from 1 to 100 characters. |
| `stages` | array of string | no | 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 | no | Account types to match, with the values of create. `[]` clears them, as long as the rule keeps another criterion. |
| `accountStages` | array of string | no | Account stages to match, with the values of create. `[]` clears them, as long as the rule keeps another criterion. |
| `reason` | string | no | The reason on every blocklist entry the rule adds, from 1 to 200 characters. |
| `enabled` | boolean | no | Whether the rule adds entries to the blocklist. |
| `position` | integer (int32) | no | The rule's new place, starting at 0. A position past the last rule moves it last. |
| `releaseAfterDays` | integer (int32) | no | 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 | no | A contact or company list of the connected CRM. `null` drops the list. |
| `crmLifecycles` | array of string | no | CRM lifecycle stages to match, with the values of create. `[]` clears them, as long as the rule keeps another criterion. |

### Response 200

`data` is a `BlocklistRule`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The rule's id. |
| `name` | string | The rule's name, from 1 to 100 characters. |
| `stages` | array of string | Opportunity stage keys from `GET /v1/opportunity-stages`. The rule matches accounts with an opportunity in one of them. Empty when the rule does not match by stage. |
| `accountTypes` | array of string | Account types the rule matches: any of `client`, `lost`, `churned`, `partner`, `competitor`, `investor` and `do_not_contact`. Empty when the rule does not match by type. Kept for older callers: account stages replace account types. |
| `accountStages` | array of string | Account stages the rule matches: any of `warming`, `engaged`, `meeting_booked`, `in_deal`, `onboarding`, `client`, `churned`, `nurture`, `paused`, `lost`, `network`, `not_a_fit`, `competitor` and `do_not_contact`. Empty when the rule does not match by account stage. |
| `reason` | string | The reason Kenso puts on every blocklist entry the rule adds, from 1 to 200 characters. |
| `enabled` | boolean | True when the rule adds entries to the blocklist. A disabled rule still shows its `matches`. |
| `position` | integer (int32) | The rule's place in the list, starting at 0. When several enabled rules match a domain or email, the first one gives the entry its reason. |
| `releaseAfterDays` | integer (int32) | From 1 to 3650 days. An account matched by stage comes off the blocklist that many days after its deal in those stages closed. A deal with no close date, a match by account type or account stage and a CRM match never release. Absent when the rule never releases. |
| `crmConnectionId` | integer (int64) | The id of the CRM connection the rule's CRM criteria use. Absent when the rule has no CRM criterion. |
| `crmLifecycles` | array of string | CRM lifecycle stages the rule matches: any of `lead`, `prospect`, `opportunity`, `customer` and `churned`. A CRM company in one of them blocks its domain. A CRM contact blocks its company domain, or its email when it has only a free email domain. |
| `crmList` | BlocklistRuleCrmList | The CRM list the rule matches. A contact list blocks its people's emails, and a company list blocks its companies' domains. Absent when the rule has no list. |
| `matches` | BlocklistRuleMatches | What the rule matches now, counted whether the rule is enabled or not. |
| `createdAt` | string (date-time) | When the rule was created, in UTC. |
| `updatedAt` | string (date-time) | When the rule last changed, in UTC. |

### Request

```bash
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"
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 812,
    "name": "string",
    "stages": [
      "string"
    ],
    "accountTypes": [
      "string"
    ],
    "accountStages": [
      "string"
    ],
    "reason": "string",
    "enabled": true,
    "position": 1,
    "releaseAfterDays": 1,
    "crmConnectionId": 812,
    "crmLifecycles": [
      "string"
    ],
    "crmList": {
      "externalId": "string",
      "name": "string",
      "objectType": "contact",
      "members": 1,
      "readAt": "2026-09-23T15:02:11Z"
    },
    "matches": {
      "accounts": 1,
      "domains": 1,
      "people": 1,
      "crmRecords": 1
    },
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-09-23T15:02:11Z"
  }
}
```

## Delete a blocklist rule

`DELETE /v1/blocklist-rules/{ruleId}` - operationId `blocklist-rules.delete`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

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.

Needs the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-rules/DELETE/v1/blocklist-rules/%7BruleId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ruleId` | path | integer (int64) | yes | The rule's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 204

### Request

```bash
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"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Preview a blocklist rule

`GET /v1/blocklist-rules/preview` - operationId `blocklist-rules.preview`

| Permission | Rate limit |
| --- | --- |
| Accounts view | 12,000 requests a minute per API key |

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 in
`error.details` names the field and a code: `out_of_range` for an unknown or archived stage, an unknown
account stage, `new` or `researching`, an unknown account type or `prospect`, a list over its limit, a `releaseAfterDays` outside 1 to 3650, or an
unknown or too large CRM list; `not_enabled` when CRM criteria are not turned on for the workspace;
`invalid_state` when no CRM is connected; `unsupported` when 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 the
`Retry-After` header.
- `503 service_unavailable`: Kenso could not reach the CRM.

Requires Accounts view.

Needs the `blocklist_rules` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/blocklist-rules/GET/v1/blocklist-rules/preview)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `stages` | query | string | no | 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 | no | 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 | no | 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) | no | 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 | no | 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 | no | Comma-separated CRM lifecycle stages to match, up to 5: `lead`, `prospect`, `opportunity`, `customer` or `churned`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | 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. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | 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`. |

### Response 200

`data` is a `BlocklistRulePreview`.

| Field | Type | Description |
| --- | --- | --- |
| `accounts` | integer (int32) | Accounts with an opportunity in one of the stages (inside the release window, if you sent one), with one of the account types or in one of the account stages, each counted once. |
| `domains` | integer (int32) | Distinct domains the rule would block: those of the matched accounts and of the matched CRM companies and contacts. Free email domains are left out. |
| `people` | integer (int32) | Distinct emails the rule would block: the people on a contact list, and CRM contacts that have only a free email domain. |
| `crmRecords` | integer (int32) | CRM records matched: those in the lifecycle stages, plus the list's members as read now. |
| `alreadyBlocked` | integer (int32) | How many of the `domains` and `people` the blocklist already holds, from any source. |
| `sample` | array of BlocklistRuleSample | Up to 10 matched accounts, each with one of its domains, in account id order. |
| `crmSample` | array of BlocklistRuleCrmSample | Up to 10 matched CRM records, each with the email or domain it would block. List members come first. |
| `skipped` | BlocklistRuleSkipped | What the rule matched but would not block, counted by reason. |

### Request

```bash
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"
```

### Example response

```json
{
  "success": true,
  "data": {
    "accounts": 1,
    "domains": 1,
    "people": 1,
    "crmRecords": 1,
    "alreadyBlocked": 1,
    "sample": [
      {
        "accountId": 812,
        "name": "string",
        "domain": "example.com"
      }
    ],
    "crmSample": [
      {
        "externalId": "string",
        "name": "string",
        "value": "string"
      }
    ],
    "skipped": {
      "noDomain": 1,
      "noEmail": 1,
      "freeMail": 1,
      "released": 1
    }
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### BlocklistRuleCrmList

The CRM list a blocklist rule matches.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | no | The list's id in the CRM, as `GET /v1/crm-connections/{connectionId}/lists` returns it. |
| `name` | string | no | The list's name in the CRM when the rule was saved. |
| `objectType` | string | no | What the list holds: `contact` or `company`. |
| `members` | integer (int32) | no | The number of members at Kenso's last successful read. Absent before the first read. Kenso reads the list again about every 15 minutes, and someone who has left the list comes off the blocklist then. |
| `readAt` | string (date-time) | no | When Kenso last read the list, in UTC. Absent before the first read. |

### BlocklistRuleMatches

What a blocklist rule matches now.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accounts` | integer (int32) | no | Accounts with an opportunity in one of the rule's stages (inside the release window, if the rule has one), with one of its account types or in one of its account stages, each counted once. |
| `domains` | integer (int32) | no | Distinct domains the rule blocks: those of the matched accounts and of the matched CRM companies and contacts. Free email domains are left out. |
| `people` | integer (int32) | no | Distinct emails the rule blocks: the people on a contact list, and CRM contacts that have only a free email domain. |
| `crmRecords` | integer (int32) | no | CRM records the rule matches: those in its lifecycle stages, plus its list's members as last read. |

### BlocklistRuleSample

An account a previewed rule would block.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | integer (int64) | no | The account's id. |
| `name` | string | no | The account's name. |
| `domain` | string | no | One of the account's domains that the rule would block. |

### BlocklistRuleCrmSample

A CRM record a previewed rule would block.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | no | The record's id in the CRM. |
| `name` | string | no | The record's name in the CRM. Absent when it has none. |
| `value` | string | no | The email or domain the record would block. |

### BlocklistRuleSkipped

What a previewed rule matched but would not block.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `noDomain` | integer (int32) | no | Matched accounts and CRM companies that have no domain. |
| `noEmail` | integer (int32) | no | Matched CRM contacts that have neither a company domain nor a valid email. |
| `freeMail` | integer (int32) | no | Matched domains that are free or shared email providers. Kenso never blocks those as a domain. |
| `released` | integer (int32) | no | Accounts in one of the stages that the release window already let go, because every such deal closed at least `releaseAfterDays` ago. 0 without a release window. |

All resources: [/docs.md](/docs.md).
