Skip to Content

Deals

ToolWhat it does
deal_add_noteReplace a deal’s shared rich-text note.
deal_bulk_updateApply exactly one bounded stage, status, tag, owner or scalar update across named deals.
deal_createCreate a deal through the existing pipeline checks.
deal_deleteSoft-delete one accessible deal after approval.
deal_getGet full detail for one named deal or opportunity by its id: pipeline/stage/status, owners, amount/value and currency (plus home-currency conversion), close date, rotten/idle-day and activity signals, notes, tags, custom fields, and its linked contacts, meetings, and followers.
deal_link_contactLink an accessible saved contact to one deal.
deal_list_by_contactList the open deals linked to a saved contact.
deal_loseMark one deal lost with the owner’s required reason.
deal_move_stageMove a deal through the owner’s stage transition path.
deal_reopenReopen one closed deal into an eligible open stage.
deal_searchFind deals or opportunities matching filters: pipeline, stage, owner, status (open/won/lost), amount range, close/created/last-activity dates, rotten-only, tags, lost reason, forecast category, source, followers, created-by, exact deal custom-field values, and free text, sorted and paginated.
deal_timelineGet one deal’s activity timeline: stage changes, note edits, its own tasks, linked meetings, and every email/call against its linked contacts, newest first. Use to answer ‘what happened on this deal’, ‘when did this deal move to this stage’, ‘has anyone called or emailed about this deal or opportunity recently’.
deal_updatePatch editable fields on one accessible deal.
deal_winMark one deal won using an eligible won stage.
lost_reason_listList the team’s configured reasons a deal can be marked lost (e.g. price, timing, went with competitor), plus whether a custom freeform lost reason is allowed. Use to resolve a lost-reason name to its id before marking a deal lost, or to answer ‘why do deals get marked lost’ / ‘what lost reasons do we track’.
pipeline_listList the team’s deal pipelines (sales funnels) and each pipeline’s ordered stages — pipeline names, default flag, stage names, stage type (OPEN/WON/LOST), win probability, rot window. Use to resolve a pipeline or deal-stage name to its id before creating, updating, or moving a deal, or to answer ‘what pipelines/stages do we have for deals’.

deal_add_note

Replace a deal’s shared rich-text note.

Save/update the deal’s single shared, team-wide rich-text notes (last-write-wins, whole record overwrite), optionally resolving @-mentions of teammates. Use to log context, an update, or a note on a named deal.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-add-note
MCP tooldeal_add_note on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
notes_richstringYes
mention_user_oidsarray of stringNoMENTION_SYSTEM.md LAW MN-2 — structured teammate ids the @-editor emits, never scanned from notes_rich text

Response

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

deal_bulk_update

Apply exactly one bounded stage, status, tag, owner or scalar update across named deals.

Apply one declared update operation across a bounded set of deals. Stage, status, tags, and owners reuse existing owner bulk capabilities; scalar field changes are bounded Assistant orchestration over the existing single-deal update capability. Deletion is not supported.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-bulk-update
MCP tooldeal_bulk_update on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
operationstring (enum)YesOne of: set_stage, set_status, add_tags, set_owners, set_scalars.
deal_oidsarray of stringYesUp to 20000 items.
stage_oidstringNoPattern ^[0-9a-fA-F]{24}$.
statusstring (enum)NoOne of: WON, LOST, REOPEN.
lost_reason_oidstringNoPattern ^[0-9a-fA-F]{24}$.
lost_notestringNo
tag_oidsarray of stringNo
add_owner_oidsarray of stringNo
remove_owner_oidsarray of stringNo
namestringNo
company_oidstringNoPattern ^[0-9a-fA-F]{24}$.
amountnumberNo
currency_codestringNo
close_datestringNo
probability_overrideintegerNoFrom 0 to 100.
forecast_categorystringNo
next_stepstringNo
next_step_datestringNo
descriptionstringNo
tag_oids_replacearray of stringNo

