# Contacts actions

> Contacts: 15 Xholic actions (6 read, 9 change), each with its MCP tool, REST endpoint and CLI command.

Source: https://docs.xholic.ai/actions/contacts/

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

## Contacts

`contacts.list` · read

Contacts and lists: search, filter by score or intent.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listId` | string (uuid) | No |  |
| `search` | string ≤ 80 chars | No |  |
| `minimumScore` | integer 1–3 | No |  |
| `intent` | "HOT" \\| "WARM" \\| "COLD" | No |  |
| `limit` | integer 1–30 | No | Default: `15`. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Export contacts

`contacts.export` · read

Contacts in a list as data.

- **MCP tool:** `contacts_export`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/contacts/export`
- **CLI:** `xholic contacts export`
- **Scope:** `read`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

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

## Add someone to a contact list

`contacts.add_to_list` · write

Add an X account to a contact list by handle. Looks the profile up on X when Xholic doesn't have it yet. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `add_to_contact_list`. Loaded by default in MCP clients.
- **REST:** `POST /v1/contacts/add-to-list`
- **CLI:** `xholic contacts add-to-list`
- **Scope:** `write`
- **Plan:** Pro plan or higher
- **Cost:** Live X lookup: no credits, counts toward the plan's X data limits.
- **Rate limit bucket:** `live_x`
- **Undo:** from the activity log, which runs `contacts.remove` (not offered when `contact.alreadyAdded` is true: the call changed nothing)

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listId` | string (uuid) | Yes | Contact list id from get_contact_lists. |
| `handle` | string ≤ 120 chars | Yes | X handle like @name, or a link to their profile. |
| `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. |

## Add a known person to a list

`contacts.add` · write

Add a person Xholic already has (by X user id, e.g. from a lead or contacts.search_profiles) to a contact list. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listId` | string (uuid) | Yes | Contact list id. |
| `creatorId` | string ≤ 64 chars | Yes | The person's numeric X user 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. |

## Update a contact

`contacts.update` · write

Change a contact's status (NEW, SAVED, CONTACTED, DISMISSED) or its note. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Contact (list membership) id from get_contacts. |
| `status` | "NEW" \\| "SAVED" \\| "CONTACTED" \\| "DISMISSED" | No |  |
| `note` | string ≤ 4000 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. |

## Remove from a list

`contacts.remove` · write

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

- **MCP tool:** `contacts_remove`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contacts/remove`
- **CLI:** `xholic contacts remove`
- **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 membership) id from get_contacts. |
| `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. |

## Save a note on a person

`contacts.save_note` · write

Add a note about a person, or edit one by passing its id. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `creatorId` | string | Yes | The person's numeric X user id. |
| `id` | string (uuid) | No | An existing note's id, to edit it. |
| `note` | string ≤ 4000 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 note

`contacts.delete_note` · write

Delete a note about a person. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `contacts_delete_note`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/contacts/delete-note`
- **CLI:** `xholic contacts delete-note`
- **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 | Note 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. |

## Find people to add

`contacts.search_profiles` · read

Search X accounts by name or handle to add to a contact list. Stored profiles first, then a capped live X lookup.

- **MCP tool:** `contacts_search_profiles`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/contacts/search-profiles`
- **CLI:** `xholic contacts search-profiles`
- **Scope:** `read`
- **Plan:** Pro plan or higher
- **Cost:** Live X lookup: no credits, counts toward the plan's X data limits.
- **Rate limit bucket:** `live_x`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string ≤ 120 chars | Yes |  |
| `listId` | string (uuid) | Yes | The contact list you'll add them to. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Contact profile

`contacts.profile` · read

Everything Xholic knows about one person: profile, lists, notes, engagement with the account, DMs and, with leadId, why they were found as a lead.

- **MCP tool:** `contacts_profile`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/contacts/profile`
- **CLI:** `xholic contacts profile`
- **Scope:** `read`
- **Plan:** Pro plan or higher
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string ≤ 64 chars | Yes | The person's numeric X user id. |
| `leadId` | string (uuid) | No | A lead id, to include that lead's details. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Follower import status

`contacts.follower_import` · read

Whether the account's own followers have been imported into Contacts, and the latest import's progress.

- **MCP tool:** `contacts_follower_import`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/contacts/follower-import`
- **CLI:** `xholic contacts follower-import`
- **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. |

## Import my followers

`contacts.import_followers` · write

Queue an import of the account's own X followers into Contacts. Runs in the background within the plan's contact limits. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**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. |
| `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. |

## Contact imports

`contacts.imports` · read

X list imports into contact lists, with their progress.

- **MCP tool:** `contacts_imports`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/contacts/imports`
- **CLI:** `xholic contacts imports`
- **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. |

## Import an X list

`contacts.import_x_list` · write

Queue an import of a public X list's members into a contact list. Runs in the background within the plan's contact limits. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `listId` | string (uuid) | Yes | Contact list to import into. |
| `url` | string ≤ 300 chars | Yes | Link to a public X list. |
| `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. |

## Stop a contact import

`contacts.cancel_import` · write

Stop a running X list import. People already imported stay.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Import id from contacts.imports. |
| `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. |