Skip to Content

Scoring

ToolWhat it does
score_createSave a finished score draft as a custom score after the user approves. The plan’s custom-score limit is enforced when it is approved. Saving never replaces an existing primary score, but when the team has no primary score for that target the new score becomes the primary automatically, so say so before asking (check score_list). Use score_set_primary only when the user asks to switch.
score_distributionPreview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Counts only, never records.
score_draft_getCheck a score draft: still building, failed, or ready with its unsaved criteria in plain words.
score_draft_startStart an AI draft of a new score from a description of the ideal customer and the Context Center. Nothing is saved and no credits are used. Returns a job id to check with score_draft_get.
score_explain_recordExplain why up to 50 people or company records got their score: each criterion matched, not matched or unknown, with the record’s own value and the importance word. Criterion detail is returned for the first 3 records; ask again with fewer records for more.
score_getRead one score in plain words: its criteria with importance and values, label cut-offs, status and who built it.
score_listList the team’s lead scores for people and companies: name, whether it is an Auto-Score or custom, which is primary, criteria count, status and the custom-score plan limit.
score_regenerateRebuild the People or Companies Auto-Score from the Default Context Center after the user approves. It replaces the current Auto-Score criteria when the job finishes.
score_set_primaryMake one score the team’s primary for its target after the user approves. The Score column, tag and filter use the primary by default.

score_create

Save a finished score draft as a custom score after the user approves. The plan’s custom-score limit is enforced when it is approved. Saving never replaces an existing primary score, but when the team has no primary score for that target the new score becomes the primary automatically, so say so before asking (check score_list). Use score_set_primary only when the user asks to switch.

Save a finished score draft as a new custom score for the team, after the user approves. The draft comes from score_draft_start and score_draft_get. The first score saved for a target becomes its primary. Free and Starter teams can keep 2 custom scores in total, and the owner enforces that limit when the approval runs.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-create
MCP toolscore_create on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionManage scores (scoring.manage)
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
draft_job_idstringYesThe job id of a finished score draft, from score_draft_start. Pattern ^[a-f0-9]{32}$.
namestringNoReplace the drafted name. Length 0 to 60.
thresholdsobjectNoReplace the default 80, 50 and 20 label cut-offs.

Response

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

score_distribution

Preview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Counts only, never records.

Preview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Returns counts only, never records. The all-records scope is an estimate.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-distribution
MCP toolscore_distribution 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
score_oidstringNoA saved score id. Give this or draft_job_id, not both. Pattern ^[a-fA-F0-9]{24}$.
draft_job_idstringNoThe job id of a finished score draft. Give this or score_oid, not both. Pattern ^[a-f0-9]{32}$.
scopestring (enum)Nosaved = the team’s saved records, list = one list, all = every record (an estimate). One of: saved, all, list. Default "saved".
list_oidstringNoThe list id. Required for scope list and not allowed otherwise. Pattern ^[a-fA-F0-9]{24}$.

Response

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

score_draft_get

Check a score draft: still building, failed, or ready with its unsaved criteria in plain words.

Check a score draft started by score_draft_start. Returns still building, failed, or the finished unsaved draft with its criteria in plain words (criterion, importance, values). Nothing is saved.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-draft-get
MCP toolscore_draft_get on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionManage scores (scoring.manage)
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
job_idstringYesThe job id returned by score_draft_start. Pattern ^[a-f0-9]{32}$.

Response

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

score_draft_start

Start an AI draft of a new score from a description of the ideal customer and the Context Center. Nothing is saved and no credits are used. Returns a job id to check with score_draft_get.

Start an AI draft of a new score from a description of the ideal customer and the Default Context Center. Nothing is saved and no credits are debited. Returns a job id to check with score_draft_get.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-draft-start
MCP toolscore_draft_start on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionManage scores (scoring.manage)
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
targetstring (enum)Yespeople to score contacts, company to score accounts. It cannot change once a score is saved. One of: people, company.
descriptionstringYesThe ideal customer in the user’s own words, for example VP of Sales at US software companies with 50 to 500 employees. Length 3 to 1000.
namestringNoAn optional name for the score. It can be changed when the score is saved. Length 0 to 60.

Response

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

score_explain_record

Explain why up to 50 people or company records got their score: each criterion matched, not matched or unknown, with the record’s own value and the importance word. Criterion detail is returned for the first 3 records; ask again with fewer records for more.

Explain why up to 50 people or company records got their score. Every criterion is matched, not matched or unknown, with the record’s own value and the importance word (points for a numeric score). Criterion detail is returned for the first 3 records; every record gets its score, label and counts.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-explain-record
MCP toolscore_explain_record 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
targetstring (enum)Yespeople for contacts, company for accounts. Must match the records and the score. One of: people, company.
recordsarray of objectYesBetween 1 and 50 records of the target type, one batch. Up to 50 items.
score_oidstringNoExplain with this score; omit to use the team’s primary score for the target. Pattern ^[a-fA-F0-9]{24}$.

Response

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

score_get

Read one score in plain words: its criteria with importance and values, label cut-offs, status and who built it.

Read one team score in plain words: its criteria with importance and values, label cut-offs, whether it is the primary, its generation status for Auto-Scores, and who built it.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-get
MCP toolscore_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
score_oidstringYesThe score id returned by score_list. Pattern ^[a-fA-F0-9]{24}$.

Response

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

score_list

List the team’s lead scores for people and companies: name, whether it is an Auto-Score or custom, which is primary, criteria count, status and the custom-score plan limit.

List the team’s scores for people and companies: name, Auto-Score or custom, primary flag, criteria count, status, and the plan’s custom-score limit. An optional target narrows the list.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-list
MCP toolscore_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
targetstring (enum)NoOnly scores for people or for companies; omit for both. One of: people, company.

Response

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

score_regenerate

Rebuild the People or Companies Auto-Score from the Default Context Center after the user approves. It replaces the current Auto-Score criteria when the job finishes.

Rebuild the People or Companies Auto-Score from the Default Context Center, after the user approves. The replacement happens in the background; a previously ready score stays active if the rebuild fails.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-regenerate
MCP toolscore_regenerate on https://mcp.prospeo.io
EffectDeletes or removes data.
CreditsFree, uses no credits.
PermissionManage scores (scoring.manage)
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
targetstring (enum)YesWhich Auto-Score to rebuild. One of: people, company.

Response

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

score_set_primary

Make one score the team’s primary for its target after the user approves. The Score column, tag and filter use the primary by default.

Make one score the team’s primary for its target, after the user approves. The Score column, the tag and the Scoring filter use the primary by default. Another score can be made primary again at any time.

EndpointPOST https://api.prospeo.io/api/v2/tools/score-set-primary
MCP toolscore_set_primary on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionManage scores (scoring.manage)
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
score_oidstringYesThe score id returned by score_list. Pattern ^[a-fA-F0-9]{24}$.

Response

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

Last updated on