Response

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

deal_create

Create a deal through the existing pipeline checks.

Create a new deal (defaults: team’s default pipeline, first open stage, owner = you, close date = end of the current month, currency = team home). Can create straight into a Won/Lost stage, attach a company, up to 50 contacts, tags, and line items. Use to log a new sales opportunity.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-create
MCP tooldeal_create on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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 255.
pipeline_oidstringNoPattern ^[0-9a-fA-F]{24}$.
stage_oidstringNoPattern ^[0-9a-fA-F]{24}$.
company_oidstringNoPattern ^[0-9a-fA-F]{24}$.
contact_oidsarray of stringNo
owner_oidsarray of stringNo
amountnumberNoFrom 0 to any.
currency_codestringNo
close_datestringNo
next_stepstringNoLength 0 to 255.
next_step_datestringNo
descriptionstringNo
line_itemsarray of objectNo
forecast_categorystring (enum)NoOne of: PIPELINE, BEST_CASE, COMMIT, OMITTED, CLOSED.
tag_oidsarray of stringNo
sourcestring (enum)NoWhere a deal was created from. One of: UI_FORM, API, IMPORT, WORKFLOW. Default "UI_FORM".
source_channelstringNoLength 0 to 200.
lost_reason_oidstringNoPattern ^[0-9a-fA-F]{24}$.
lost_notestringNo
custom_fieldsarray of objectNo

Response

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

deal_delete

Soft-delete one accessible deal after approval.

Delete a deal the user names explicitly.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-delete
MCP tooldeal_delete on https://mcp.prospeo.io
EffectDeletes or removes data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_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.

deal_get

Get full detail for one named deal or opportunity by its id: pipeline/stage/status, owners, amount/value and currency (plus home-currency conversion), close date, rotten/idle-day and activity signals, notes, tags, custom fields, and its linked contacts, meetings, and followers.

Get full detail for one named deal: pipeline/stage/status, owners, amount and currency (plus home-currency conversion), dates, notes, tags, custom fields, rotten/activity signals, and its linked contacts, meetings, and followers.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-get
MCP tooldeal_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesThe deal’s public id, taken from a deal search result. A deal’s name is not accepted here. Length 1 to 128.

Response

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

Link an accessible saved contact to one deal.

Link an existing saved contact to a deal (fluid, no roles, up to 50 contacts per deal). If the deal is on an open stage, this also syncs the contact’s own stage tracking.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-link-contact
MCP tooldeal_link_contact on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
contact_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.

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

deal_list_by_contact

List the open deals linked to a saved contact.

List a contact’s currently OPEN deals (derived purely via the deal-contact join; nothing stored on the contact). Never errors for zero results. Use to answer “does this person have any open deals?” from a contact context.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-list-by-contact
MCP tooldeal_list_by_contact on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
contact_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.

deal_lose

Mark one deal lost with the owner’s required reason.

Mark a deal LOST with a required reason (and optional note); lands on the pipeline’s first LOST-type stage unless stage_oid picks a specific one. Reversible via reopening the deal.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-lose
MCP tooldeal_lose on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
lost_reason_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
lost_notestringNo
stage_oidstringNoPattern ^[0-9a-fA-F]{24}$.

Response

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

deal_move_stage

Move a deal through the owner’s stage transition path.

Move a deal to a different stage (any pipeline). If the target stage is a WON or LOST type, this closes the deal in-place through the same win/lose flow (required-field gating, FX snapshot) instead of just relocating it.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-move-stage
MCP tooldeal_move_stage on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
stage_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
lost_reason_oidstringNoPattern ^[0-9a-fA-F]{24}$.
lost_notestringNo

Response

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

deal_reopen

Reopen one closed deal into an eligible open stage.

