Goals

List sales goals

crm.goals.list

Lists the sales goals (targets) of the org, newest period first, paginated by cursor (limit up to 200): metric (revenue_won, deals_won, deals_created, activities_logged, calls_made, meetings_held), target, period with its start and end dates (calendar periods in UTC) and is_active (today falls inside it), team or individual owner with user_name, optional pipeline with pipeline_name, and the current value with when it was last computed. Whoever cannot see everyone's performance only gets the team goals and their own.

Scope

crm:read

Permission

View the module

MCP tool

crm_goals_listOn the full surface; on the compact one, mb_execute_operation with id: "crm.goals.list".

Declared cost: up to 202 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a sales goal

crm.goals.create

Creates a sales goal: metric, positive target, period (monthly, quarterly or yearly; the bounds snap to the calendar period that contains start_date, today by default), team_scope team or individual (individual needs user_id, a member of the org; a team goal has no owner and any user_id sent is ignored), optional pipeline_id and name. The current value is computed right away. The dry run runs the same checks (same errors: goal_owner_required, goal_owner_not_member) and its preview computes the value the goal would start with (counts goals, current_value, target and percent, the % of the target with one decimal) and says the metric, the period with its dates and the scope. Requires manage_goals (CRM admins).

Scope

crm:write

Permission

Edit in the module · CRM action: manage_goals

MCP tool

crm_goals_createOn the full surface; on the compact one, mb_execute_operation with id: "crm.goals.create".

Declared cost: up to 10000 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "team_scope": "individual",
  "metric": "revenue_won",
  "target": 0,
  "period": "monthly"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "team_scope": "individual",
  "metric": "revenue_won",
  "target": 0,
  "period": "monthly"
}'

Update a sales goal

crm.goals.update

Updates a goal's name, metric, target, team scope, owner (user_id), pipeline (null = all pipelines) or period; with none of them it answers no_changes (crm.goals.refresh recomputes the value). A team goal has no owner: moving a goal to team (or saving any change on a team goal that still kept one) clears user_id, so its progress counts the whole team. An individual goal needs an owner: a change to the scope or the owner that would leave it individual without user_id is goal_owner_required, and user_id must be a member (goal_owner_not_member). Changing the period moves the bounds to the calendar period of today. The current value is recomputed after saving. The dry run runs the same checks (same errors) and its preview computes the value with the change (counts goals, current_value, target, percent and previous_value, the value saved today), says the resulting metric, period dates and scope, and warns when the owner is cleared or the dates move. Requires manage_goals.

Scope

crm:write

Permission

Edit in the module · CRM action: manage_goals

MCP tool

crm_goals_updateOn the full surface; on the compact one, mb_execute_operation with id: "crm.goals.update".

Declared cost: up to 10001 reads and 2 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/crm/goals/{goal_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/crm/goals/{goal_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a sales goal

crm.goals.delete

Deletes a goal for good: goals have no trash, so it cannot be restored (the deals and activities it measured are untouched). Use crm.goals.update to change a goal instead of deleting and recreating it. Requires manage_goals.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

crm:write and “Allow deletions” (crm:delete in OAuth)

Permission

Edit in the module · CRM action: manage_goals

MCP tool

crm_goals_deleteOn the full surface; on the compact one, mb_execute_operation with id: "crm.goals.delete".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Recompute a goal's current value

crm.goals.refresh

Recomputes a goal's current value now from the deals or activities of its period (a daily job already does it for every goal) and returns it. Safe to repeat. The dry run computes the value without saving it (counts goals, current_value, target, percent and previous_value, the value saved today; the text says the metric and the period dates). Anyone with access to the CRM can refresh, as in the goals panel; it does not change the goal itself.

Scope

crm:write

Permission

View the module

MCP tool

crm_goals_refreshOn the full surface; on the compact one, mb_execute_operation with id: "crm.goals.refresh".

Declared cost: up to 10001 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/refresh" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/refresh" \
  -H "Authorization: Bearer $MB_TEST_KEY"