Contacts actions
15 actions. Every field marked Required must be sent; account, dryRun, idempotencyKey, confirmCredits and quoteId are the control fields every surface adds.
Contacts
Section titled “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” |
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
Section titled “Export contacts”contacts.export · read
Contacts in a list as data.
- MCP tool:
contacts_export. Catalog: reach it withfind_actionsandrun_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
Section titled “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
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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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” \ |
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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “Contact imports”contacts.imports · read
X list imports into contact lists, with their progress.
- MCP tool:
contacts_imports. Catalog: reach it withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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
Section titled “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 withfind_actionsandrun_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. |