Reopen a closed (Won/Lost) deal back onto an open stage — either one the user names explicitly, or the deal’s last open stage / open-stage history / pipeline’s first open stage as a fallback chain.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-reopen
MCP tooldeal_reopen on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
stage_oidstringNoPattern ^[0-9a-fA-F]{24}$.

Response

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

Find deals or opportunities matching filters: pipeline, stage, owner, status (open/won/lost), amount range, close/created/last-activity dates, rotten-only, tags, lost reason, forecast category, source, followers, created-by, exact deal custom-field values, and free text, sorted and paginated.

Find deals matching structured criteria (pipeline, stage, owner, open/won/lost status, tags, amount range, close date, rotten-only) plus optional free text. Use to answer a filtered lookup like “open deals over $10k owned by X” rather than browsing the full table.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-search
MCP tooldeal_search on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page, per_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
pageintegerNo1-based page number. From 1 to any. Default 1.
per_pageintegerNoRows per page, 1-100. From 1 to 100. Default 25.
pipeline_oidstringNoRestrict to one pipeline.
scope_me_onlybooleanNoOnly deals the caller owns. Default false.
searchstringNoFree-text match on deal name or linked company name. Length 0 to 500.
sort_bystringNoOne of: name, amount, close_date, created_at, next_step_date, forecast_category, probability_override, amount_home, weighted_amount, days_in_stage, is_rotten, next_activity_at. An unrecognized value falls back to newest-created-first. Length 0 to 60.
sort_dirstring (enum)NoSort direction. One of: asc, desc. Default "desc".
stage_oidsarray of stringNoUp to 200 items.
statusstring (enum)NoSingle-value status filter (legacy alias for statuses[]). One of: OPEN, WON, LOST, DELETED.
statusesarray of string (enum)NoUp to 4 items. Items one of: OPEN, WON, LOST, DELETED.
owner_oidsarray of stringNoUp to 200 items.
company_oidstringNo
amount_minnumberNoFrom 0 to any.
amount_maxnumberNoFrom 0 to any.
close_date_fromstringNo
close_date_tostringNo
close_date_presetstringNoOne of: overdue, month, quarter, later (server-resolved preset). Length 0 to 40.
created_fromstringNo
created_tostringNo
created_presetstringNoOne of: 7d, 30d, 90d, month, quarter. Length 0 to 40.
stage_entered_fromstringNo
stage_entered_tostringNo
last_activity_fromstringNo
last_activity_tostringNo
last_activity_presetstringNoOne of: 7d, 30d, stale. Length 0 to 40.
next_step_fromstringNo
next_step_tostringNo
activity_statusstringNoLength 0 to 40.
activity_statusesarray of stringNoUp to 10 items.
rotten_onlybooleanNoOnly deals currently flagged rotten. Default false.
tag_oidsarray of stringNoUp to 200 items.
lost_reason_oidstringNo
lost_reason_oidsarray of stringNoUp to 200 items.
forecast_categorystring (enum)NoOne of: PIPELINE, BEST_CASE, COMMIT, OMITTED, CLOSED.
forecast_categoriesarray of string (enum)NoUp to 5 items. Items one of: PIPELINE, BEST_CASE, COMMIT, OMITTED, CLOSED.
forecast_category_is_nullbooleanNoMatch deals with no forecast category set (the §7.5 ‘Not set’ door). Default false.
sourcestring (enum)NoOne of: UI_FORM, API, IMPORT, WORKFLOW.
sourcesarray of string (enum)NoUp to 4 items. Items one of: UI_FORM, API, IMPORT, WORKFLOW.
follower_oidsarray of stringNoUp to 200 items.
created_by_oidstringNo
created_by_oidsarray of stringNoUp to 200 items.
custom_field_equalsarray of objectNoExact-match conditions on DEAL custom fields, all of which must hold (AND). Each field_oid may appear once. Up to 20 conditions. Up to 20 items.
account_list_oidsarray of stringNoUp to 200 items.
company_locationstringNoLength 0 to 200.
company_employee_count_minintegerNoFrom 0 to any.
company_employee_count_maxintegerNoFrom 0 to any.
company_industrystringNoLength 0 to 200.
company_keywordsstringNoLength 0 to 200.
company_technologiesarray of stringNoUp to 50 items.
company_funding_stagestringNoLength 0 to 100.
filter_groupobjectNo§7.3 advanced AND/OR builder — set instead of, never alongside, the flat filters above.

