AI

Performance of the CRM AI team

crm.ai.performance

Performance of the CRM AI team (operative positions such as the Setter, the Qualifier or the Seller) for a period, start and end (both required, epoch ms): the roster, AI conversations (states) created in the period and how many are still active, meetings booked vs a human baseline (won rate of the deals created in the period with a human owner), average and median time to booking vs time to win, and why finished conversations were handed off or closed (explicit request, stalled, guardrail, no AI credits, disqualified). Reads at most 2,000 AI states and 2,000 deals; truncated: true when a cap was hit, and truncation says which: states (the AI side counts only the first 2,000 states of the period) or human_deals (the human baseline comes from the first 2,000 deals of the period, not all of them, so its rate is not comparable: narrow the period). Org-wide numbers, as in the app. Use crm.ai_team.positions.list for the positions themselves.

Scope

crm:read

Permission

View the module · CRM action: view_performance

MCP tool

crm_ai_performanceOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.performance".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/crm/ai/performance?start=0&end=0" \
  -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/ai/performance?start=0&end=0" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Run the AI Deal Coach on a deal

crm.ai.deal_coach

Runs the CRM's AI Deal Coach on one deal and saves its note on the deal (ai_coach_note, the note the deal's Coach card shows; it replaces the previous one). The coach is the AI agent chosen in CRM settings → AI scoring → Coach, with that block's focus, offer context and things to avoid; it reads the deal (stage and days in it, value, owner, AI score, custom fields), its company, up to 6 contacts and the last 8 activities. Returns the saved note plus its parts: summary, next_best_action, 2-3 recommendations with priority and a risk_level (low, medium, high). Use it when asked what to do next with a deal. It does not move, edit or contact anything. language (es, en, pt-BR) defaults to the caller's language. The coach must be turned on (409 coach_not_configured). Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. If the AI fails, or answers with an empty note (an answer that cannot be read at all counts as empty), nothing is saved and nothing is charged (502 ai_generation_failed, or 429 external_rate_limited when the AI provider is limiting); an answer that comes back malformed is charged and nothing is saved either (502 ai_generation_failed). Takes several seconds. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_deal; a seller with restricted scope only coaches deals they can work. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

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

Permission

Edit in the module

MCP tool

crm_ai_deal_coachOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.deal_coach".

Declared cost: up to 50 reads and 1 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-coach" \
  -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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Draft an email for a deal with AI

crm.ai.draft_email

Writes a draft of one outbound sales email for a deal with AI (Gemini Pro) and returns it: subject, plain_body and a simple html_body (p, br, strong, em, a, lists; sanitized). It uses the deal (value, status, owner, company, primary contact and email) and the subjects of its last 5 activities (never email bodies), with a tone (formal, casual, direct; default direct), an intent (follow_up by default, intro, proposal, check_in, break_up, demo_request or custom), optional additional_context (up to 1,000 characters) and an optional seed_subject to adapt. language (es, en, pt-BR) defaults to the caller's language. It saves nothing and sends nothing: to send it use crm.email.send after the person reviews it. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. If the AI fails or returns an empty draft (an answer that cannot be read counts as empty), nothing is charged (502 ai_generation_failed, or 429 external_rate_limited when the AI provider is limiting). Not idempotent: send an Idempotency-Key to retry safely. Requires send_email on the deal. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

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

Permission

Edit in the module

MCP tool

crm_ai_draft_emailOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.draft_email".

Declared cost: up to 25 reads and 3 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-email-draft" \
  -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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Score a deal with AI

crm.ai.score_deal

Scores a deal (0-100) with the AI agent and criteria of the deals block in CRM settings → AI scoring, using the firmographics of one of its persons (person_id; default the deal's primary person), its source channel and value, and saves the result on the deal (ai_scoring, and ai_score for sorting), replacing the previous score. The score is a hybrid: 40% rules (email, phone, company, role, source) and 60% AI; it returns score, rules_score, ai_score, recommendation (qualified, needs_review, not_qualified), a short reasoning and the rule signals. If the AI fails, the score is rules only (it says so in reasoning) and nothing is charged; if the AI answers with something that cannot be used, the score is rules only too and that answer is charged. It runs even if automatic deal scoring is off. Errors: 409 deal_without_person when the deal has no primary person and no person_id is sent; 400 person_not_in_deal when person_id is not linked to the deal. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_deal; a seller with restricted scope only scores deals they can work. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

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

Permission

Edit in the module

MCP tool

crm_ai_score_dealOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.score_deal".

Declared cost: up to 20 reads and 1 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-score" \
  -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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Score a prospect with AI

crm.ai.score_prospect

Scores an inbox prospect (0-100) with the AI agent and criteria of the prospects block in CRM settings → AI scoring, using the linked contact's firmographics (when there is one), the prospect's title, custom fields, source channel and value, and saves the result on the prospect (ai_scoring, and ai_score for sorting), replacing the previous score. Hybrid: 40% rules and 60% AI; returns score, rules_score, ai_score, recommendation (qualified, needs_review, not_qualified), a short reasoning and the rule signals. If the AI fails, the score is rules only and nothing is charged; if the AI answers with something that cannot be used, the score is rules only too and that answer is charged. It runs even if automatic scoring is off for the prospect's lead source. For several prospects use crm.ai.bulk.score_prospects. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_prospect. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).

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

Permission

Edit in the module

MCP tool

crm_ai_score_prospectOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.score_prospect".

Declared cost: up to 20 reads and 1 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/ai-score" \
  -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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Score many prospects with AI

crm.ai.bulk.score_prospects

Scores up to 50 prospects with AI, like crm.ai.score_prospect one by one (5 at a time; repeated ids count once), and saves each score on its prospect. Ids that do not exist, and prospects the matrix does not let the caller edit (another person's, for a seller), are skipped. Returns scored, failed (everything not scored) and one row per id with its status (scored, not_found, denied, failed) and score. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. The credit check covers the whole batch before the first call. Bulk: outside the app it needs a dry run (it previews how many will be scored, which are skipped and the estimated credits, without calling the AI) and then the confirm_token. Takes up to a minute with 50 prospects. Not idempotent: send an Idempotency-Key to retry safely. Requires edit access to the CRM; edit_prospect is checked per prospect.

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

Permission

Edit in the module

MCP tool

crm_ai_bulk_score_prospectsOn the full surface; on the compact one, mb_execute_operation with id: "crm.ai.bulk.score_prospects".

Declared cost: up to 320 reads and 50 writes per call (they count against the daily quota). Touches an external platform (ai): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/ai-score" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "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. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.