Lists
| Tool | What it does |
|---|---|
list_add_items | Save selected people or companies to an existing accessible list with normal save/reveal pricing. The maximum estimate covers the frozen base save. List Auto-Enrich is suppressed without changing its setting. Ordinary added-to-list workflows still run with their existing authorization and billing; their actions are outside the base save estimate. |
list_create | Create an empty saved list of people or companies. |
list_delete | Delete one accessible list after reviewing its feed impact. |
list_get | Hydrate one accessible saved list using owner filters and pagination. |
list_list | List saved lists with owner scope, type, name search, sorting and pagination. |
list_remove_items | Remove selected or matching records from one accessible list. |
list_update | Rename one existing saved list. |
list_add_items
Save selected people or companies to an existing accessible list with normal save/reveal pricing. The maximum estimate covers the frozen base save. List Auto-Enrich is suppressed without changing its setting. Ordinary added-to-list workflows still run with their existing authorization and billing; their actions are outside the base save estimate.
Save selected people or companies into a named list. For persons this reveals work emails on the newly added rows and charges 1 credit per new email found; if the destination list has auto-enrich turned on (a separate list setting, not an argument of this call), adding rows also unconditionally kicks off that list’s configured enrichment columns, which bill further credits with no cap this call can enforce.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-add-items |
| MCP tool | list_add_items on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Can charge credits. At most 1 credits per item. The response’s charge field reports what was charged. |
| Permission | Create lists (lists.create) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
list_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
type | string (enum) | Yes | One of: PERSON, COMPANY. |
source | string (enum) | Yes | One of: FROM_LIST, FROM_SEARCH, FROM_EXTENSION_WEBSITE, FROM_EXTENSION_LINKEDIN. |
operation | ”LIST_ADD” | No | Default "LIST_ADD". |
auto_enrich | ”false” | No | Default false. |
from_list_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
filter_config_token | string | No | |
select_type | string | No | Pattern ^(20K|CUSTOM_[0-9]+)$. |
person_oids | array of string | No | Up to 2500 items. |
company_oids | array of string | No | Up to 2500 items. |
manually_excluded_person_oids | array of string | No | Up to 2500 items. |
manually_excluded_company_oids | array of string | No | Up to 2500 items. |
max_person_per_company | integer | No | From 1 to any. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_create
Create an empty saved list of people or companies.
Create an empty people or company list with a given name.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-create |
| MCP tool | list_create on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create lists (lists.create) |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Length 1 to 100. |
type | string (enum) | Yes | One of: PERSON, COMPANY. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_delete
Delete one accessible list after reviewing its feed impact.
Delete a list the user names explicitly, by list id. Never suggest deletion proactively — always require the user to name the specific list.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-delete |
| MCP tool | list_delete on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | Delete team lists (lists.team.delete) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
list_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_get
Hydrate one accessible saved list using owner filters and pagination.
View a single list’s metadata (name, type, total records, creator, auto-enrich state, pending-enrich count, feeding sequences) and its paginated rows. Viewing your own lists or the virtual All-Saved views needs no special permission; viewing a list owned by a different team member requires the LISTS_TEAM_VIEW_STATS permission. Use to inspect a specific list before adding/removing records or before deciding whether to run pending enrichment.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-get |
| MCP tool | list_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-based: page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
list_oid | string | No | The list’s id: 24 hex characters, taken from the team’s lists, which can be searched by name. This tool cannot look a list up by name. Leave empty only when all_saved_type is set. Pattern ^[0-9a-fA-F]{24}$. |
type | string (enum) | No | Optional and not needed: the list’s own type decides what comes back. One of: PERSON, COMPANY. |
filters | object | No | |
all_saved_type | string | No | PERSON or COMPANY to read every saved person or saved company instead of one list. Leave empty when list_oid is set. |
page | integer | No | Page number, starting at 1. Default 1. |
sort_by | string | No | |
sort_direction | string | No | |
score_column | boolean | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_list
List saved lists with owner scope, type, name search, sorting and pagination.
List the team’s saved lists (people or company lists) with names, types, sizes, and creators, with search/pagination. Use to help the user pick an existing list, or to check whether a suitable list already exists before creating one.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-list |
| MCP tool | list_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-based: page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
user_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
owner_scope | string (enum) | No | One of: ALL, MINE, TEAM. |
type | string (enum) | No | One of: PERSON, COMPANY. |
search | string | No | |
sort_by | string (enum) | No | One of: name, total_records, created_by, created_at, updated_at. |
sort_direction | string (enum) | No | One of: asc, desc. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_remove_items
Remove selected or matching records from one accessible list.
Remove specific people or companies from a list. The underlying saved contacts/companies are not deleted — only their membership in this one list is removed.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-remove-items |
| MCP tool | list_remove_items on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Modify team lists (lists.team.modify) |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
list_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
person_oids | array of string | No | |
company_oids | array of string | No | |
select_type | string | No | |
filter_config_token | string | No | |
manually_excluded_person_oids | array of string | No | |
manually_excluded_company_oids | array of string | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
list_update
Rename one existing saved list.
Rename an existing list. Does not change list contents, type, or auto-enrich settings.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/list-update |
| MCP tool | list_update on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Modify team lists (lists.team.modify) |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
list_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
name | string | Yes | Length 1 to 100. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.