> 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: Preview a blocklist rule

> **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.

One endpoint of [Blocklist rules](/docs/api/blocklist-rules.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## 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.

### 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. |
