Skip to Content

Lists

ToolWhat it does
list_add_itemsSave 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_createCreate an empty saved list of people or companies.
list_deleteDelete one accessible list after reviewing its feed impact.
list_getHydrate one accessible saved list using owner filters and pagination.
list_listList saved lists with owner scope, type, name search, sorting and pagination.
list_remove_itemsRemove selected or matching records from one accessible list.
list_updateRename 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-add-items
MCP toollist_add_items on https://mcp.prospeo.io
EffectChanges data.
CreditsCan charge credits. At most 1 credits per item. The response’s charge field reports what was charged.
PermissionCreate lists (lists.create)
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns 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.

ParameterTypeRequiredDescription
list_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
typestring (enum)YesOne of: PERSON, COMPANY.
sourcestring (enum)YesOne of: FROM_LIST, FROM_SEARCH, FROM_EXTENSION_WEBSITE, FROM_EXTENSION_LINKEDIN.
operation”LIST_ADD”NoDefault "LIST_ADD".
auto_enrich”false”NoDefault false.
from_list_oidstringNoPattern ^[0-9a-fA-F]{24}$.
filter_config_tokenstringNo
select_typestringNoPattern ^(20K|CUSTOM_[0-9]+)$.
person_oidsarray of stringNoUp to 2500 items.
company_oidsarray of stringNoUp to 2500 items.
manually_excluded_person_oidsarray of stringNoUp to 2500 items.
manually_excluded_company_oidsarray of stringNoUp to 2500 items.
max_person_per_companyintegerNoFrom 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-create
MCP toollist_create on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate lists (lists.create)
ConfirmationNot needed.
PaginationReturns 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.

ParameterTypeRequiredDescription
namestringYesLength 1 to 100.
typestring (enum)YesOne 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-delete
MCP toollist_delete on https://mcp.prospeo.io
EffectDeletes or removes data.
CreditsFree, uses no credits.
PermissionDelete team lists (lists.team.delete)
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns 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.

ParameterTypeRequiredDescription
list_oidstringYesMongoDB 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-get
MCP toollist_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-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.

ParameterTypeRequiredDescription
list_oidstringNoThe 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}$.
typestring (enum)NoOptional and not needed: the list’s own type decides what comes back. One of: PERSON, COMPANY.
filtersobjectNo
all_saved_typestringNoPERSON or COMPANY to read every saved person or saved company instead of one list. Leave empty when list_oid is set.
pageintegerNoPage number, starting at 1. Default 1.
sort_bystringNo
sort_directionstringNo
score_columnbooleanNo

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-list
MCP toollist_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-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.

ParameterTypeRequiredDescription
pageintegerNoFrom 1 to any. Default 1.
user_oidstringNoPattern ^[0-9a-fA-F]{24}$.
owner_scopestring (enum)NoOne of: ALL, MINE, TEAM.
typestring (enum)NoOne of: PERSON, COMPANY.
searchstringNo
sort_bystring (enum)NoOne of: name, total_records, created_by, created_at, updated_at.
sort_directionstring (enum)NoOne 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-remove-items
MCP toollist_remove_items on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionModify team lists (lists.team.modify)
ConfirmationNot needed.
PaginationReturns 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.

ParameterTypeRequiredDescription
list_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
person_oidsarray of stringNo
company_oidsarray of stringNo
select_typestringNo
filter_config_tokenstringNo
manually_excluded_person_oidsarray of stringNo
manually_excluded_company_oidsarray of stringNo

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/list-update
MCP toollist_update on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionModify team lists (lists.team.modify)
ConfirmationNot needed.
PaginationReturns 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.

ParameterTypeRequiredDescription
list_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
namestringYesLength 1 to 100.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

Last updated on