Response

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

deal_timeline

Get one deal’s activity timeline: stage changes, note edits, its own tasks, linked meetings, and every email/call against its linked contacts, newest first. Use to answer ‘what happened on this deal’, ‘when did this deal move to this stage’, ‘has anyone called or emailed about this deal or opportunity recently’.

Get a deal’s joined activity stream: stage-change/note-edit history plus its own tasks, linked meetings, and every email/call against its linked contacts, newest first. Use to answer “what’s happened on this deal” questions.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-timeline
MCP tooldeal_timeline on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesThe deal’s public id. Length 1 to 128.

Response

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

deal_update

Patch editable fields on one accessible deal.

Edit fields on an existing deal (name, company, amount/currency, close date, probability override, forecast category, next step, description, line items, tags, custom fields). Team-shared, no field-level permission gate. Use to update deal details the user names explicitly.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-update
MCP tooldeal_update on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
namestringNoLength 0 to 255.
company_oidstringNoPattern ^[0-9a-fA-F]{24}$.
amountnumberNoFrom 0 to any.
currency_codestringNo
close_datestringNo
probability_overrideintegerNoFrom 0 to 100.
forecast_categorystring (enum)NoOne of: PIPELINE, BEST_CASE, COMMIT, OMITTED, CLOSED.
next_stepstringNoLength 0 to 255.
next_step_datestringNo
descriptionstringNo
source_channelstringNoLength 0 to 200.
line_itemsarray of objectNo
tag_oidsarray of stringNo
custom_fieldsarray of objectNo

Response

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

deal_win

Mark one deal won using an eligible won stage.

Mark a deal WON; lands on the pipeline’s first WON-type stage unless stage_oid picks a specific one. Reversible via reopening the deal.

EndpointPOST https://api.prospeo.io/api/v2/tools/deal-win
MCP tooldeal_win on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
deal_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
stage_oidstringNoPattern ^[0-9a-fA-F]{24}$.

Response

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

lost_reason_list

List the team’s configured reasons a deal can be marked lost (e.g. price, timing, went with competitor), plus whether a custom freeform lost reason is allowed. Use to resolve a lost-reason name to its id before marking a deal lost, or to answer ‘why do deals get marked lost’ / ‘what lost reasons do we track’.

List the team’s configured “deal lost” reasons — name, active flag, display order — plus whether a freeform “Other” reason is allowed. Use to resolve a reason name to its oid before calling deal_lose, or to show what reasons exist.

EndpointPOST https://api.prospeo.io/api/v2/tools/lost-reason-list
MCP toollost_reason_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
include_inactivebooleanNoInclude deactivated lost reasons. False (default) returns only active ones. Default false.

Response

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

pipeline_list

List the team’s deal pipelines (sales funnels) and each pipeline’s ordered stages — pipeline names, default flag, stage names, stage type (OPEN/WON/LOST), win probability, rot window. Use to resolve a pipeline or deal-stage name to its id before creating, updating, or moving a deal, or to answer ‘what pipelines/stages do we have for deals’.

List the team’s deal pipelines, each with its full ordered stage set (names, types, win probabilities, rot windows). Use to resolve a pipeline or stage name to its oid before creating, updating, or moving a deal.

EndpointPOST https://api.prospeo.io/api/v2/tools/pipeline-list
MCP toolpipeline_list on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
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
include_archivedbooleanNoInclude archived pipelines. False (default) returns only live pipelines. Default false.

Response

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

Last updated on