> 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: Create 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).

## 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"
  }
}
```

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