---
title: "Call the manageLeadList MCP tool"
method: POST
path: "/api/v1/actions/manageLeadList"
tags: ["Actions"]
---

# Call the manageLeadList MCP tool

`POST /api/v1/actions/manageLeadList`

## Request

- Base URL: `https://app.reachium.io`
- URL: `https://app.reachium.io/api/v1/actions/manageLeadList`
- Auth: HTTP bearer

Manage lead lists post-hoc, in four actions. (1) split_by_open_profile: create a NEW lead list containing only the OPEN PROFILE leads from an existing list (source_list_id + open_list_name), the audience for a free cold-InMail campaign (createDraftCampaign with the inmail_open_profiles preset). Open-profile status is learned only by visiting or enriching a profile - a campaign's visit_profile step, or the InMail-activation list_enrichment job - NOT by scraping or search (LinkedIn stopped exposing it there). Leads that have not yet been visited or enriched, including freshly scraped leads and ones exported from the Reachium database (addSearchToLeadList), start with unknown status and will not match until then. keep defaults to 'open' (only the Open list is created); keep:'both' also creates a second list (other_list_name) with the Remaining, not-confirmed-open leads. (2) merge: combine 2 to 25 existing lists (source_list_ids) into ONE brand-new list (new_list_name), deduped by lead. (3) rename: rename ONE existing list in place (list_id + new_name) - name only, matching the app's own rename dialog exactly, so it does not touch the list's description field. No credits are charged for any of these three actions. split_by_open_profile and merge are additive: their source lists are only ever read, never modified. rename is the one action here that changes an existing list, and it only ever changes that list's name; the LEADS on a renamed list are never touched. (4) enrich_emails: preview, then confirmation-gate, up to 500 blank-email LinkedIn leads from one list through a connected Prospeo or Apollo account. It can spend vendor credits, never Reachium credits; the preview shows eligible/today and the provider balance when available. Run it again tomorrow for any remainder.

Called through the Actions bridge: the response is that tool's own result, wrapped as `{ data: <tool result> }` under HTTP 200. Billing, daily-cap, and confirm-step outcomes are embedded INSIDE `data`, never remapped to an HTTP status (see the templated `/api/v1/actions/{toolName}` operation above for the full protocol, and `x-mcp-actions` for this tool's machine-readable scope/cap/confirm_behavior fields). Authentication, request-shape, and optional idempotency-protocol failures still use their documented non-200 statuses.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `action` 'split_by_open_profile' | 'merge' | 'rename' | 'enrich_emails', required
  - `source_list_id` string, uuid: split_by_open_profile: the list to filter (from getLeadLists). Not modified.
  - `keep` 'open' | 'both': split_by_open_profile: 'open' (default) creates only the Open list; 'both' also creates a Remaining list.
  - `open_list_name` string: split_by_open_profile: name for the new open-profiles-only list.
  - `other_list_name` string: split_by_open_profile: name for the Remaining list. Required when keep is 'both'.
  - `source_list_ids` string[]: merge: 2 to 25 list ids to combine (from getLeadLists).
  - `new_list_name` string: merge: name for the combined list.
  - `list_id` string, uuid: rename/enrich_emails: the target list (from getLeadLists).
  - `new_name` string: rename: the new name for the list.
  - `integration_id` string, uuid: enrich_emails: an active Prospeo or Apollo connection id from getConnectors.
  - `confirm_token` string: enrich_emails only: return the exact token from the preview after the user approves vendor-credit spend.

## Response `200`

The result of calling this tool.

- object
  - `data` unknown, required
  - `error` unknown, required

## Other responses

- `400`: The request body was not a JSON object (code invalid_request), or Idempotency-Key is malformed (code invalid_idempotency_key).
- `401`: Missing or invalid API key. Send `Authorization: Bearer rmcp_...` (code unauthorized).
- `403`: This tool is out of the key’s granted scope (code insufficient_scope).
- `409`: This Idempotency-Key has an unresolved in-flight or ambiguous result (code request_in_flight). Reconcile before using a new key.
- `422`: This Idempotency-Key was already used with a different request body (code idempotency_key_reuse).
- `429`: Rate limited: shared `mcp:ip:{ip}` (600/60s) or `mcp:key:{keyId}` (120/60s) bucket, the SAME buckets the MCP endpoint uses (code rate_limited).
- `500`: Unhandled server error (code internal_error).

---

[API](https://skmtc.dev/reachium/apis/reachium-api.md) · [All operations](https://skmtc.dev/reachium/apis/reachium-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reachium/apis/reachium-api/revisions/11682826692b?raw)