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

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

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