Skip to Content
Tools referenceContacts and accounts

Contacts and accounts

ToolWhat it does
account_timelineShow one record’s owner activity, deals, open tasks, calls, meetings, recorded meetings and inbox conversations, with explicit coverage gaps.
contacts_deleteDelete one accessible saved person or company after approval.
custom_field_listList the team’s profile field definitions and picklist options by object type.
custom_field_set_valueSet or clear one typed custom-field value on an accessible record.
record_company_peopleList saved contacts linked to one accessible account.
record_note_editReplace or clear the one team-shared note on a contact or account.
record_set_stageSet one saved person or company’s CRM stage.
record_update_companyPatch editable fields on an existing saved account.
record_update_personPatch editable fields on an existing saved contact.
saved_companies_searchHydrate known saved company IDs; this tool does not apply audience filters.
saved_people_searchHydrate known saved person IDs; this tool does not apply audience filters.
stage_listList 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.

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

ParameterTypeRequiredDescription
record_typestring (enum)YesOne of: PERSON, COMPANY.
saved_oidstringYes
limitintegerNoFrom 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/contacts-delete
MCP toolcontacts_delete on https://mcp.prospeo.io
EffectDeletes or removes data.
CreditsFree, uses no credits.
PermissionDelete records (records.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
record_typestring (enum)YesWhich shell kind an endpoint operates on. One of: PERSON, COMPANY.
saved_oidstringYes

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).

EndpointPOST https://api.prospeo.io/api/v2/tools/custom-field-list
MCP toolcustom_field_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
object_typestring (enum)NoOne 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/custom-field-set-value
MCP toolcustom_field_set_value on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate records (records.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
object_typestring (enum)YesWhich 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_oidstringYes
field_oidstringYes
valuestring or integer or number or boolean or array of string or integer or number or booleanNo

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/record-company-people
MCP toolrecord_company_people 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
saved_oidstringYes

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/record-note-edit
MCP toolrecord_note_edit on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate records (records.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
record_typestring (enum)YesWhich shell kind an endpoint operates on. One of: PERSON, COMPANY.
saved_oidstringYes
notes_richstringNoLength 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).

EndpointPOST https://api.prospeo.io/api/v2/tools/record-set-stage
MCP toolrecord_set_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
record_typestring (enum)YesWhich stage set an endpoint operates on. One of: PERSON, COMPANY.
saved_oidstringYes
stage_idintegerYes

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/record-update-company
MCP toolrecord_update_company on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate records (records.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
saved_oidstringYes
namestringNoLength 0 to 200.
main_websitestringNoLength 0 to 500.
social_urlstringNoLength 0 to 500.
location_textstringNoLength 0 to 500.
locationobjectNo
phonestringNoLength 0 to 40.
employee_countintegerNoFrom 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/record-update-person
MCP toolrecord_update_person on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionCreate records (records.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
saved_oidstringYes
first_namestringNoLength 0 to 100.
last_namestringNoLength 0 to 100.
job_titlestringNoLength 0 to 200.
social_urlstringNoLength 0 to 500.
location_textstringNoLength 0 to 500.
locationobjectNo
seniorityintegerNo
departmentintegerNo

Response

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

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/saved-companies-search
MCP toolsaved_companies_search 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
company_oidsarray of stringYesUp to 100 items.

Response

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

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.

EndpointPOST https://api.prospeo.io/api/v2/tools/saved-people-search
MCP toolsaved_people_search 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
person_oidsarray of stringYesUp 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.

EndpointPOST https://api.prospeo.io/api/v2/tools/stage-list
MCP toolstage_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
record_typestring (enum)YesWhich 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.

Last updated on