Tasks
| Tool | What it does |
|---|---|
task_archive | Archive a pending task irreversibly after approval; a live sequence task releases its contact. |
task_bulk_update | Apply one approved action to selected tasks, reporting updated, skipped and failed counts. |
task_complete | Complete one task, supplying an outcome when it is a phone-call task. |
task_create | Create an ad-hoc task against an existing person, account or deal. |
task_get | Get full detail for one task by its id: task name, task type, status, priority, due date, assignees, the linked contact/account/deal record and company, the sequence the task belongs to, notes, and (for a completed or archived task) who closed the task and why. |
task_reassign | Add or remove task assignees, or clear the assignment explicitly. |
task_search | Search or list the team’s tasks by quick tab, assignee, task status, due date range, priority, task type, sequence, or linked contact/account/deal, with free text and pagination; also returns quick-tab counts, the due/overdue task badge, and facet counts. |
task_update | Update one pending task’s due date, priority, name, notes or social text. |
task_archive
Archive a pending task irreversibly after approval; a live sequence task releases its contact.
Archive a task the user explicitly names, closing it out without marking it done. Never suggest archiving proactively — always confirm first.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-archive |
| MCP tool | task_archive on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_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.
task_bulk_update
Apply one approved action to selected tasks, reporting updated, skipped and failed counts.
Bulk-apply one action — complete, archive, set due date, set priority, or reassign — to a set of tasks by oid in a single call (20,000-task cap).
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-bulk-update |
| MCP tool | task_bulk_update on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_oids | array of string | Yes | Up to 20000 items. |
action | string (enum) | Yes | One of: COMPLETE, ARCHIVE, SET_DUE, SET_PRIORITY, REASSIGN. |
due_at | string | No | |
due_timezone | string | No | Length 0 to 64. |
priority | string | No | |
add_assignee_oids | array of string | No | |
remove_assignee_oids | array of string | No | |
clear_assignees | boolean | No | Default false. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_complete
Complete one task, supplying an outcome when it is a phone-call task.
Mark a task done. For a sequence-linked task this advances the contact to the sequence’s next step; a phone-call task requires a logged call outcome before it can complete. The outcome Asked not to be called is accepted here only when the task’s call already has it logged, because it marks the contact Do Not Contact for the whole team: log it with call_log first, which asks for approval, then complete the task.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-complete |
| MCP tool | task_complete on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
call_log | object | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_create
Create an ad-hoc task against an existing person, account or deal.
Create an ad-hoc task (manual email, phone call, social action, or custom action) against one person, account, or deal, with a due date, priority, and assignees.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-create |
| MCP tool | task_create on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_type | string (enum) | Yes | Task channel — the manual step types (Automatic email is never a task). One of: MANUAL_EMAIL, PHONE_CALL, SOCIAL_SEND_CONNECT_REQUEST, SOCIAL_SEND_MESSAGE, SOCIAL_VIEW_PROFILE, SOCIAL_INTERACT_WITH_POST, CUSTOM_ACTION. |
record_type | string (enum) | No | What a task is attached to. Sequence tasks are always PERSON. One of: PERSON, ACCOUNT, DEAL. Default "PERSON". |
sequence_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
deal_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
saved_person_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
saved_company_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
name | string | No | |
notes | string | No | Default "". |
due_at | string | Yes | |
due_timezone | string | No | Length 0 to 64. |
priority | string | No | Default "MEDIUM". |
assignee_oids | array of string | No | |
social_message | string | No | |
connection_note | string | No | |
action_name | string | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_get
Get full detail for one task by its id: task name, task type, status, priority, due date, assignees, the linked contact/account/deal record and company, the sequence the task belongs to, notes, and (for a completed or archived task) who closed the task and why.
Fetch full detail for one task by its oid — status, due date, priority, assignees, linked record, notes, and (for a closed task) who closed it and why.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-get |
| MCP tool | task_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 | 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 |
|---|---|---|---|
task_oid | string | Yes | The task’s public id. Length 1 to 128. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_reassign
Add or remove task assignees, or clear the assignment explicitly.
Add and/or remove assignees on one task by delta (additions/removals apply on top of the current assignee set — any current assignee not named in remove_assignee_oids stays), or clear all assignees at once.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-reassign |
| MCP tool | task_reassign on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
add_assignee_oids | array of string | No | |
remove_assignee_oids | array of string | No | |
clear_all | boolean | No | Default false. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_search
Search or list the team’s tasks by quick tab, assignee, task status, due date range, priority, task type, sequence, or linked contact/account/deal, with free text and pagination; also returns quick-tab counts, the due/overdue task badge, and facet counts.
Search the team’s tasks by status, assignee, due-date range, priority, task type, or linked person/account/deal, with free text and pagination; also returns quick-tab counts, the nav badge count, and facet counts.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-search |
| MCP tool | task_search 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 | 1-based page number; fixed at 25 rows per page. From 1 to any. Default 1. |
quick_tab | string (enum) | No | Global Tasks page quick tab. One of: ALL, EMAILS, CALLS, SOCIALS, CUSTOMS, OVERDUE. Default "ALL". |
assignee_oid | string | No | One specific teammate. 400s if it cannot be resolved to a team member. |
unassigned_only | boolean | No | The ‘Nobody’ assignee facet. Default false. |
all_assignees | boolean | No | The ‘Anybody’ facet — bypasses the caller-only default. Default false. |
statuses | array of string (enum) | No | Up to 4 items. Items one of: PENDING, COMPLETED, ARCHIVED, AUTO_SKIPPED. |
search | string | No | Free-text match on task name or the linked contact/company name. Length 0 to 500. |
sequence_oid | string | No | Scope to one sequence’s Tasks tab. |
task_types | array of string (enum) | No | Up to 7 items. Items one of: MANUAL_EMAIL, PHONE_CALL, SOCIAL_SEND_CONNECT_REQUEST, SOCIAL_SEND_MESSAGE, SOCIAL_VIEW_PROFILE, SOCIAL_INTERACT_WITH_POST, CUSTOM_ACTION. |
record_type | string (enum) | No | Nested ‘Record type’ facet under Task type. One of: PERSON, ACCOUNT, DEAL. |
sequence_oids | array of string | No | Sequence facet (multi). Up to 200 items. |
priorities | array of string (enum) | No | Items one of: LOW, MEDIUM, HIGH. |
due_bucket | string (enum) | No | Independent of due_from/due_to. One of: OVERDUE, DUE_TODAY, ALL_UPCOMING. |
due_from | string | No | |
due_to | string | No | |
completed_from | string | No | |
completed_to | string | No | |
created_from | string | No | |
created_to | string | No | |
stage_ids | array of integer | No | Contact/Account CRM-shell stage ids (small team-scoped config ints, not record ids). Up to 200 items. |
stage_ids_exclude | array of integer | No | Up to 200 items. |
company_oids | array of string | No | Up to 200 items. |
person_oids | array of string | No | Up to 200 items. |
job_titles | array of string | No | Up to 50 items. |
deal_oids | array of string | No | The deal record page’s own ‘Tasks (N open)’ scope. Up to 200 items. |
step_indexes | array of integer | No | §8.13 per-sequence Tasks tab ‘Step’ facet. Up to 50 items. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
task_update
Update one pending task’s due date, priority, name, notes or social text.
Edit an open task’s due date, priority, notes, name, or (for social tasks) its drafted message/connection note. Changing the due date also shifts the task’s auto-skip window on a sequence-linked task.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/task-update |
| MCP tool | task_update on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| 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 |
|---|---|---|---|
task_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
due_at | string | No | |
due_timezone | string | No | Length 0 to 64. |
priority | string | No | |
notes | string | No | |
name | string | No | |
social_message | string | No | |
connection_note | string | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.