Contacts and accounts
| Tool | What it does |
|---|---|
account_timeline | Show one record’s owner activity, deals, open tasks, calls, meetings, recorded meetings and inbox conversations, with explicit coverage gaps. |
contacts_delete | Delete one accessible saved person or company after approval. |
custom_field_list | List the team’s profile field definitions and picklist options by object type. |
custom_field_set_value | Set or clear one typed custom-field value on an accessible record. |
record_company_people | List saved contacts linked to one accessible account. |
record_note_edit | Replace or clear the one team-shared note on a contact or account. |
record_set_stage | Set one saved person or company’s CRM stage. |
record_update_company | Patch editable fields on an existing saved account. |
record_update_person | Patch editable fields on an existing saved contact. |
saved_companies_search | Hydrate known saved company IDs; this tool does not apply audience filters. |
saved_people_search | Hydrate known saved person IDs; this tool does not apply audience filters. |
stage_list | List the team’s CRM stages for saved contacts (PERSON) or saved companies/accounts (COMPANY) — the record-status stage set shown on a contact or account record, separate from a deal’s pipeline stage. Resolves to Prospeo’s default stage set until the team customizes its own. |
account_timeline
Show one record’s owner activity, deals, open tasks, calls, meetings, recorded meetings and inbox conversations, with explicit coverage gaps.
Get one view of what has happened with a company or contact: its record activity, deals, open tasks and notes, calls (linked to the contact or to its current mobile), meetings the caller hosts or booked, recorded meetings the caller can see, and inbox conversations. Teammates’ unrecorded meetings and sent-only email are reported as unavailable, and every gap and cap is listed in the result.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/account-timeline |
| MCP tool | account_timeline on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Limit-based: limit. |
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 |
|---|---|---|---|
record_type | string (enum) | Yes | One of: PERSON, COMPANY. |
saved_oid | string | Yes | |
limit | integer | No | From 1 to 100. Default 100. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
contacts_delete
Delete one accessible saved person or company after approval.
Permanently delete one saved contact or account and cascade the removal across custom-field values, list memberships, notes/activity, and search indexes.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/contacts-delete |
| MCP tool | contacts_delete on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | Delete records (records.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 |
|---|---|---|---|
record_type | string (enum) | Yes | Which shell kind an endpoint operates on. One of: PERSON, COMPANY. |
saved_oid | string | Yes |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
custom_field_list
List the team’s profile field definitions and picklist options by object type.
List the team’s custom (profile) field definitions for people or companies — name, data type, shape, picklist options, and where each field originated (an import batch or a promoted list column).
| Endpoint | POST https://api.prospeo.io/api/v2/tools/custom-field-list |
| MCP tool | custom_field_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 | 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 |
|---|---|---|---|
object_type | string (enum) | No | One of: PERSON, COMPANY, DEAL. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
custom_field_set_value
Set or clear one typed custom-field value on an accessible record.
Write a value for one custom (profile) field onto a saved contact or account — everyday record editing, gated the same as shell-core updates.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/custom-field-set-value |
| MCP tool | custom_field_set_value on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create records (records.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 |
|---|---|---|---|
object_type | string (enum) | Yes | Which record class a custom field / list column attaches to (CRM_SHELL_V3 §9.1a, GLOBAL SETTINGS §7). DEAL fields are MANUAL + FORMULA only, have no LIST scope, and store their values on the Deal document (out of scope for the shell storage layer). One of: PERSON, COMPANY, DEAL. |
saved_oid | string | Yes | |
field_oid | string | Yes | |
value | string or integer or number or boolean or array of string or integer or number or boolean | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
record_company_people
List saved contacts linked to one accessible account.
List the contact shells linked to one saved account (the account’s People tab) — name, job title, stage, whether an email is on file, and when each was added.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/record-company-people |
| MCP tool | record_company_people 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 |
|---|---|---|---|
saved_oid | string | Yes |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
record_note_edit
Replace or clear the one team-shared note on a contact or account.
Save (or clear) the one shared rich-text note on a saved contact or account — explicit save, team-shared, last-write-wins.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/record-note-edit |
| MCP tool | record_note_edit on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create records (records.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 |
|---|---|---|---|
record_type | string (enum) | Yes | Which shell kind an endpoint operates on. One of: PERSON, COMPANY. |
saved_oid | string | Yes | |
notes_rich | string | No | Length 0 to 100000. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
record_set_stage
Set one saved person or company’s CRM stage.
Move a single saved contact or account to a pipeline stage. Everyday record editing — setting one record’s stage is intentionally NOT gated by the stage-management permission (only creating/editing/deleting stage definitions is).
| Endpoint | POST https://api.prospeo.io/api/v2/tools/record-set-stage |
| MCP tool | record_set_stage 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 |
|---|---|---|---|
record_type | string (enum) | Yes | Which stage set an endpoint operates on. One of: PERSON, COMPANY. |
saved_oid | string | Yes | |
stage_id | integer | Yes |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
record_update_company
Patch editable fields on an existing saved account.
Patch editable account shell-core fields (name, main website, social URL, location, HQ phone, employee count) on an owned saved account.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/record-update-company |
| MCP tool | record_update_company on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create records (records.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 |
|---|---|---|---|
saved_oid | string | Yes | |
name | string | No | Length 0 to 200. |
main_website | string | No | Length 0 to 500. |
social_url | string | No | Length 0 to 500. |
location_text | string | No | Length 0 to 500. |
location | object | No | |
phone | string | No | Length 0 to 40. |
employee_count | integer | No | From 0 to 100000000. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
record_update_person
Patch editable fields on an existing saved contact.
Patch editable contact shell-core fields (first/last name, job title, social URL, location, seniority, department) on an owned saved contact.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/record-update-person |
| MCP tool | record_update_person on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Create records (records.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 |
|---|---|---|---|
saved_oid | string | Yes | |
first_name | string | No | Length 0 to 100. |
last_name | string | No | Length 0 to 100. |
job_title | string | No | Length 0 to 200. |
social_url | string | No | Length 0 to 500. |
location_text | string | No | Length 0 to 500. |
location | object | No | |
seniority | integer | No | |
department | integer | No |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
saved_companies_search
Hydrate known saved company IDs; this tool does not apply audience filters.
Fetch full saved-company detail (firmographics, contacts, custom fields) for up to 100 companies by their exact ids.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/saved-companies-search |
| MCP tool | saved_companies_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 | 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 |
|---|---|---|---|
company_oids | array of string | Yes | Up to 100 items. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
saved_people_search
Hydrate known saved person IDs; this tool does not apply audience filters.
Fetch full saved-person detail (name, title, company, location, email/mobile reveal status, custom fields) for up to 100 people by their exact ids, plus the associated companies map.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/saved-people-search |
| MCP tool | saved_people_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 | 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 |
|---|---|---|---|
person_oids | array of string | Yes | Up to 100 items. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
stage_list
List the team’s CRM stages for saved contacts (PERSON) or saved companies/accounts (COMPANY) — the record-status stage set shown on a contact or account record, separate from a deal’s pipeline stage. Resolves to Prospeo’s default stage set until the team customizes its own.
List the team’s effective pipeline stages for people or companies — resolves to Prospeo’s hardcoded default set until the team has customized its own. Read-only; use before record_set_stage to resolve a stage name to its id.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/stage-list |
| MCP tool | stage_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 | 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 |
|---|---|---|---|
record_type | string (enum) | Yes | Which record type’s stage set to list: PERSON (saved contacts) or COMPANY (saved accounts). One of: PERSON, COMPANY. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.