# PATCH /lists/{id}

Part of the SendHeron REST API. Base URL: `https://api.sendheron.com/api/v1`

Rename a list, describe it, or change its rules or type.

```http
PATCH https://api.sendheron.com/api/v1/lists/{id}
Authorization: Bearer <YOUR_API_KEY>
```

**Required scopes:** `contacts:write`

**Success status:** `200`

**Rate limit:** 100/min per key, counted against the organization's WRITE ceiling (400/min).

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | yes | List UUID. |

**Body parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | New name, unique within the workspace. |
| `description` | string | no | What the list is for. Shown in the dashboard only. |
| `type` | STATIC \| DYNAMIC | no | `STATIC`: members are added and removed explicitly, and adding one fires the `LIST_ADDED` sequence trigger. `DYNAMIC`: a segment whose members are whoever matches `rules` when it is read; nothing is ever added to it, so `LIST_ADDED` never fires for it. Switching a dynamic list to static drops its rules and starts it empty; switching a static list to dynamic needs `rules` in the same request. |
| `rules` | object | no | Replaces the rules of a dynamic list. Who a dynamic list contains, evaluated every time it is read. Required when `type` is `DYNAMIC`, cleared when it is `STATIC`. A group is `{"type": "group", "logic": "AND" \| "OR", "rules": [...]}` whose rules are atomic rules `{"type": "rule", "field": ..., "operator": ..., "value": ...}` or nested groups, at most three levels deep. A bare array of atomic rules is read as an AND group. `field` is a contact column (`email`, `firstName`, `lastName`, `status`, `source`, `createdAt` or `updatedAt`), `tags`, or `properties.<key>` for a custom property; any other field is refused (400 `lists.invalidRuleField`). `operator` is one of `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_SET`, `IS_NOT_SET`, `IN` or `NOT_IN`, in that spelling (400 `lists.invalidRuleOperator` otherwise), and `logic` is `AND` or `OR` (400 `lists.invalidRuleLogic`). `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH` and `ENDS_WITH` match regardless of case; a contact column compares as its own type and a custom property as text. `IS_SET` and `IS_NOT_SET` take no value; `IN` and `NOT_IN` take a non-empty list, and every other operator one value, not a list (400 `lists.invalidRuleValue` otherwise). On `status` and `source` only `EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`, `IS_SET` and `IS_NOT_SET` are accepted (400 `lists.invalidRuleOperator`), with the values that column holds: `SUBSCRIBED`, `UNSUBSCRIBED`, `BOUNCED` or `COMPLAINED` for `status`, and `MANUAL`, `IMPORT`, `API`, `FORM` or `SYNC` for `source` (400 `lists.invalidRuleValue`). On `tags` only `IN` and `NOT_IN` (tag names) and `IS_SET` and `IS_NOT_SET` (any tag at all) are accepted. Example: `{"type": "group", "logic": "AND", "rules": [{"type": "rule", "field": "status", "operator": "EQUALS", "value": "SUBSCRIBED"}, {"type": "rule", "field": "tags", "operator": "IN", "value": ["customer"]}, {"type": "rule", "field": "properties.plan", "operator": "EQUALS", "value": "pro"}]}`. |

**Endpoint-specific errors** (beyond the shared error set):

- `400`: `lists.rulesRequiredForDynamic`: a switch to dynamic without `rules` in the same request.
- `400`: `lists.invalidRuleField`, `lists.invalidRuleOperator`, `lists.invalidRuleValue`, `lists.invalidRuleLogic`, `lists.invalidRuleFormat` or `lists.rulesTooDeeplyNested`: a rule the segment query cannot apply, refused rather than stored. `lists.invalidRuleOperator`, `lists.invalidRuleValue` and `lists.invalidRuleLogic` come with a `description` saying what is accepted.
- `409`: A list with this name already exists in the workspace.


---

Rate limits: 100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.
