# Contact lists actions

> Contact lists: 5 Xholic actions (1 read, 4 change), each with its MCP tool, REST endpoint and CLI command.

Source: https://docs.xholic.ai/actions/contact-lists/

5 actions. Every field marked *Required* must be sent; `account`, `dryRun`, `idempotencyKey`, `confirmCredits` and `quoteId` are the [control fields](/api/responses/#control-fields) every surface adds.

## Contact lists

`contact_lists.list` · read

The account's contact lists with member counts, including which one is the close-accounts list. Use a list's id with the other contact tools.

- **MCP tool:** `get_contact_lists`. Loaded by default in MCP clients.
- **REST:** `GET /v1/contact-lists/list`
- **CLI:** `xholic contact-lists list`
- **Scope:** `read`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Create a contact list

`contact_lists.create` · write

Create a contact list. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `contact_lists_create`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contact-lists/create`
- **CLI:** `xholic contact-lists create`
- **Scope:** `write`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string ≤ 80 chars | Yes |  |
| `description` | string ≤ 1500 chars or null | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Rename a contact list

`contact_lists.rename` · write

Rename a contact list. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `contact_lists_rename`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contact-lists/rename`
- **CLI:** `xholic contact-lists rename`
- **Scope:** `write`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Contact list id. |
| `name` | string ≤ 80 chars | Yes |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Delete a contact list

`contact_lists.delete` · write

Delete a contact list and its memberships. The people stay in other lists. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `contact_lists_delete`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contact-lists/delete`
- **CLI:** `xholic contact-lists delete`
- **Scope:** `write`. Destructive: it can't be taken back
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Contact list id. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Use a list as close accounts

`contact_lists.set_close_accounts` · write

Turn a list into the account's close-accounts list (people whose posts Home and Engage surface first), or turn that off. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `contact_lists_set_close_accounts`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contact-lists/set-close-accounts`
- **CLI:** `xholic contact-lists set-close-accounts`
- **Scope:** `write`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Contact list id. |
| `enabled` | boolean | Yes |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |