> 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: List 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.

One endpoint of [Blocklist rules](/docs/api/blocklist-rules.md). Authentication, workspaces and errors: [/docs.md](/docs.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
  }
}
```

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